Decorators

Decorators allow you to alter message fields during search time automatically while preserving the unmodified message on disk. Decorators are especially useful in making the data in your fields more readable, combining data in a field, or adding new fields with more information about the message. As decorators are configured per stream (including the default stream), you are also able to present an individual message in many streams and various ways.

As changes made by decorators are not persisted, you cannot search for decorated values or use field analyzers on them. You can still use those features in the original non-decorated fields.

Decorators are applied on a stream-level, and are shared among all users capable of accessing a stream, so all users can share the same results and benefit from the advantages decorators add.

Graylog comes with some out of the box message decorators, but you can add new ones from pipelines or by writing your own as plugins.

Decorators can be configured under System> Configurations. Select a stream in the Decorators section to see an overview of all related decorators.

To add new default decorators to a stream, click the Update button. This will open a modal which provides two options: either specify the stream or define the type of decorator. After creating a decorator, you need to Save the changes to complete the configuration.

When you apply multiple decorators to the same search results, you can change the order in which they are applied at any time by using drag and drop in the decorator list inside the modal.

List Active Decorators

The message table widget provides an overview of all active decorators. When you open the stream search page by selecting a stream on the Streams page, the widget is preconfigured and it will display the related search results. Editing the message table widget will open a modal with an overview of all active decorators. You can also add decorators here, but they will not be saved or associated with the stream. If you want to save a decorator for a specific message table, you can do this inside Dashboards or Saved Searches.

Syslog Severity Mapper

The syslog severity mapper decorator lets you convert the numeric syslog level of syslog messages to a human readable string. For example, applying a decorator to the levelfield in your logs would convert the syslog level 4 to Warning (4).

To apply a syslog severity mapper decorator, you need to provide the following data:

  • Source field : Field containing the numeric syslog level
  • Target field : Field to store the human readable string in. If you wish to replace the numeric value in your search results, this could be the same as source field.

Format String

The format string decorator provides a simple way of combining several fields into one. It can also be used to modify the content of a field without altering the stored result in Elasticsearch.
To apply a format string decorator you need to provide the following data:

  • Format string : Pattern used to format the resulting string. You can provide fields in the message by enclosing them in ${}. E.g. ${source} will add the contents of the source message field into the resulting string.
  • Target field : Field to store the resulting value.
  • Require all fields (optional): Check this box to format the string only when all other fields are present.

For example, using the format string Request to ${controller}#${action} finished in ${took_ms}ms with code ${http_response_code}, could produce the text Request to PostsController#show finished in 57ms with code 200, and make it visible in one of the message fields in your search results.

Pipeline Decorator

The pipeline decorator provides a way to decorate messages by processing them with an existing processing pipeline. In contrast to using a processing pipeline, changes done to the message by the pipeline are not persisted. Instead, the pipeline is used in searches to modify the presentation of the message.

In order to use the pipeline decorator you need to have an existing pipeline.

Hint: Please take note, the pipeline you use for decoration should not be connected to a stream. If it is then it will run twice (during indexing and search time) for each message, effectively rendering the second run useless.

After creating a pipeline, you can now add a decorator to use on any number of streams. The creation process is the same as for any other decorator type:

  1. Navigate to System > Configurations

  2. Click on Update under Decorators Configuration.

  3. Select the type (Pipeline Processor Decorator in this case)

  4. Click the Apply button next to it.

Select a pipeline and click Save. You now have a new pipeline decorator.

Further Functionality

If the existing decorators are not sufficient for your needs, you can either search the Graylog marketplace, or write your own decorator.