Custom Event Notification Template¶

Through template syntax, you can customize event notification content:

Basic Template Variables¶

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

Template Variable	Type	Description
date, timestamp	Integer	Event generation time. Unit is seconds
df_date_range	Integer	Time range. Unit is seconds
df_check_range_start	Integer	Detection range start time. Unix timestamp, unit is seconds
df_check_range_end	Integer	Detection range end time. Unix timestamp, unit is seconds
df_status	String(Enum)	Event status, possible values: Critical critical Error error Warning warning Normal ok Data gap nodata
df_event_id	String	Event unique ID
df_event_link	String	Event details page link address
df_dimension_tags	String	Event dimensions. Used to identify detection objects e.g.: {"host":"web-001"}
df_monitor_id	String	Alert policy ID
df_monitor_name	String	Alert policy name
df_monitor_checker_id	String	Monitor ID
df_monitor_checker_name	String	Monitor name
df_monitor_checker_value	String	Detection value, i.e., the value detected by the monitor Detection value is forcibly converted to String type to ensure compatibility
df_monitor_checker_event_ref	String	Monitor event association. Calculated based on monitor ID, event df_dimension_tags
df_fault_id	String	Current fault ID, value is the df_event_id of the first fault event
df_fault_status	String(Enum)	Current fault status, redundant field of df_status. Possible values: Normal ok Fault fault
df_fault_start_time	Integer	Current fault occurrence time. Unix timestamp, unit is seconds
df_fault_duration	Integer	Current fault duration. Unit is seconds
df_user_id	String	Operator user ID during manual recovery
df_user_name	String	Operator user name during manual recovery
df_user_email	String	Operator user email during manual recovery
df_crontab_exec_mode	String(Enum)	Monitor execution mode, possible values: Automatic trigger crontab Manual execution manual
df_site_name	String	CurrentTrueWatch node name
df_workspace_name	String	Workspace name
df_workspace_uuid	String	Workspace ID
df_label	List	Monitor label list
df_check_condition	Dict	Satisfied detection conditions
df_check_detail	Dict	Applicable to mutation detection, represents mutation compared to the original value. Contains three fields: Display detection value (change_value) Comparison value (comparison_value) Change value (detection_value)
df_check_condition.operator	String	Operator for satisfied detection conditions, e.g.: >, >=, etc.
df_check_condition.operands	List	Operand list for satisfied detection conditions. Generally, there is only 1 operand, but operators like between have 2 operands
df_check_condition.operands[#]	Integer, Float	Operand for satisfied detection conditions
Result	Integer, Float	Detected value, same as df_monitor_checker_value, but the field type is the original type during detection, not forcibly converted to String
Fields in df_dimension_tags	String	Fields in df_dimension_tags will be extracted
df_event	Dict	Complete event data

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 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 found 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 additionally 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 passing parameters, the syntax is as follows:

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

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

The available template function list is as follows:

Template Function Example¶

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 }} found 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 found 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: Error
- Detection value: 9012.35

Template Branching¶

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

Template Branching Example¶

You can use the following syntax to implement branching functionality:

{% 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 production, please check business situation in time

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

{% endif %}

Embedded DQL Query Function¶

In some cases, using only template variables cannot meet rendering requirements. In this case, 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 be executed") %}

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

Subsequently, {{ dql_data.os }} can be used in the template 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 only contains region and host template variables to mark different data, it does not contain more information such as IP address, operating system, etc.

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