Skip to main content

addCookbook

A Graze API POST request that creates a new Cookbook.

Back to Graze API EndPoint Reference.

Request arguments

Endpoint addCookbook takes the following request arguments:

Name

Type

Required

Description

auth_token

String

Yes

A valid auth_token returned from the authenticate request. Alternatively, basic authenticate headers can be used in place of this parameter. See the authenticate endpoint for more information and usage examples.

name

String

Yes

Name of the Cookbook. Must be unique.

description

String

No

Description of the Cookbook.

process_output_of

List of Strings

No

Defines the source of the alerts that Cookbook processes. You can specify none, one or more Moolets. Typically Cookbook processes the output of its direct upstream neighbor in the processing chain. Usually this is "Alert Workflows" which are the output from the Alert Workflow Engine.

cluster_by

String

No

Determines Cookbook's clustering behavior. 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 first_match.

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

entropy_threshold

Number

No

Minimum entropy value an alert must have in order for Cookbook to consider it for clustering it into a Situation. A value between 0 and 1. Only relevant if threshold_type is set to explicit_value. If used, Cookbook does not cluster any alerts with an entropy value below the threshold into Situations. Default is 0.0 which means that Cookbook processes all alerts.

threshold_type

String

No

cook_for

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

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

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.

scale_by_severity

Boolean

No

Determines whether Cookbook ignores alerts with a severity of 0 (Clear). Set to true if you want Cookbook to ignore alerts with a severity of 0 (Clear). Set to false if you want Cookbook to include alerts with a severity of 0 (Clear).Default is false.

first_recipe_match_only

Boolean

No

Defines whether Cookbook treats Recipes in priority order. If set to true, Cookbook adds an alert to a cluster created by the highest priority Recipe that meets the clustering criteria. The priority order is defined by the order of the Recipes in the recipes list. If an alert appears in a Situation that a recipe with a low priority order creates, it may reappear in a Situation that a Recipe with a higher priority creates. If set to false, Cookbook adds an alert to clusters in all the Recipes that meet the clustering criteria. Default is false.

recipes

List of Strings

Yes

A list of the Recipes in this Cookbook. You must supply at least one Recipe. If you set first_recipe_match_only to first_match, Cookbook uses the order of the Recipes in this list to determine their priority. The first Recipe has the highest priority.

run_on_startup

Boolean

No

Whether Cookbook should start when Moogfarmd starts. Default is true.

moobot

String

No

The Moobot you want Cookbook to use if there are any Bot Recipes. See Recipe Types for more information. Default is Cookbook.js.Recipe Types

Response

Endpoint addCookbook returns the following response:

This endpoint returns an error code if the values of entropy_threshold and threshold_type are inconsistent. For example, if the entropy_threshold is set to 0.4 and threshold_type is set to global.

Successful requests return a JSON object containing the following:

Name

Type

Description

id

Integer

ID of the new Cookbook.

Examples

The following examples demonstrate typical use of endpoint addCookbook:

Request examples

Example cURL request to create a new Cookbook "GrazeCookBook6" using an entropy threshold with an explicit value for this Cookbook of 0.25:

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addCookbook" -H "Content-Type: application/json; charset=UTF-8" -d 
'{ 
    "name": "GrazeCookBook6", 
    "process_output_of": ["Alert Workflows"], 
    "recipes": ["Description","Source"], 
    "run_on_startup":false, 
    "first_recipe_match_only":true}, 
    "entropy_threshold" : 0.25, 
    "threshold_type": "explicit_value" 
}'

Example cURL request to create a new Cookbook "GrazeCookBook7" using entropy thresholds set up for individual managers.

curl -X POST -u graze:graze -k -v "https://localhost/graze/v1/addCookbook" -H "Content-Type: application/json; charset=UTF-8" -d 
'{ 
    "name": "GrazeCookBook7", 
    "process_output_of": ["Alert Workflows"], 
    "recipes": ["GrazeRecipe1","GrazeRecipe2","GrazeRecipe3"], 
    "run_on_startup":false, 
    "first_recipe_match_only":true}, 
    "threshold_type": "manager" 
}'

Response example

Successful response providing the ID of the new Cookbook that has been created:

{
    "id": 2
}