Custom Event Notification Templates¶

Through template syntax, you can customize event notification content:

Basic Template Variables¶

The basic syntax of 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	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 are: Critical critical Error error Warning warning Normal ok No data nodata
df_event_id	String	Unique event ID
df_event_link	String	Link address to the event details page
df_dimension_tags	String	Event dimensions. Used to identify monitored objects e.g.: {"host":"web-001"}
df_monitor_id	String	Alert strategy ID
df_monitor_name	String	Alert strategy name
df_monitor_checker_id	String	Monitor ID
df_monitor_checker_name	String	Monitor name
df_monitor_checker_value	String	Detected value, i.e., the value being monitored The detected value will be forcibly converted to a String type to ensure compatibility
df_monitor_checker_event_ref	String	Monitor event association. Calculated based on monitor ID and event df_dimension_tags
df_fault_id	String	Current fault ID, takes the df_event_id of the first fault event
df_fault_status	String(Enum)	Status of current fault, redundant field of df_status. Possible values are: Normal ok Fault fault
df_fault_start_time	Integer	Fault occurrence time in current round. Unix timestamp, unit is seconds
df_fault_duration	Integer	Duration of current fault. Unit is seconds
df_user_id	String	Operator user ID when manually recovering
df_user_name	String	Operator user name when manually recovering
df_user_email	String	Operator email when manually recovering
df_crontab_exec_mode	String(Enum)	Monitor execution mode, possible values are: Auto-triggered crontab Manual execution manual
df_site_name	String	Current Guance node name
df_workspace_name	String	Belonging workspace name
df_workspace_uuid	String	Belonging workspace ID
df_label	List	Monitor tag list
df_check_condition	Dict	Satisfied detection conditions
df_check_detail	Dict	Applicable for abrupt change detection, represents original comparison values of changes. Contains three fields: Displayed detected value (change_value) Comparison value (comparison_value) Change value (detection_value)
df_check_condition.operator	String	Operator of satisfied condition, e.g.: >, >=, etc.
df_check_condition.operands	List	Operand list of satisfied condition. Usually only one operand, but operators like between have two operands
df_check_condition.operands[#]	Integer, Float	Operand satisfying the detection condition
Result	Integer, Float	Detected value, same as df_monitor_checker_value indicating values generated during detection, but field type remains original without forced conversion to String
Fields within df_dimension_tags	String	Each field in df_dimension_tags will be extracted
df_event	Dict	Complete event data

Template Variable Example¶

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

Event Name:

Monitor {{ df_monitor_checker_name }} found that {{ df_dimension_tags }} has faults

Event Content:

- Region: {{ region }}
- Host: {{ host }}
- Level: {{ df_status }}
- Detected Value: {{ Result }}
- Monitor: {{ df_monitor_checker_name }} (Alert Strategy: {{ df_monitor_name }})

Then, after generating an error event, the rendered output would be:

Output Event Name:

Monitor Monitor001 found {"region":"hangzhou","host":"web-001"} has faults

Output Event Content:

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

Special Scenario Variables¶

User Access Metrics Detection¶

In user access metrics detection, in addition to the generic template variables mentioned above, the following additional template variables are supported:

Handling Fields with Special Characters¶

If the dimension field in detection configuration contains special characters (such as -, @), for example host-name, @level, it cannot be used directly as a normal variable name, which may cause template rendering failure.

The solution is to reference them using the following format:

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

Template Functions¶

Besides directly displaying field values from events, you can also use template functions to further process field values for improved output presentation.

The basic syntax is as follows:

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

A concrete example is shown below:

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

Below is a list of available template functions:

Template Function Example¶

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

Event Name:

Monitor {{ df_monitor_checker_name }} found that {{ df_dimension_tags | to_pretty_tags }} has faults

Event Content:

- Object: {{ df_dimension_tags | to_pretty_tags }}
- Time: {{ date | to_datetime }}
- Level: {{ df_status | to_status_human }}
- Detected Value: {{ (Result * 100) | to_round(2) }}

Then, after generating an error event, the rendered output would be:

Output Event Name:

Monitor My Monitor found region:hangzhou, host:web-001 has faults

Output Event Content:

- Detection Object: region:hangzhou, host:web-001
- Detection Time: 2022-01-01 01:23:45
- Fault Level: Error
- Detected Value: 9012.35

Template Branches¶

Templates also support conditional rendering of different content using branch syntax 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' %}
Potential issue, handle when available
{% elif df_status == 'nodata' %}
Data interruption, please handle immediately!
{% else %}
No problem!
{% endif %}

A more typical example is shown below:

{% if  df_status != 'ok' %}
> Severity: {{ df_status }}
> Host: {{ host }}
> Content: Elasticsearch JVM heap memory usage is {{ Result }}%
> Recommendation: Current JVM garbage collection cannot keep up with garbage generation, please check business conditions promptly

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

{% endif %}

Embedded DQL Query Function¶

In some cases, using template variables alone cannot meet 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 statements under the current workspace within the current detection time range. Typically, the first row of data obtained from the query can be used as a template variable in the template, used 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 row 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 in the template, you can use {{ dql_data.os }} to output specific fields from the query result.

Passing Parameters to Embedded DQL¶

Sometimes, the DQL statement to be executed needs to pass parameters.

Assume 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 to mark different data, it does not include more detailed information such as IP address or operating system.

In this case, using embedded DQL allows obtaining corresponding data through region and host as DQL query parameters, and using {{ 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 parameter values or variables for the DQL statement

When parameter placeholder ? is replaced with specific values, the system automatically escapes them.

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¶