Moogsoft Docs

addValueRecipe

A Graze API POST request that creates a new Cookbook Recipe using Value Recipe or Value Recipe v2 recipe types. See Recipe Types for more information.

Back to Graze API EndPoint Reference.

Request arguments

Endpoint addValueRecipe takes the following request arguments:

Name

Type

Required

Description

auth_token

String

Yes

A valid auth_token returned from the authenticate request. See the authenticate endpoint for more information.

cookbook

List of Strings

No

A list of the Cookbooks that this Recipe belongs to. You can add Cookbooks here or, when you create a Cookbook, you can assign the Recipes to it.

name

String

Yes

Name of the Recipe. Use a unique and descriptive name.

description

String

No

Description of the Recipe. Default is the Recipe name.

version

String

No

Defines whether the Recipe uses Value Recipe or Value Recipe v2. Valid values are V1 for the Value Recipe and V2 for Value Recipe v2. Default is V2. See Recipe Types for more information. Use addBotRecipe if you want to create a Bot Recipe.

alert_threshold

Positive Integer

No

Minimum number of alerts required before Cookbook creates a Situation.

When Cookbook determines the number of alerts required to create a Situation, it compares the alert threshold values in the Cookbook Recipe and in the merge group that the Cookbook Recipe belongs to, and it uses the higher value. If you are using the default merge group which has an alert threshold of 2, Cookbook will never create a Situation containing a single alert. If you want Moogsoft AIOps to create Situations with a single alert, consider changing the alert threshold in the default merge group to 1 or creating custom merge groups. See Configure Merge Groups for more information on updating the default merge group and setting up custom merge groups.

trigger

String

No

A filter that determines the alerts that Cookbook considers for Situation creation. Cookbook includes alerts that match the trigger filter. By default Cookbook only includes alerts with a severity of 'Critical'. For details on creating a filter, see Filter Search Data. To set a vertex entropy trigger filter, see Set Up Vertex Entropy for more information. Default is an empty string.

exclusion

String

No

A filter that determines the alerts to exclude from Situation creation. Cookbook ignores alerts that match the exclusion filter. For details on creating a filter, see Filter Search Data. To set a vertex entropy exclusion filter, see Set Up Vertex Entropy for more information. Default is an empty string.

seed_alert

String

No

A filter that determines whether to create a Situation from a seed alert. The seed alert must meet both the trigger, exclusion and seed_alert criteria to create a Situation. Cookbook considers subsequent alerts for clustering if they meet the trigger and exclusion filter criteria. Alerts that arrive prior to the seed alert that met the trigger and exclusion filter criteria do not form Situations. For details on creating a filter, see Filter Search Data. To set a vertex entropy seed alert filter, see Set Up Vertex Entropy for more information. Default is an empty string.

rate

Double

No

Rate, in number of alerts per second. Cookbook clusters alerts if they arrive at a higher rate than is specified here. Cookbook uses rate together with min_sample_size and max_sample_size to determines whether to cluster alerts into Situations. See Cookbook and Recipe Examples for more information. Default is 0 which means that Cookbook does not use the rate to cluster alerts.

min_sample_size

Positive Integer

No

Number of alerts that must arrive before the Cookbook starts to calculate the alert rate. See Cookbook and Recipe Examples for more information. Default is 5. Valid only if rate is non-zero.

max_sample_size

Positive Integer

No

Maximum number of alerts that are considered in the alert rate calculation. When more than this number of alerts have arrived, Cookbook discards the oldest alerts and calculates the alert rate based on the number of alerts in the max_sample_size. See Cookbook and Recipe Examples for more information. Default is 10. Valid only if rate is non-zero.

cook_for

Positive Integer

No

Minimum time period, in seconds, that Cookbook clusters alerts for before the Recipe resets and starts a new cluster. See Cookbook and Recipe Examples for more information. Default is 3600 seconds (1 hour).

If you set a different cook_for time for a Recipe, it overrides the Cookbook value. Recipes without a cook_for time inherit the value from the Cookbook.

cook_for_extension

Positive Integer

No

Time period that Cookbook can extend clustering alerts for before the Recipe resets and starts a new cluster. Setting this value enables the cook for auto-extension feature for this Cookbook. As Cookbook receives related alerts, it continues to extend the total clustering time until the max_cook_for period is reached. Used in conjunction with the max_cook_for value, the cook_for_extension period helps to ensure that Cookbook continues to cluster alerts together that are related to the same failure. The cook_for_extension period only applies to new related alerts; it does not apply to existing alerts that are updated with new events. See Cookbook and Recipe Examples for more information. Default is 0.

If you set a different cook_for_extension time for a Recipe, it overrides the Cookbook value. Recipes without a cook_for_extension time inherit the value from the Cookbook.

max_cook_for

Positive Integer

No

Maximum time period that Cookbook clusters alerts for before the Recipe resets and starts a new cluster. It works in conjunction with the cook_for_extension time to help ensure that Cookbook continues to cluster alerts together that are related to the same failure. This value is ignored unless the cook_for_extension time is specified. If cook_for_extension is set and this value is not set, the default is three times the cook_for value. See Cookbook and Recipe Examples for more information. Default is 0.

If you set a different max_cook_for time for a Recipe, it overrides the Cookbook value. Recipes without a max_cook_for value inherit the value from the Cookbook.

cluster_by

String

No

Determines Cookbook's clustering behavior. Set to an empty string to use the Cookbook cluster_by setting. Set to first_match so that Cookbook adds alerts to the first cluster over the similarity threshold value. Set to closest_match to add alerts to the cluster with the highest similarity greater than the similarity threshold value. This option may be less efficient because Cookbook needs to compare alerts against each cluster in a Recipe. Default is an empty string which means the Recipe uses the Cookbook setting.

If you set a different cluster_by value for a Recipe, it overrides the Cookbook value. Recipes without a cluster_by time inherit the value from the Cookbook.

matcher

JSON Structure

Yes

A JSON structure containing:

  • hop_limit: Maximum number of hops between the alert source nodes in order for the alerts to qualify for clustering. Moogsoft AIOps measures hop limit from the first alert that formed the Situation and always follows the shortest possible route in the network. A hop is the jump between two directly connected nodes in a network. For more information on hops, see Vertex Entropy. To set a hop limit, see Set Up Vertex Entropy for more information.

    You can only use a hop limit if you have imported your network topology into the system. See Import a Topology for details.

  • components: Values that alerts must match for Cookbook to include them in a Situation. You can provide multiple values such as source, description, service or custom info fields. An array of JSON objects, each containing:

    Name

    Type

    Required

    Description

    name

    String

    Yes

    Name of the component.

    similarity

    Double

    Yes

    Similarity threshold that the component must meet for Cookbook to cluster the alert into a Situation.

    shingle_size

    Integer

    No

    Shingle size for Cookbook to use to determine the similarity between different strings. The shingle size is only valid for Recipe Value v2 recipes. Default is -1 which means that Cookbook uses words to determine similarity. See Recipe Types for more details.

    treat_as

    String

    No

    Determines whether Cookbook treats the component as a string or matches each value in the list individually. See Recipe Types for details. Valid values are List and String. Default is String.

    case_sensitive

    Boolean

    No

    Enables or disables case sensitive when comparing strings. Case sensitivity is only valid for Recipe Value recipes. See Recipe Types for more details. Default is true which means that strings are treated as case sensitive.

Response

Endpoint addValueRecipe returns the following response:

Examples

The following examples demonstrate typical use of endpoint addValueRecipe:

Request example

Example cURL request to add a new Recipe "GrazeRecipe2":

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addValueRecipe" -H "Content-Type: application/json; charset=UTF-8" -d '{"cookbook" : "GrazeCook1", "name": "GrazeRecipe2", "alert_threshold" : 1,
"matcher" : { "hop_limit" : 0},
 "components" :  [{ "name": "custom_1",
      "similarity": 0.2,
       "shingle_size": 2 } ]
       }'
Response example
In this section: