跳转至

自定义事件通知模板


通过模板语法,可自定义事件通知内容:

  • 动态渲染:使用 {{ 字段名 }} 直接插入告警字段(如 {{ host }}, {{ df_status }})
  • 数据处理:通过 {{ 变量 | 函数() }} 格式化数据(如时间戳转日期、数值转百分比)
  • 条件分支:用 {% if ... %} 实现不同状态差异化通知
  • 实时查询:嵌入 DQL ("查询语句") 获取关联数据(如主机 IP、应用信息)

基础模板变量

模板变量的基本语法为 {{ 字段名 }},可用于渲染事件相关动态信息。以下是常见的模板变量及其用途:

模板变量 类型 说明
datetimestamp Integer 事件产生时间。单位为秒
df_date_range Integer 时间范围。单位为秒
df_check_range_start Integer 检测范围开始时间。Unix 时间戳,单位为秒
df_check_range_end Integer 检测范围结束时间。Unix 时间戳,单位为秒
df_status String(Enum) 事件状态,可能的值为:

  • 紧急 critical
  • 重要 error
  • 警告 warning
  • 正常 ok
  • 数据断档 nodata
  • df_event_id String 事件唯一 ID
    df_event_link String 事件详情页链接地址
    df_dimension_tags String 事件维度。用于标识检测对象

    如:{"host":"web-001"}
    df_monitor_id String 告警策略 ID
    df_monitor_name String 告警策略名称
    df_monitor_checker_id String 监控器 ID
    df_monitor_checker_name String 监控器名称
    df_monitor_checker_value String 检测值,即被监控器检测的值

    ⚠检测值会强制转换为 String 类型以保证兼容性
    df_monitor_checker_event_ref String 监控器事件关联。
    根据监控器 ID、事件 df_dimension_tags 计算所得
    df_fault_id String 本轮故障 ID,取值为首次故障事件的df_event_id
    df_fault_status String(Enum) 本轮故障状态,为 df_status 的冗余字段。可能的值为:

  • 正常 ok
  • 故障 fault
  • df_fault_start_time Integer 本轮故障发生时间。Unix 时间戳,单位为秒
    df_fault_duration Integer 本轮故障持续时间。单位为秒
    df_user_id String 手工恢复时,操作者用户 ID
    df_user_name String 手工恢复时,操作者用户名称
    df_user_email String 手工恢复时,操作者用户邮箱
    df_crontab_exec_mode String(Enum) 监控器运行模式,可能的值为:

  • 自动触发 crontab
  • 手工执行 manual
  • df_site_name String 当前观测云节点名
    df_workspace_name String 所属工作空间名
    df_workspace_uuid String 所属工作空间 ID
    df_label List 监控器标签列表
    df_check_condition Dict 满足的检测条件
    df_check_detail Dict 适用于突变检测,表示突变对比原始值。包含三个字段:

  • 展示检测值(change_value
  • 对比值(comparison_value
  • 改变值(detection_value
  • df_check_condition.operator String 满足检测条件的操作符,如:>>=
    df_check_condition.operands List 满足检测条件的操作数列表。
    一般只有 1 个操作数,但 between 等操作符具有 2 个操作数
    df_check_condition.operands[#] Integer, Float 满足检测条件的操作数
    Result Integer, Float 检测到的值,与 df_monitor_checker_value 同为检测时产生的值,但字段类型为检测时的原始类型,不会强制转为 String
    df_dimension_tags 中的各字段 String df_dimension_tags 中的各字段会被提取
    df_event Dict 完整事件数据

    模板变量示例

    假设监控器 by 配置了 regionhost,且事件内容的模板如下:

    事件名称:

    监控器 {{ df_monitor_checker_name }} 发现 {{ df_dimension_tags }} 存在故障
    

    事件内容:

    - 地区:{{ region }}
    - 主机:{{ host }}
    - 级别:{{ df_status }}
    - 检测值:{{ Result }}
    - 监控器:{{ df_monitor_checker_name }}(告警策略:{{ df_monitor_name }})
    

    那么,产生 error 事件后,经过渲染的事件输出如下:

    输出事件名称:

    监控器 监控器001 发现 {"region":"hangzhou","host":"web-001"} 存在故障
    

    输出事件内容:

    - 地区:hangzhou
    - 主机:web-001
    - 级别:error
    - 检测值:90.12345
    - 监控器:监控器001(告警策略:团队001)
    

    特殊场景变量

    用户访问指标检测

    用户访问指标检测中,除了上述通用的模板变量外,额外支持下列模板变量:

    模板变量 类型 说明
    app_id String 应用 ID
    app_name String 应用名称
    app_type String 应用类型

    特殊字符字段处理

    若检测配置中 维度 字段包含特殊字符(如 -@),例如 host-name@level,则无法直接作为正常变量名使用,会导致模板渲染失败。

    解决方案是使用以下格式进行引用:

    • 使用 {{ df_event['host-name'] }} 替代 {{ host-name }}
    • 使用 {{ df_event['@level'] }} 替代 {{ @level }}

    模板函数

    除了可以直接展示事件中的字段值外,还可以使用模板函数对字段值进行进一步处理,优化输出。

    基本语法如下:

    {{ <模板变量> | <模板函数> }}
    

    具体实例如下:

    事件产生时间:{{ date | to_datetime }}
    

    如果模板函数需要传递参数,那么语法如下:

    事件产生时间:{{ date | to_datetime('America/Chicago') }}
    
    Warning

    如果需要在使用模板函数之前对模板变量进行运算,请不要忘记添加括号,如:

    CPU 使用率:{{ (Result * 100) | to_round(2) }}
    

    可用的模板函数列表如下:

    模板函数 参数 说明
    to_datetime 时区 将时间戳转换为日期(默认时区为Asia/Shanghai
    示例:{{ date | to_datetime }}
    输出:2022-01-01 01:23:45
    to_status_human df_status转换为易读形式
    示例:{{ df_status | to_status_human }}
    输出:紧急
    to_fixed 小数位数 将数字输出为固定小数位数(默认保留 0 位小数)
    示例:{{ Result | to_fixed(3) }}
    输出:1.230
    to_round 小数位数 将数字四舍五入(默认保留 0 位小数)
    示例:{{ Result | to_round(2) }}
    输出:1.24
    to_percent 小数位数 将小数输出为百分比(默认保留 0 位小数)
    示例:{{ Result | to_percent(1) }}
    输出:12.3%
    to_pretty_tags 美化输出标签
    示例:{{ df_dimension_tags | to_pretty_tags }}
    输出:region:hanghzou, host:web-001
    to_date_range_human df_fault_duration 转为易读形式
    示例:{{ df_fault_duration | to_date_range_human }}
    输出:X天 Y小时 Z分钟 W秒

    模板函数示例

    假设所配置的监控器 by 配置了 regionhost,且告警配置的模板如下:

    事件名称:

    监控器 {{ df_monitor_checker_name }} 发现 {{ df_dimension_tags | to_pretty_tags }} 存在故障
    

    事件内容:

    - 对象:{{ df_dimension_tags | to_pretty_tags }}
    - 时间:{{ date | to_datetime }}
    - 级别:{{ df_status | to_status_human }}
    - 检测值:{{ (Result * 100) | to_round(2) }}
    

    那么,产生 error 事件后,经过渲染的事件输出如下:

    输出事件名称:

    监控器 我的监控器 发现 region:hangzhou, host:web-001 存在故障
    

    输出事件内容:

    - 检测对象:region:hangzhou, host:web-001
    - 检测时间:2022-01-01 01:23:45
    - 故障级别:重要
    - 检测值:9012.35
    

    模板分支

    模板也支持使用分支语法根据条件渲染不同内容。

    模板分支示例

    可以使用以下语法实现分支功能:

    {% if df_status == 'critical' %}
    紧急问题,请立即处理!
    {% elif df_status == 'error' %}
    重要问题,请处理
    {% elif df_status == 'warning' %}
    可能有问题,有空处理
    {% elif df_status == 'nodata' %}
    数据中断,请立即处理!
    {% else %}
    没问题!
    {% endif %}
    

    更典型的例子如下:

    {% if  df_status != 'ok' %}
    > 等级:{{ df_status }}
    > 主机:{{ host }}
    > 内容:Elasticsearch JVM 堆内存的使用量为 {{ Result }}%
    > 建议:当前 JVM 垃圾的收集已经跟不上 JVM 垃圾的产生请及时查看业务情况
    
    {% else %}
    > 等级:{{df_status}}
    > 主机:{{host}}
    > 内容:Elasticsearch JVM 堆内存告警已恢复
    
    {% endif %}
    

    内嵌 DQL 查询函数

    在某些情况下,仅使用模板变量无法满足渲染需求。此时,可以使用内嵌 DQL 查询函数实现额外的数据查询。

    内嵌 DQL 查询函数支持在本工作空间下本次检测时间范围内执行任意 DQL 语句,通常情况下,查询所得的第一条数据可在模板中作为模板变量使用,使用方式如下:

    {% set dql_data = DQL("需要执行的 DQL 语句") %}
    
    某字段:{{ dql_data.some_field }}
    

    内嵌 DQL 查询示例

    以下内嵌 DQL 语句查询host字段为"my_server"的数据,并将第一条数据赋值给dql_data变量:

    {% set dql_data = DQL("O::HOST:(host, host_ip, os, datakit_ver) { host = 'my_server' }") %}
    
    主机 OS:{{ dql_data.os }}
    

    此后的模板中即可使用{{ dql_data.os }}输出查询结果中的具体字段。

    向内嵌 DQL 传递参数

    有时,所需执行的 DQL 语句需要传递参数。

    假设监控器 by 配置了 regionhost,且事件内容的模板如下:

    {% set dql_data = DQL("O::HOST:(host_ip, os) { region = ?, host = ? }", region, host) %}
    
    主机信息:
    IP:{{ dql_data.host_ip }}
    OS: {{ dql_data.os }}
    

    由于事件仅包含 regionhost 模板变量用于标记不同的数据,不包含 IP 地址、操作系统等更多信息。

    那么,使用内嵌 DQL 可以通过 regionhost 作为 DQL 查询参数获取对应数据,并使用 {{ dql_data.host_ip }} 等输出关联信息。

    内嵌 DQL 查询函数细节

    内嵌 DQL 查询函数调用格式如下:

    DQL(dql, param_1, param_2, ...)
    
    • 第 1 个参数为 DQL 语句,可以包含参数占位符 ?
    • 后续参数为 DQL 语句的参数值或变量

    参数占位符 ? 在替换为具体值的时候,系统会自动进行转义。

    假设,变量 host 值为 "my_server",那么内嵌 DQL 函数和所执行的最终 DQL 语句如下:

    DQL("O::HOST:(host, host_ip, os, datakit_ver) { host = ? }",  host)
    
    O::HOST:(host, host_ip, os, datakit_ver) { host = 'my_server' }
    
    Warning
    • 内嵌 DQL 查询应当放在模板开头
    • 查询结果名(这里是dql_data)遵循一般编程语言的命名要求,可以为任意英文开头,且仅包含英文、数字、下划线的字符串,不建议使用 emoji。
    • 查询结果名不要与现有的任何模板变量、模板函数重名,否则会产生不可预料的问题
    • 如果在 DQL 中对字段使用了函数,建议使用AS为字段取别名来方便后续使用(如:O::HOST:( last(host) AS last_host ))。
    • 如果 DQL 中字段名包含特殊字符,和模板变量一样,应当使用{{ dql_data['host-name'] }}{{ dql_data['@level'] }}进行渲染。

    更多 DQL 文档

    文档评价

    文档内容是否对您有帮助? ×