Moogsoft Docs

Cookbook and Recipe Reference

This is a reference for the Cookbook Sigaliser algorithm and its associated Recipes. The Cookbook configuration properties are found in $MOOGSOFT_HOME/config/moolets/cookbook.conf.

Moolet
name

Name of the Cookbook Sigaliser algorithm. Do not change.

Type: String

Required: Yes

Default: "Cookbook"

class

Moolet class name. Do not change.

Type: String

Required: Yes

Default: "CCookbook"

run_on_startup

Determines whether Cookbook runs when Moogsoft AIOps starts. If you enable this property, Cookbook captures all alerts from the moment the system starts, without you having to configure or start it manually.

Type: Boolean

Required: No

Default: false

metric_path_moolet

Determines whether Moogsoft AIOps includes Cookbook in the Event Processing metric for Self Monitoring.

Type: Boolean

Required: No

Default: true

moobot

Specifies which associated Moobot the Cookbook Moolet loads at startup.

Type: String

Required: Yes

Default: "Cookbook.js"

process_output_of

Defines the Moolet source of the alerts for Cookbook.

Type: List

Required: Yes

One of: AlertBuilder, AlertRulesEngine, MaintenanceWindowManager, EmptyMoolet

Default: "MaintenanceWindowManager"

Algorithm
membership_limit

Maximum number of Situations an alert can be part of. This does not impact alerts in merged Situations. Smaller limits result in fewer Situations with many alerts and many Situations with fewer associated alerts. Larger limits result in many Situations with few alerts and a few Situations with many alerts. The optimal value is between 1 and 5.

Type: Integer

Required: Yes

Default: 1

scale_by_severity

Enables Cookbook to ignore alerts with a severity of 0 (Clear).

Type: Boolean

Required: No

Default: False

entropy_threshold

Minimum entropy value that an alert must have for Cookbook to consider it for clustering into a Situation. Cookbook does not include any alerts with an entropy value below the threshold in Situations. Set to a value between 0.0 and 1.0. The default of 0.0 means Cookbook processes all alerts.

Type: Decimal

Required: No

Default: 0.0

single_recipe_matching

Enable single_recipe_matching for Cookbook to treat Recipes in priority order, based on the order of configuration in cookbook.conf. The first recipe in the list takes highest priority. 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.

Type: Boolean

Required: No

Default: false

cluster_match_type

Defines how Cookbook matches clusters. You can select the first_match in order so Cookbook adds alerts to the first cluster over the similarity threshold value. This is the default behavior for Cookbook. Alternatively, select closest_matchto 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. The Recipe-level match type configuration overrides the Cookbook-level definition.

Type: List

Required: No

One of: first_match, closest_match

Default: "first_match"

cook_for

Minimum time period, in seconds, that Cookbook clusters alerts for before the Recipe resets and determines when to start a new cluster. You can set a different cook_for time for a Recipe, and this overrides the Cookbook value. Recipes without cook_for values inherit the value from the Cookbook.

Type: Integer

Required: No

Default: "5000"

cook_for_extension

Time period, in seconds, 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 helps to ensure that Cookbook continues to cluster alerts together that are related to the same failure. The cook_for_extension only applies to new related alerts; it does not apply to existing alerts that are updated with new events.

For example, cook_for is set to 1 hour (3,600 seconds), cook_for_extension is set to 30 minutes (1,800 seconds), and max_cook_for is set to 2 hours (7,200 seconds). If Cookbook receives a new related alert 40 minutes after the Recipe started clustering alerts, the Recipe extends the total clustering time by 30 minutes from that time to 1 hour and 10 minutes, then:

  • If Cookbook receives another alert 1 hour and 5 minutes after the Recipe started clustering, because Cookbook received it within the extended time of 1 hour and 10 minutes, Cookbook further extends the total clustering time to 1 hour and 35 minutes. Cookbook continually extends the total clustering time as it receives more related alerts, provided that they are received within the extended time. Cookbook can extend the total clustering time until the max_cook_for time is reached. If Cookbook receives further related alerts after the max_cook_for time of 2 hours has elapsed, the Recipe resets and adds them to a new cluster.

  • If Cookbook does not receive any further alerts, it stops clustering alerts after the extended time of 1 hour and 10 minutes elapses. If Cookbook then receives another alert after this time has elapsed, the Recipe starts a new cluster.

You can set a different cook_for_extension time for a Recipe, and this overrides the Cookbook value. Recipes without cook_for_extension values inherit the value from the Cookbook.

Type: Integer

Required: No

Default: "1000"

max_cook_for

Maximum time period, in seconds, that Cookbook can extend clustering alerts for before the Recipe resets and starts a new cluster. It is used in conjunction with the cook_for_extension to help to ensure that Cookbook continues to cluster alerts together that are related to the same failure. This value is ignored unless cook_for_extension is specified. If max_cook_for is not specified, it defaults to three times the cook_for period.

Type: Integer

Required: No

Default: 3 x cook_for value

Recipes

Recipes determine how Cookbook detects relationships between alerts and considers them for clustering into Situations. You can configure Recipes with different event filters, triggers and similarity comparisons using these parameters:

chef

The recipe type: CValueRecipeV2, CValueRecipe or CBotRecipe. The Value Recipes cluster according to the recipe definitions whereas Bot Recipes follow custom clustering logic defined by a Moobot. See Configure a Cookbook Recipe for more details.

Type: String

Required: Yes

One of: CValueRecipeV2, CValueRecipe, CBotRecipe

Default: "CValueRecipeV2"

name

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

Type: String

Required: Yes

Default: "SplitBySourceAndDescription"

description

Description of the Recipe.

Type: String

Required: No

Default: "Value Recipe outage"

recipe_alert_threshold

Minimum number of alerts required before Cookbook creates a Situation. If left as '0',a single alert can generate a new Situation.

Type: Integer

Required: Yes

Default: 0

exclusion

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.

Type: String

Required: No

Default: "severity < 5"

trigger

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.

Type: String

Required: No

Default: "null"

seed_alert

Filter that determines whether to create a Situation from a seed alert if it meets both trigger and seed_alert filter criteria. Cookbook considers subsequent alerts for clustering if they meet the trigger filter criteria. Alerts that arrived prior to the seed alert that met the trigger filter criteria do not form Situations. For details on creating a filter, see Filter Search Data.

The seed_alert filter is a mechanism to ensure that only specific events create Situations. For example, if you create a seed_alert filter if the description matches 'Switch failure', alerts are eligible for clustering only after a seed alert with the matching description arrives to create a Situation.

Type: String

Required: No

Default: "null"

Example: 'Description' MATCHES "Switch failure"

rate

Filter that determines the minimum event rate per minute required for Cookbook to create a Situation. Cookbook only calculates the rate after the cluster meets the threshold defined by min_sample_size r max_sample_size.

Type: Integer (Number of events per minute).

Required: No

Default: "0"

min_sample_size

Minimum number of events contained in a cluster before Moogsoft AIOps calculates the rate.

Type: Integer

Required: No

Default: "5"

max_sample_size

Maximum number of events contained in a cluster before Moogsoft AIOps calculates the rate.

Type: Integer

Required: No

Default: "10"

cluster_match_type

Defines how Cookbook matches alerts to clusters. The first_match default option adds alerts to the first cluster above the similarity threshold value. The alternative is closest_match to add alerts to the cluster with the highest similarity greater than the similarity threshold value. The latter option might be less efficient because it needs to compare alerts against each cluster in a Recipe.

Type: String

Required: No

Default: "first_match"

cook_for

Minimum time period, in seconds, that Cookbook clusters alerts for before the Recipe resets and starts a new cluster. Different cook_for times per Recipe are useful for monitoring systems with different fail rates, to ensure the Recipe clusters all the relevant events relating to a failure. For example:

  • A Recipe monitoring for network link failures, which have a fast fail rate and many events in a short time, should have a short cook_for time.

  • A Recipe monitoring for disc or CPU issues, which have a slower fail rate as the issue builds, should have a longer cook_for time.

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

Type: Integer

Required: No

Default: "5000"

cook_for_extension

Time period, in seconds, 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 Recipe. 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 helps to ensure that Cookbook continues to cluster alerts together that are related to the same failure. The cook_for_extension only applies to new related alerts; it does not apply to existing alerts that are updated with new events.

For example, cook_for is set to 1 hour (3,600 seconds), cook_for_extension is set to 30 minutes (1,800 seconds), and max_cook_for is set to 2 hours (7,200 seconds). If Cookbook receives a new related alert 40 minutes after the Recipe started clustering alerts, the Recipe extends the total clustering time by 30 minutes from that time to 1 hour and 10 minutes, then:

  • If Cookbook receives another alert 1 hour and 5 minutes after the Recipe started clustering, because Cookbook received it within the extended time of 1 hour and 10 minutes, Cookbook further extends the total clustering time to 1 hour and 35 minutes. Cookbook continually extends the total clustering time as it receives more related alerts, provided that they are received within the extended time. Cookbook can extend the total clustering time until the max_cook_for time is reached. If Cookbook receives further related alerts after the max_cook_for time of 2 hours has elapsed, the Recipe resets and adds them to a new cluster.

  • If Cookbook does not receive any further alerts, it stops clustering alerts after the extended time of 1 hour and 10 minutes elapses. If Cookbook then receives another alert after this time has elapsed, the Recipe starts a new cluster.

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

Type: Integer

Required: No

Default: "1000"

max_cook_for

Maximum time period, in seconds, that Cookbook clusters alerts for before the Recipe resets and starts a new cluster. It works in conjunction with the cook_for_extension to help to ensure that Cookbook continues to cluster alerts together that are related to the same failure. This value is ignored unless cook_for_extension is specified. If max_cook_for is not specified, it defaults to three times the cook_for period.

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

Type: Integer

Required: No

Default: 3 x cook_for value

Matcher
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. You can only use hop limit if you have imported your network topology into the system. See Import a Topology for details.

A hop is the jump between two directly connected nodes in a network. For more information on hops, see Vertex Entropy.

Type: Integer

Required: No

Default: "2"

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 using custom_info fields.

The Value Recipe v2 uses the shingle_size component to determine the similarity between different strings. See Recipe Types for more details.

You can enable or disable case sensitivity with CValueRecipe. You can also configure Cookbook to match each value in the list individually. See Recipe Types for details.

Type: String

Required: No

Default:

{ name: "source_id", similarity: 0.75, shingle_size: 4 },
{ name: "description", similarity: 0.75, shingle_size: -1 }