Configure a Cookbook Recipe
A Cookbook Recipe is a set of configurable filters, triggers, and calculations that defines the type of alerts and the alert relationships that Cookbook detects and clusters into Situations.
Cookbook requires at least one active Recipe in order to function and cluster alerts into Situations.
You can configure the following two Recipe types from the UI:
Value Recipe v2: Default Recipe that extracts and analyzes groups of consecutive characters, called shingles, to measure text similarity between alerts.
Value Recipe: First version of the Value Recipe that uses a string comparison mechanism to determine text similarity between alerts.
See Recipe Types for more details on the different types of Recipes available in Cookbook. If you want to implement a Bot Recipe that allows you to call Moobot functions, you can use the Graze API.
Before you begin
Before you set up your Recipe via the UI, ensure you have met the following requirements:
Your LAMs or integrations are running and Moogsoft Enterprise is receiving events.
If you want to cluster on topology information or use Vertex Entropy in your Recipes, you have created one or more topologies. See Topology Overview.
Create a Cookbook Recipe
To create a new Cookbook Recipe from the Moogsoft Enterprise UI:
Navigate to Settings > Cookbook Recipes.
Click the + icon to create a new Recipe.
On the Recipe tab, enter the properties to name and describe the Recipe:
Name: Name of the Recipe. Use a unique and descriptive name.
Situation Description: Description that appears in Situations that the Recipe creates.
Recipe Type: Type of Recipe. The options are Value Recipe and Value Recipe v2. See Recipe Types for more information.
Configure the Recipe behavior and filters that define the alert relationships:
Trigger Filter: Determines the alerts that Cookbook considers for Situation creation. Cookbook includes alerts that match the trigger filter. For details on creating a filter, see Filter Search Data. To set a Vertex Entropy trigger filter, see Configure Topology-based Clustering with Vertex Entropy for more information.
Exclusion Filter: 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 Configure Topology-based Clustering with Vertex Entropy for more information.
Seed Alert Filter: Determines whether to create a Situation from a seed alert. The seed alert must meet both the Trigger Filter, Exclusion Filter and Seed Alert Filter 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 Configure Topology-based Clustering with Vertex Entropy for more information.
The seed alert filter is a mechanism to ensure that only specific events create Situations. For example, if you create a seed alert filter where the description matches 'Switch failure', alerts are eligible for clustering into a Situation only after a seed alert with the matching description arrives.
Rate Filter: Determines whether Cookbook clusters alerts into Situations based on the rate the events arrive and the minimum and maximum sample size. To add a rate filter, check the checkbox and complete the following fields:
Rate: Rate, in number of events per minute. Cookbook clusters alerts if they arrive at the rate specified here or higher.
Min Sample Size: Number of events that must arrive before the Cookbook starts to calculate the event rate.
Max Sample Size: Maximum number of events that are considered in the event rate calculation. When more than this number of events have arrived, Cookbook discards the oldest events and calculates the event rate based on the number of events in the Max Sample Size.
Topology Filter: Determines whether Cookbook clusters alerts into Situations based on topology information. This section is only enabled if you have one or more topologies in your system. To add a topology filter, check the checkbox and complete the following fields:
Source: The source of the topology information on which to cluster. Choices are:
Infer topology from alert: The Recipe obtains the topology name from
custom_info.moog_topology. You can use this option to cluster alerts related to several topologies, without needing to create an individual Recipe for each named topology. For more information, see Create and Manage Topologies.Named topology: The name of the topology from which to obtain topology information.
Node Field: The alert field that contains the topology node information. You must define a node field for both named and inferred topologies.
Match: Maximum number of hops between the alert source nodes in order for the alerts to qualify for clustering. Moogsoft Enterprise measures hop limit from the first alert that formed the Situation and always follows the shortest possible route. A hop is the distance between two directly connected nodes. For more information on Vertex Entropy and hops, see Vertex Entropy and Configure Topology-based Clustering with Vertex Entropy. To change the default of 2, select the Nodes within checkbox and then set a different limit:
Any node: The Recipe checks whether the alert is from any node in the same topology as the node represented by the reference alert in the Situation.
Nodes within: The Recipe checks whether the alert is from a node within a specified hop limit of the node represented by the reference alert in the Situation.
Note
To cluster all alerts from the same node, add a clustering attribute at 100% similarity. Use the same attribute that you are using for your Topology Node Field.
For more information on topologies see Topology Overview.
Alert Threshold: Minimum number of alerts in a candidate cluster required before Cookbook creates a Situation. If left as '1', a single alert can generate a new Situation.
To determines the number of alerts required to create a Situation, Cookbook compares the alert threshold values in the Cookbook Recipe to those of the merge group that the Cookbook Recipe belongs to. 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 Enterprise to create Situations with a single alert, change the alert threshold in the default merge group to 1 or create a custom merge group. See Merge Groups for more information on updating the default merge group and setting up custom merge groups.
Cook For: 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.
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: 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 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 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.
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: 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 to ensure that Cookbook continues to cluster alerts together that are related to the same failure. If Cook For Extension is set and this value is not set, it defaults to three times the Cook For value. See Cookbook and Recipe Examples for more information.
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.
Configure the alert matching property for the Recipe:
Cluster By: Defines how Cookbook matches alerts to clusters. You can select the default option to cluster alerts based on Cookbook's Single Recipe Matching Only setting. The First Matching Cluster option adds alerts to the first cluster above the similarity threshold value. The alternative is Closest Matching Cluster to add alerts to the cluster with the highest similarity greater than the similarity threshold value. The second option may be less efficient because it needs to compare alerts against each cluster in a Recipe.
On the Clustering tab, add the fields that you want Cookbook to factor in when clustering alerts:
Click the + icon and select a field in the drop-down list.
Use the slider to set the similarity threshold for each field. The value determines the required percentage similarity for Cookbook to cluster a set of alerts.
If you want to use custom info fields, configure the Match List Items option. See Match List Items in Recipes for details.
If you are configuring a Value Recipe, check Case Sensitive if you want the text similarity calculation to factor in case sensitivity. See Recipe Types for more information.
If you are configuring a Value Recipe V2, select whether you want Cookbook to calculate text similarity using shingles or words. You can select Shingles from the drop-down list in the Language Processing field and enter a Shingle Size. The default value is the optimal shingle size for that field. Alternatively, you can select Words. See Recipe Types for more information.
Click Save Changes.
When you have completed the configuration, Moogsoft Enterprise applies the changes to any active Cookbooks that use the Recipe as soon as you save the changes. If the Recipe has not been added to an active Cookbook, go to Settings > Cookbook and move the Recipe under Selected Recipes for that Cookbook.
If you change a Cookbook Recipe, see Cookbook Configuration Changes for information on how these changes affect the clusters that Cookbook creates.