Message Summary Templates

Message summary templates enable users to display relevant information in search results so that, rather than having to expand a log message, useful information will be available in the initial search results and optionally highlighted in color so that the most important messages stand out.

Requirements

• Active Graylog Illuminate license

Install Message Summary Templates

The latest message summary templates are delivered and updated as a pack in Illuminate bundles. To install and activate the latest Illuminate bundle:

1. Click Enterprise from the menu header and select Illuminate from the resulting drop-down options.

2. In the search bar, search for Message Summary Updates and enable the pack labeled “Illuminate X.X.X:Message Summary Updates rev. X” from the Illuminate Processing Packs page by clicking the check box.

The Message Summary Templates Spotlight pack has now been installed and is ready to use. A more detailed view of its contents can be found by navigating to System/Content Packs > Content Packs and selecting the “Default Summary Templates” pack.

Enable or Disable in Search View

By default, message summaries will be displayed from any search view with a messages widget. To control whether summaries are displayed:

1. Click the Edit icon at the top right of the widget.

2. From the Edit pane, select or deselect Show summary.
   

3. Select Update widget to apply new settings.

Color Customization

Customize your desired color selections by navigating to the Enterprise > Customization page.

Entities

There are 3 entities that are used to assign the message summary formatting and the color for the message to be shown in:

• Event Type Category: The entity that is used to apply both message templates.

• Message Summary Templates: Controls the message format.

• Indicator Templates: Controls the color that the log message shows in.

Event Type Category

This is the first entity that is used to apply both message summaries and indicator templates. The category and subcategory fields are combined with a dot between them in the gim_event_subcategory field to determine which messages match the event type category and therefore get the indicated summary and indicator. For example, when gim_event_subcategory=service.configuration, the following template will apply.

Note that this points to the summary message summaries and indicator templates by name (with summaryTemplate.serviceCategory pointing to the summary template with template_id of serviceCategory and indicatorTemplate.serviceStateIndicator pointing to the Indicator Template with type of serviceStateIndicator).

{
  "id": "63e2bc8fc393530e78f8bf57",
  "title": 'serviceConfig',
  "description": 'Service Configuration Summary (schema v3.1)',
  "category": 'service',
  "sub_category": 'configuration',
  "summary_template": 'summaryTemplate.serviceCategory',
  "indicator_template": 'indicatorTemplate.serviceStateIndicator'
}

Note that an explicit summary template might be used instead of pointing to the template by name:

summary_template: '[{gim_event_type}] {source_ip} - {destination_ip}'

Indicator templates do not support explicit indicator templates. They always point to one in the indicator template collection.

Message Summary Templates

Message summary templates are reusable template objects that control the message format. They must be referenced by the Event Type Category summary_template field using the summaryTemplate.template_name format.

Fields

• id: A unique database ID.

• template_id: The unique reference ID to be used by other entities.

• summary : The desired message format, with field placeholders denoted with curly braces {<field_name>}.

• title: A plain language title.

• description: (optional) A plain language description.

Example

Message summary template entity:

{
  "id" : "64d3f02a7b43ea375663c131",
  "template_id" : "serviceCategory",
  "summary" : "[{gim_event_type}] service_name:{service_name} | user_name:{user_name}",
  "title" : "service category template",
  "description" : "Basic service category message template for schema v3.1"
}

A log with the fields:

• gim_event_type: “service error”

• service_name: “Windows Defender”

• user_name: “User1234”

would result in a message summary of: [Alert] service_name:Windows Defender | user_name:User1234

Indicator Templates

This directly controls the color that the log message shows in. The indicator field contains the field that should be inspected and the value is contained within the success/danger arrays.

Fields

• id: A unique database ID.

• type: The unique reference ID to be used by other entities.

• title: A plain language title.

• description: (optional) A plain language description.

• indicator: The field in the message to determine what color key to use.

• default_indicator: The color key to use if no matches are found.

• danger/info/primary/success/warning: (for one or more keys) Array of indicator field values that will trigger the message to be displayed in the <key> color.

Example

Indicator template entity:

{
  "id" : "64d3f02a7b43ea375663c152",
  "type" : "serviceStateIndicator",
  "title" : "Service State Indicator",
  "description" : "Set summary font color for different service state events",
  "success" : [
      "service installed",
      "service enabled"
    ],
  "danger" : [
      "service error",
      "service disabled",
      "service removed"
    ],
  "indicator" : "gim_event_type",
  "default_indicator" : "info"
}

1. A log with the fields:

would result in a message of the danger color:[service error] service_name:Windows Defender | user_name:User1234

2. A log with the fields:

• gim_event_type: “service enabled”

• service_name: “Windows Defender”

• user_name: “User1234”

Would result in a message of the success color:[service enabled] Windows Defender | outcome: success