Decorators

Decorators are search-time tools that transform how message fields appear in your search results without modifying the stored data on disk. When you execute a search, decorators automatically alter field values for display purposes: converting numeric codes to readable strings, combining multiple fields into formatted text, or adding contextual information while preserving the original message exactly as it was indexed. This separation between storage and presentation lets you improve readability and add context to your search results without the performance cost or risk of modifying your log data.

How Decorators Work

Decorators are fundamentally result interpretation tools, not data processing mechanisms. This distinction shapes how you should think about using them in your Graylog workflow.

Use decorators when:

You need to improve the readability of search results without changing stored data.
Different teams need different views of the same data.
You want to experiment with display formats without committing to permanent data transformations.
You need to add context or formatting that aids human interpretation but is not required for queries or analysis.

Do not use decorators in the following scenarios:

When you need to create searchable fields; use pipeline processors during ingestion instead.
When you need to perform aggregations or analytics on transformed values; transform the data during ingestion so processed values are indexed and analyzable.
When you need consistent field values across all Graylog features including dashboards, alerts, and exports; permanent transformations during ingestion ensure consistency.

Generally, if you need to search, aggregate, or analyze a log message, transform it during ingestion with pipelines. If you only need to display log messages more clearly in search results, use decorators. This separation keeps your data processing pipeline clean and efficient while giving you flexibility in how results are presented to different audiences.

Configure a Decorator

Decorators are configured at the stream level through the system configuration interface.

Navigate to System > Configurations > Decorators.
In the Decorators section, select a stream to view all decorators associated with that stream.
Review the existing decorators and their parameters.
Add a new decorator, modify an existing one, or change the order in which decorators are applied.

When you apply multiple decorators to the same search results, execution order matters because later decorators may operate on values transformed by earlier decorators. You can change the execution order at any time by dragging and dropping decorators in the configuration modal.

The message table widget provides an overview of active decorators when you view search results. When you open a stream search page by selecting a stream, Graylog displays a preconfigured message table widget showing related search results with decorators applied. You can also add decorators directly in the message table widget configuration, but those decorators are not saved to or associated with the stream. They apply only to that specific widget instance.

Save a Decorator

To save decorators for consistent use across all searches in a stream, configure them through the system configuration interface. To save decorators for specific message tables in dashboards or saved searches, configure them within those contexts.

To add new default decorators to a stream:

Select Edit configuration.
In the modal, choose a stream.
Select the decorator type.
Click Update configuration to apply the change.

Decorator Types Explained

Graylog includes several built-in decorator types to improve message readability and formatting. You can also create custom decorators using pipelines or by developing plugins.

Syslog Severity Mapper

Syslog Severity Mapper converts numeric syslog severity levels to human-readable strings. Use this decorator when your messages contain numeric syslog levels and you want severity to be immediately recognizable in search results. Applying this decorator to the level field transforms 4 into Warning (4).

To apply a syslog severity mapper decorator, provide the following:

Source field: Field containing the numeric syslog level.
Target field: Field to store the human-readable string in.

Format String

Format string combines multiple fields into a single formatted string using a template with field placeholders. Use this decorator when you want to create human-readable summaries of complex events or combine related information that appears in separate fields.

To apply a format string decorator, provide the following:

Format string: Pattern used to format the resulting string. Provide fields in the message by enclosing them in ${}. For example, ${source} inserts 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 referenced fields are present.

For example, using the format string Request to ${controller}#${action} finished in ${took_ms}ms with code ${http_response_code} produces this output: Request to PostsController#show finished in 57ms with code 200. The decorator extracts values from the specified fields and inserts them into the format string.

Hyperlink String

Hyperlink String creates clickable links from field values, enabling quick navigation to related resources or external systems directly from search results. Use this decorator when a field contains identifiers that map to URLs in other systems. Selecting the decorated field opens the corresponding resource in a new browser tab.

Pipeline Processor Decorator

The pipeline processor decorator lets you decorate messages by processing them with an existing processing pipeline. Unlike standard pipeline processing that permanently modifies messages before storage, the pipeline decorator uses pipeline rules to transform message presentation without persisting changes. This approach is useful when you need complex transformations for display purposes but do not want to modify stored data. The pipeline you use for decoration should not be connected to a stream. If it is, the pipeline will run twice (during indexing and at search time), rendering the second run ineffective.

Hint: To use the pipeline decorator, you need an existing pipeline.