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 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: Critical critical Important 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 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	Detection value, i.e., the value detected by the monitor Detection value will be 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, the value is the df_event_id of the first fault event
df_fault_status	String(Enum)	Current fault status, a 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 running mode, possible values: Automatic trigger crontab Manual execution manual
df_site_name	String	CurrentGuance node name
df_workspace_name	String	Belonging workspace name
df_workspace_uuid	String	Belonging workspace ID
df_label	List	Monitor label list
df_check_condition	Dict	Satisfied detection conditions
df_check_detail	Dict	Applicable to mutation detection, representing the original value compared with the mutation. Contains three fields: Display detection value (change_value) Comparison value (comparison_value) Change value (detection_value)
df_check_condition.operator	String	Satisfied detection condition operator, e.g.: >, >=, etc.
df_check_condition.operands	List	Satisfied detection condition operand list. Generally, there is only 1 operand, but operators like between have 2 operands
df_check_condition.operands[#]	Integer, Float	Satisfied detection condition operand
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
df_dimension_tags fields	String	Each field in df_dimension_tags will be extracted
df_event	Dict	Complete event data
df_studio_env_name		Current environment name
df_studio_console_base_url		Current environment console address
df_studio_monitor_base_link		Current environment monitor address

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

Then, after generating an error event, 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 strategy: Team001)

Special Scenario Variables¶

User Access Metric Detection¶

In User Access Metric Detection, in addition to the above general template variables, 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 to 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¶

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 }} 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 generating an error event, 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: Important
- 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:

{% 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 problem!
{% 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 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. At this time, 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. Generally, 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 }}

After this, you can use {{ dql_data.os }} in the template to output specific fields in the query result.

Passing Parameters to Embedded DQL¶

Sometimes, executing a DQL statement requires passing parameters. These parameters can be directly embedded in 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, 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 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¶