Situation Manager Labeler

You can use the Situation Manager Labeler to provide better context for Situations. You can add data that will help operators diagnose and resolve issues faster.

You can set Situation descriptions and fields dynamically based on the alert data. For example, suppose you want to define a correlation based on the custom_info.services alert field. To generate descriptions for the resulting Situations, you can specify a label string in the description field such as:

$$COUNT(custom_info.services) services affected including $$CITED(custom_info.services,3)

Given this string, the resulting descriptions include the three most-cited services and the number of times each service is cited by a member alert:

5 services affected including cust-login(7), verify-login(6), update-login-info(4), ...

Configuration

You can configure Situation Labeling:

Through a Cookbook Recipe definition. See Configure a Cookbook Recipe for more information.
By using enriched Situation data. See Situation Enrichment for more information.
By manually entering text.

Usage

Given a macro operation and an alert data field, the operation iterates through the relevant values in the Situation alerts and returns a string derived from these values.

Labeling can provide better context for Situations.

The usage for fields with single values (prefix is one $): $macro(alert-field, max-alerts-to-include)

The usage for fields with lists (prefix is two $’s): $$macro(alert-field, max-alerts-to-include)

The max-alerts-to-include field is optional. This value limits the number of alert values to include in the description.

Consider the following example. You want to create a label with a count of all the affected services (custom_info.services) cited in all alerts. A Situation has two alerts:

Alert 1: custom_info.services = [ a, b, c ];
Alert 2: custom_info.services = [ d, e, f ];

$COUNT treats the fields as individual values and returns a count of 2.

$$COUNT treats the fields as lists of individual values and returns a count of 6.

Update Situation descriptions

You can use the following macros to generate Situation descriptions. These macros are supported for single values ($macro) and lists ($$macro):

COUNT(alert-field)— Return the count of alert-field citations, including duplicates.
UCOUNT(alert-field) — Return the count of unique alert-field citations, excluding duplicates.
CRITICAL(alert-field)— Return the string CRITICAL : if any alerts have a severity of critical, or 5. This macro is only useful for the severity field.
UNIQ(alert-field)— Return a list of all cited alert-field values.
TOP(alert-field)— Return the alert-field value cited by the most alerts in the Situation.
CITED(alert-field)— Return a list of the unique alert-field values cited by alerts in the Situation along with the number of times they are cited -- for example, source1 (10), source5 (7), source3 (4).
CITEDLIST(alert-field)— Same as $CITED but returns a string instead of a JSON list.
BOOLEAN(alert-field)— Return false if all values are “falsy:” 0, null, undefined, "", and so on.
$CLASS(custom-info-value) —Set the situation custom_info.situationClass field with this value and include this value in the situation label. This is useful for specifying custom information about the Situation such information about the clustering algorithm — for example, cookbook-name.recipe-name.
TOLIST(alert-field)— Creates a comma-separated string from the elements of alert-field.
Note
UI list-based filtering is now native, so $TOLIST() should no longer be required.

Numeric fields only

The following macros are supported for numeric fields only, such as time, severity, or event-count.

MIN(alert-field)— Return the minimum cited value of alert-field.
MAX(alert-field)— Return the maximum cited value of alert-field.
AVE(alert-field)— Return the average of all cited values of aalert-field.
SUM(alert-field)— Return the average of all cited values of alert-field.
NUM(alert-field)— Return the set of alert-field values sorted numerically from low to high, including duplicates.
UNUM(alert-field)— Return the set of unique alert-field values sorted numerically from low to high, excluding duplicates.

Text fields only

The following macros are supported for text fields only, such as service, source, or description.

ALPHA(alert-field)— Return the set of alert-field values sorted alphabetically, including duplicates.
UALPHA(alert-field) — Return the set of unique alert-field values sorted alphabetically, excluding duplicates.

List values only

The following macros are supported for array values only.

$$INTERSECT(alert-field)— Return the list of intersections -- that is, alert-field values cited by multiple alerts. This macro parses the alert-field array values and returns a list of the items with multiple citations.For example, support a Situation has two alerts. The service field of alert 1 is [a, b, c]. The service field of alert 2 is [b, c, d]. $$INTERSECT(service) would return the list [b, c].
$$NINTERSECT(alert-field)— Return the number of intersections. Given the previous example, $$NINTERSECT(service) would return the number 2.
$$CINTERSECT(alert-field) — Return the list of common intersections -- that is, values cited by all alerts in the Situation. This macro is useful for identifying a possible root cause that caused all the alerts to get correlated together.

Limiting the number of alerts to consider

By default, each macro considers all alerts in a Situation up to a maximum of 200. You might want to specify a lower threshold to ensure that labeling does not become a bottleneck in systems with large or frequently-updated Situations. To lower the threshold, append the $FETCH modifier at the start of the Labeler string:

$FETCH(max-alerts-to-consider)Labeler-string

For example, the following macro considers the first alert in each Situation based on alert ID:

$FETCH(1) Application Situation for: $UNIQ(custom_info.application) at DataCentre $UNIQ(custom_info.location)

You should specify the maximum number of alerts needed to ensure an accurate description. If you are correlating based on a specific field such that all alerts have the same value for that field, you only need to fetch 1 alert.

Warning

Do not specify a fetch value higher than 20.

Update Situation columns

You can use the following macros to update columns in the Situation Table with values contained in its member alerts.

$$SERVICES(alert-field) —Update the Services Impacted column in the Situation with all unique alert-field values cited in the member alerts.
$$ISERVICES(alert-field) — Update the Services Impacted column in the Situation with all unique alert-field values cited in 2 or more member alerts.
$$PROCESSES(alert-field)— Update the Processes Impacted column in the Situation with all unique alert-field values cited in the member alerts.

You can also use the $MAP[ ] macro to update a custom_info field in the Situation with data from the member alerts. The usage is as follows:

$MAP[ $MACRO(source alert field, destination custom_info field) ]

Update Situation fields

You can use the following macro to update the custom_info field for individual Situations.

$MAP[source-alert-field, destination-custom-info-field] —Update a custom_info field in the Situation with data from the member alerts. You can include multiple macros in the same MAP macro, as shown in the following example:
```
$MAP[ $UNIQ(source, hosts) $UCOUNT(source, num_hosts) ]
```
$CLASS(custom-info-value) —Set the situation custom_info.situationClass field with this value. This is useful for specifying custom information about the situation, such as information about the clustering algorithm — for example, cookbook-name.recipe-name.

Example

For instructions on how to use the Situation Manager Labeler to automatically create services based on custom_info data, see Create Services using Situation Manager Labeler.

In this section: