Custom Event Notification Templates¶

Through template syntax, you can customize event notification content:

• Dynamic rendering: Use {{ field_name }} to directly insert alert fields (e.g., {{ host }}, {{ df_status }});

• Data processing: Format data using {{ variable | function() }} (e.g., convert timestamp to date, convert number to percentage);

• Conditional branching: Use {% if ... %} to implement differentiated notifications for different states;

• Real-time query: Embed DQL ("query statement") to obtain associated data (e.g., host IP, application information).

Basic Template Variables¶

The basic syntax for template variables is {{ field_name }}, which can be used to render dynamic information related to events. Below are common template variables and their uses:

Template Variable Example¶

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

Event name:

Monitor {{ df_monitor_checker_name }} detected 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:

Monitor Monitor001 detected 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 mentioned above, the following template variables are also supported:

Special Character Field Handling¶

If the Dimension field in the detection configuration contains special characters (e.g., -, @), such as host-name, @level, it cannot be directly used as a normal variable name, which will cause template rendering to fail.

The solution is to use the following format for reference:

• 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 in events, you can also use template functions to further process field values and optimize output.

The basic syntax is as follows:

{{ <template_variable> | <template_function> }}

Specific examples are as follows:

Event generation time: {{ date | to_datetime }}

If the 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, visit Get Template Function Examples.

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

Event name:

Monitor {{ df_monitor_checker_name }} detected a fault in {{ df_dimension_tags | to_pretty_tags }}

Event content:

- Object: {{ 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:

Monitor My Monitor detected a fault in region:hangzhou, host:web-001

Output event content:

- Detection object: 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 branching 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 immediately!
{% elif df_status == 'error' %}
Important issue, please handle
{% elif df_status == 'warning' %}
Possible issue, handle when available
{% elif df_status == 'nodata' %}
Data interruption, please handle immediately!
{% else %}
No issue!
{% 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: Current JVM garbage collection cannot keep up with JVM garbage generation, please check the business situation in time

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

{% endif %}

Embedded DQL Query Function¶

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

The embedded DQL query function supports executing any DQL statement within the current detection time range in the current workspace. Typically, the first piece of data obtained from the query can be used as a template variable in the template, as follows:

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

Some field: {{ dql_data.some_field }}

Embedded DQL Query Example¶

The following embedded DQL statement queries data with the host field as "my_server" and assigns the first piece of data 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 subsequent templates, you can use {{ dql_data.os }} to output specific fields from the query result.

Passing Parameters to Embedded DQL¶

Sometimes, executing a DQL statement requires passing parameters. These parameters can be directly embedded into the DQL statement, and you can choose whether to add by filtering. However, the writing method is slightly different. Usually, when referencing variables, {df_status} is used. But in DQL statements, you should directly use the variable name without adding {{ }}, so the final writing method is status.

Assume the monitor 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 region and host template variables to mark different data, it does not contain more information such as IP address and operating system.

Then, using embedded DQL, you can obtain corresponding data through region and host as DQL query parameters, and use {{ dql_data.host_ip }} to output associated information.

Embedded DQL Query Function Details¶

The embedded DQL query function call format is as follows:

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

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

When the parameter placeholder ? is replaced with a specific value, the system will automatically escape it.

Assume the variable host value is "my_server", then the embedded DQL function and the final executed DQL statement 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¶