Custom Event Notification Templates¶

With template syntax, you can customize event notification content:

• Dynamic rendering: insert alert fields directly using {{ field name }} (e.g., {{ host }}, {{ df_status }});
• Data processing: format data with {{ variable | function() }} (e.g., timestamp to date, number to percentage);
• Conditional branching: use {% if ... %} to send differentiated notifications based on status;
• Real-time queries: embed DQL ("query statement") to retrieve related data (e.g., host IP, application information).

Validate and Preview Templates¶

The Event Content of monitors, Data Gap Event Content, and the Event Content of Smart Monitoring support syntax validation. After editing, when you move the cursor out of the input box, or when you save the monitor, the system checks the template and flags syntax issues.

After the syntax check passes, click the Preview button in the event content editor, fill in test values for variables as needed, and then click Preview to verify the rendered result. Regular monitors preview both the current title and content, while Smart Monitoring previews the event content. You can switch the test values of variables such as df_status to check conditional branches such as anomaly and recovery.

Preview is used to check the template effect; actual alerts are based on the data at the time the event occurs. When the template contains an embedded DQL, the preview reads the relevant data from the current workspace.

Basic Template Variables¶

The basic syntax of template variables is {{ field name }}, which can be used to render dynamic event-related information. The following are common template variables and their purposes:

Template Variable Example¶

Assume the monitor's by is configured with region and host, and the event content template is as follows:

Event Name:

The monitor {{ df_monitor_checker_name }} found a fault in {{ df_dimension_tags }}

Event Content:

- Region: {{ region }}
- Host: {{ host }}
- Level: {{ df_status }}
- Detection value: {{ Result }}
- Monitor: {{ df_monitor_checker_name }} (Alert Policy: {{ df_monitor_name }})

Then, after an error event is generated, the rendered event output is as follows:

Output Event Name:

The monitor Monitor001 found a fault in {"region":"hangzhou","host":"web-001"}

Output Event Content:

- Region: hangzhou
- Host: web-001
- Level: error
- Detection value: 90.12345
- Monitor: Monitor001 (Alert Policy: Team001)

Special Scenario Variables¶

User Access Metrics Detection¶

In User Access Metrics Detection, in addition to the general template variables above, the following template variables are also supported:

Handling Fields with Special Characters¶

If the Dimensions field in the detection configuration contains special characters (such as - or @), for example host-name or @level, it cannot be used directly as a normal variable name, which causes template rendering to fail.

The solution is to reference them using the following formats:

• Use {{ df_event['host-name'] }} instead of {{ host-name }}
• Use {{ df_event['@level'] }} instead of {{ @level }}

Template Functions¶

In addition to directly displaying field values from an event, you can also use template functions to further process field values and improve the output.

The basic syntax is as follows:

{{ <template variable> | <template function> }}

For example:

Event generation time: {{ date | to_datetime }}

If a template function requires parameters, the syntax is as follows:

Event generation time: {{ date | to_datetime('America/Chicago') }}

CPU usage: {{ (Result * 100) | to_round(2) }}

The available template functions are as follows:

Template Function Example¶

For more details, refer to Examples of Each Template Function.

Assume the configured monitor's by is configured with region and host, and the alert template is as follows:

Event Name:

The monitor {{ df_monitor_checker_name }} found a fault in {{ df_dimension_tags | to_pretty_tags }}

Event Content:

- Target: {{ df_dimension_tags | to_pretty_tags }}
- Time: {{ date | to_datetime }}
- Level: {{ df_status | to_status_human }}
- Detection value: {{ (Result * 100) | to_round(2) }}

Then, after an error event is generated, the rendered event output is as follows:

Output Event Name:

The monitor My Monitor found a fault in region:hangzhou, host:web-001

Output Event Content:

- Detection target: region:hangzhou, host:web-001
- Detection time: 2022-01-01 01:23:45
- Fault level: Important
- Detection value: 9012.35

Template Branching¶

Templates also support branch syntax to render different content based on conditions.

Template Branching Example¶

You can use the following syntax to implement branching:

{% if df_status == 'critical' %}
Critical issue, please handle it immediately!
{% elif df_status == 'error' %}
Important issue, please handle it
{% elif df_status == 'warning' %}
There may be an issue, handle it when you have time
{% elif df_status == 'nodata' %}
Data interrupted, please handle it immediately!
{% else %}
No problem!
{% endif %}

A more typical example is as follows:

{% if  df_status != 'ok' %}
> Level: {{ df_status }}
> Host: {{ host }}
> Content: Elasticsearch JVM heap memory usage is {{ Result }}%
> Suggestion: JVM garbage collection cannot keep up with JVM garbage generation. Please check the business situation promptly

{% else %}
> Level: {{df_status}}
> Host: {{host}}
> Content: The Elasticsearch JVM heap memory alert has recovered

{% endif %}

Embedded DQL Query Function¶

In some cases, template variables alone cannot meet the rendering requirements. In such cases, you can use the embedded DQL query function to perform additional data queries.

The embedded DQL query function supports executing any DQL statement within the current detection time range in this workspace. Typically, the first record returned by the query can be used as a template variable in the template, as follows:

{% set dql_data = DQL("The DQL statement to execute") %}

Some field: {{ dql_data.some_field }}

Embedded DQL Query Example¶

The following embedded DQL statement queries data whose host field is "my_server" and assigns the first record to the dql_data variable:

{% set dql_data = DQL("O::HOST:(host, host_ip, os, datakit_ver) { host = 'my_server' }") %}

Host OS: {{ dql_data.os }}

In the template that follows, you can use {{ dql_data.os }} to output specific fields from the query result.

Passing Parameters to the Embedded DQL¶

Sometimes, executing a DQL statement requires passing parameters. These parameters can be embedded directly into the DQL statement, and you can choose whether to add a by filter. However, the syntax is slightly different. Usually, you reference a variable with {{df_status}}. But in a DQL statement, you should use the variable name directly without adding {{ }}; therefore, the final form is status.

Assume the monitor's by is configured with region and host, and the event content template is as follows:

{% set dql_data = DQL("O::HOST:(host_ip, os) { region = ?, host = ? }", region, host) %}

Host information:
IP: {{ dql_data.host_ip }}
OS: {{ dql_data.os }}

Since the event only contains the region and host template variables to identify different data, it does not include more information such as IP addresses or operating systems.

Then, using the embedded DQL, you can retrieve the corresponding data using region and host as DQL query parameters, and output the related information with {{ dql_data.host_ip }} and so on.

Embedded DQL Query Function Details¶

The embedded DQL query function is called in the following format:

DQL(dql, param_1, param_2, ...)

• The first parameter is the DQL statement, which can contain parameter placeholders ?
• The subsequent parameters are the parameter values or variables of the DQL statement

When the parameter placeholder ? is replaced with an actual value, the system escapes it automatically.

Assume the variable host has the value "my_server". The embedded DQL function and the final DQL statement executed are as follows:

DQL("O::HOST:(host, host_ip, os, datakit_ver) { host = ? }",  host)

O::HOST:(host, host_ip, os, datakit_ver) { host = 'my_server' }

More DQL Documentation¶