Custom Event Notification Templates¶

When specifying event content, template syntax is supported. Users can use template variables to render dynamic text.

Template Variables¶

The syntax for rendering variables is {{ field_name }}, and the following event fields can be used for text rendering:

User Access Metrics Detection (RUM)¶

In User Access Metrics Detection (RUM), in addition to the above general template variables, the following additional template variables are supported:

Template Variable Example¶

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

Event Name:

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 Strategy: {{ df_monitor_name }})

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

Output Event Name:

Monitor Monitor001 found {"region":"hangzhou","host":"web-001"} with a fault

Output Event Content:

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

Fields Containing Special Characters Such As -, @¶

In some cases, the specified dimension field in the detection configuration may contain special characters such as -, @, e.g., host-name, @level.

According to the template syntax, these field names cannot be used as normal variable names, leading to inability to render properly.

At this point, you can use {{ df_event['host-name'] }}, {{ df_event['@level'] }} instead of {{ host-name }}, {{ @level }}.

Template Functions¶

In addition to directly displaying field values from events, template functions can be used 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, then the syntax is as follows:

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

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

The list of available template functions is as follows:

Template Function Example¶

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

Event Name:

Monitor {{ df_monitor_checker_name }} found 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 occurs, the rendered event output is as follows:

Output Event Name:

Monitor MyMonitor found 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 Branches¶

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

Template Branch Example¶

You can use the following syntax to implement branching functionality:

{% if df_status == 'critical' %}
Urgent issue, please handle immediately!
{% elif df_status == 'error' %}
Important issue, please handle
{% elif df_status == 'warning' %}
Possible issue, handle when free
{% elif df_status == 'nodata' %}
Data interruption, please handle immediately!
{% else %}
No issues!
{% 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 }}%
> Recommendation: The current JVM garbage collection cannot keep up with the JVM garbage production, please check the business situation promptly

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

{% endif %}

Embedded DQL Query Functions¶

In some cases, using only template variables does not meet the rendering requirements. At this point, embedded DQL query functions can be used to achieve additional data queries.

Embedded DQL query functions support executing any DQL statement within the detection time range of the current workspace. In most cases, the first piece of data obtained from the query can be used as a template variable in the template, and the usage method is 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 where the host field is "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 }}

Subsequent templates can then use {{ dql_data.os }} to output specific fields from the query results.

Passing Parameters to Embedded DQL¶

Sometimes, the DQL statement to be executed requires passing parameters.

Assume the monitor by has configured 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 used to mark different data, it does not include IP addresses, operating systems, or other more detailed information.

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

Details of Embedded DQL Query Functions¶

The call format for embedded DQL query functions is as follows:

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

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

The parameter placeholder ? is automatically escaped when replaced with a specific value.

Assuming 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¶