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 general template variables mentioned above, the following additional template variables are supported:

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 }} found a failure 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 generating an error event, the rendered event output would be as follows:

Output Event Name:

Monitor Monitor001 found a failure in {"region":"hangzhou","host":"web-001"}

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 fields in the detection configuration may contain special characters such as -, @, like host-name, @level.

According to the template syntax, these field names cannot be used as normal variable names, causing them to fail to render properly.

In this case, 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 also be used to further process field values and optimize output.

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) }}

List of available template functions:

Template Function Example¶

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

Event Name:

Monitor {{ df_monitor_checker_name }} found a failure 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 generating an error event, the rendered event output would be as follows:

Output Event Name:

Monitor MyMonitor found a failure in region:hangzhou, host:web-001

Output Event Content:

- Detection Object: region:hangzhou, host:web-001
- Detection Time: 2022-01-01 01:23:45
- Failure 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 }}%
> Suggestion: Current JVM garbage collection cannot keep up with JVM garbage production, please check business conditions promptly

{% 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 does not meet rendering requirements. In such cases, embedded DQL query functions can be used to perform additional data queries.

Embedded DQL query functions support executing any DQL statement within the current workspace and detection time range. In most cases, the first piece of queried data 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 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 contains only region and host template variables used to mark different data, it does not include IP addresses, operating systems, or other more detailed information.

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

Details of Embedded DQL Query Function¶

The call format of the embedded DQL query function 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

Parameter placeholders ? will be automatically escaped when replaced with specific values.

Assuming the variable host has the value "my_server", 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¶