全部產品
Search
文件中心

Simple Log Service:內容範本文法(新版)

更新時間:Jul 26, 2024

新版警示支援兩個版本的內容範本文法。本文介紹新版內容範本文法。

概述

相對於舊版的內容範本文法,新版通過類似Python文法的方式,提供更加靈活且進階的自訂渲染邏輯,在定製通知內容(例如Markdown轉義)、自訂內容樣式等方面都做了最佳化,滿足更多樣化的定製內容需求。例如:

  • 根據警示的嚴重度進行動態內容渲染,不同嚴重度使用不同顏色的文字進行區分。

  • 對警示的查詢結果進行迭代渲染,在郵件中渲染為列表或者表格。

  • 通過函數對某個欄位進行BASE64編碼和解碼、對數值進行數學運算等。

新版的內容範本文法完全相容舊版,並支援新舊版混合使用。但在不同版本的內容範本文法中使用警示屬性時,其類型、取值和展示形式等存在差異,因此建議您不要混合使用新舊版本的內容範本文法。推薦您使用新版本的內容範本文法。

快速開始

通過新版內容範本定義通知內容的樣本如下:

  • 警示內容

    {
        "alert_id": "test-alert",
        "alert_name": "PV/UV Alert",
        "project": "project-1",
        "status": "firing",
        "severity": 6,
        "labels": {
            "app": "nginx",
            "host": "host-1"
        },
        "results": [
            {
                "project": "project-1",
                "logstore": "logstore-1",
                "query": "* | select count(*) as pv"
            },
            {
                "project": "project-2",
                "logstore": "logstore-2",
                "query": "* | select count(distinct user_id) as uv"
            }
        ]
    }
  • 內容範本配置

    - Alert ID: {{ alert.alert_id }}
    - Alert Name: {{ alert.alert_name }}
    - Project: {{ alert.project }}
    - Status: {% if alert.status == "firing" %}FIRING{% else %}RESOLVED{% endif %}
    - Labels:
    {%- for key, val in alert.labels.items() %}
        - {{ key }}: {{ val }}
    {%- endfor %}
    - Query: {{ alert.results[0].query }}
  • 輸出結果

    - Alert ID: test-alert
    - Alert Name: PV/UV Alert
    - Project: project-1
    - Status: FIRING
    - Labels:
        - app: nginx
        - host: host-1
    - Query: * | select count(*) as pv

基本文法

資料類型

內容範本文法類似於Python文法,支援如下資料類型。

資料類型

說明

數字

包含整數和浮點數。例如3、-1。

字串

需要使用單引號('')或者雙引號("")包裹。例如"foo"、'bar'。

當字串中存在特殊字元時,需使用反斜線(\)進行轉義。例如\foo需寫為"\\foo"

布爾值

True、False。

空值

None。

列表

不同程式設計語言中的叫法不同,可以為列表、數組、Slice等。例如['foo', 'bar']。

字典

不同程式設計語言中的叫法不同,可以為字典、對象等。例如{'foo': 'bar'}。

分隔字元

分隔字元

使用情境

樣本

{{ }}

在變數或運算式中使用。

  • 數字:{{ 123 }}

  • 字串:{{ "abc" }}或{{ 'xyz' }}

    需要使用雙引號("")或單引號('')。

  • 變數:{{ alert.alert_name }}

  • 運算式:{{ alert.project + '/' + alert.alert_id }}

{% %}

用於控制語句。

{% if alert.status == 'firing' %}FIRING{% else %}RESOLVED{% endif %}

{# #}

用於注釋,不會出現在通知內容中。

{# this is a comment #}

清除Null 字元

預設情況下,在分隔字元內部,分隔字元與運算式之間的空格會被忽略。例如{{ 23 }} < {{ 45 }}等同於{{23}} < {{45}},渲染結果都為23 < 45。但是分隔字元外部的Null 字元(空格、Tab、換行等)會被保留,例如{{ 23 }} < {{ 45 }}的渲染結果為23 < 45,而不是23<45

當您需要刪除多餘的Null 字元時,可以使用清除Null 字元操作。在分隔字元開始或結束的地方添加一個短劃線(-),用於清除該分隔字元前面和後面所有緊連著的Null 字元。例如{{ 23 -}} < {{- 45 }}的渲染結果為23<45

  • {{-{{%-{#-用於刪除分隔字元左側緊連著的所有Null 字元。

  • -}}-%}-%}用於刪除分隔字元右側緊連著的所有Null 字元。

重要
  • 短劃線(-)和分隔字元之間不能有空格。例如{{- 3 }}是有效,渲染結果為3{{ - 3 }}是無效的,渲染結果為-3

  • 清除Null 字元操作只對分隔字元外部的空格有效,不影響分隔字元內部的空格。例如{{ "hello " }} {{- "world"}}渲染結果為hello world

條件陳述式

條件判斷支援對參數或者邏輯比較運算式進行判斷。通過條件判斷,可以進行動態渲染。

  • 如果if後面傳入的是常量或者普通變數,則對該值進行真值判斷。其中布爾值false、數字0、Null 字元串""、空值null、空數組[]、Null 物件{}都會被判定為假,其它值被判定為真。

  • 如果if後面傳入的是邏輯比較運算式,則按照比較結果進行判斷。例如{{ if alert.severity >= 8 }}用於判斷警示嚴重度是否大於等於8。

條件判斷支援如下幾種形式:

使用方式

樣本

if

{% if alert.severity >= 8 %}
嚴重警示
{% endif %}

if-else

{% if alert.severity >= 8 %}
嚴重警示
{% else %}
普通警示
{% endif %}

if-elif

{% if alert.severity >= 8 %}
嚴重警示
{% elif alert.severity >= 4 %}
普通警示
{% endif %}

if-elif-else

{% if alert.severity >= 8 %}
嚴重警示
{% elif alert.severity >= 4 %}
普通警示
{% else %}
通知
{% endif %}

嵌套使用

{% if alert.severity >= 8 %}
嚴重警示
{% else %}
{% if alert.severity >= 4 %}
普通警示
{% else %}
通知
{% endif %}
{% endif %}

迭代

迴圈語句用於對數組和對象進行迭代操作。支援如下幾種使用方式:

使用方式

樣本

數組迭代

{% for result in alert.results %}
{{ result }}
{% endfor %}

數組迭代,包含下標

使用enumerate函數對數組進行下標迭代。關於enumerate函數的更多資訊,請參見enumerate函數

{% for index, result in enumerate(alert.results) %}
{{ index }}: {{ result }}
{% endfor %}

下標預設從0開始。您也可以通過enumerate函數中的start參數自訂起始下標。例如:

{% for index, result in enumerate(alert.results, start=1) %}
{{ index }}: {{ result }}
{% endfor %}

對象迭代

通過items()方法將對象轉為Key:Value形式的數組進行迭代。

{% for key, val in alert.labels.items() %}
{{ key }}: {{ val }}
{% endfor %}

嵌套使用

{% for result in alert.fire_results %}
{% for key, val in result.items() %}
{{ key }}: {{ val }}
{% endfor %}
{% endfor %}

轉義

如果您希望特殊字元串(例如{{)不被內容範本解析和渲染,可對特殊字元串進行轉義。例如:根據如下配置表示保留{% raw %}{% endraw %}之間所有的內容。

  • 內容範本配置

    {% raw %}
    {% for result in alert.results %}
    {{ result }}
    {% endfor %}
    {% endraw %}
  • 結果

    {% for result in alert.results %}
    {{ result }}
    {% endfor %}

函數

內建模板函數便於您對資料進行各種操作,豐富了通知內容的格式和展示樣式。更多資訊,請參見內建模板函數

例如您要通過Webhook方式發送JSON格式的內容,相關資訊如下:

  • 警示的查詢語句(包含一個換行)

    * |
    select count(*) as cnt
  • 不同使用方式的對比說明

    對比項

    內容範本

    結果

    說明

    不使用函數

    {
        "query": "{{ alert.results[0].query }}"
    }
    {
        "query": "* |
    select count(*) as pv"
    }

    JSON格式不合法

    使用quote函數

    {
        "query": {{ quote(alert.results[0].query) }}
    }
    {
        "query": "* | \nselect count(*) as pv"
    }

    JSON格式合法

過濾器

在函數嵌套使用情境中,通知內容的編輯麻煩且不夠直觀,例如{{ block(to_list(alert.labels)) }},此時您可以使用過濾器功能。過濾器使用豎線(|) 操作符,並支援鏈式調用,一般格式為{{ xxx | filiter1 | filter2 | ... }}。例如{{ blockquote(to_list(alert.labels)) }}等同於{{ alert.labels | to_list | blockquote }}

使用過濾器方式時,請先確認目標內建函數是否支援過濾器方式。大部分內建函數都支援過濾器方式的調用。更多資訊,請參見內建模板函數

重要
  • 如果函數中沒有參數,則只能使用函數方式,不支援過濾器方式。

  • 當函數中只有一個參數時,推薦使用過濾器方式,即使用{{ arg | fn }}。例如{{ abs(-1) }} 等同於{{ -1 | abs }}

  • 如果函數中有多個參數,且從第二個參數開始有預設值,也可以使用過濾器。如果有多個參數值需要傳遞,通過過濾器方式並不直觀。不建議對多參數的函數使用過濾器方式。

操作符

內容範本運算式中支援如下操作符。操作符的優先順序說明請參見Operator precedence

類別

操作符

說明

算數

+

加法

-

減法

*

乘法

/

除法,傳回值是一個浮點數。

//

除法,返回整數。

%

模數

比較

==

等於

!=

不等於

>

大於

>=

大於等於

<

小於

<=

小於等於

邏輯

and

且操作

or

或操作

not

取反

其它

in

判斷是否包含,返回布爾類型的結果。

  • 數組:{{ 1 in [1, 2, 3] }}

  • 對象:{{ "foo" in {"foo": "bar" } }}

  • 字串:{{ "ll" in "hello" }}

()

操作組合,例如:{{ a > b and (a > c or b > c) }}

使用警示變數

在新版內容範本中,警示變數的使用形式為alert.xxx,例如alert.project。更多資訊,請參見內容範本變數說明(新版)

配置樣本

  • 樣本1:根據警示狀態展示不同內容

    觸發警示後,展示警示狀態、警示嚴重度和觸發結果等資訊;警示恢複時,只展示警示狀態。

    • 不使用函數

      {% if alert.status == "firing" %}
      - 狀態: <font color="#E03C39">觸發</font>
      - 嚴重度:{{ alert.severity | format_severity }}
      - Results: {{ alert.results | to_json }}
      {% else %}
      - 狀態: <font color="#72C140">恢複</font>
      {% endif %}
    • 使用函數

      使用format_status函數和format_severity函數簡化配置。

      - 狀態: {{ alert.status | format_status }}
      {% if alert.status == "firing" %}
      - 嚴重度:{{ alert.severity | format_severity }}
      - Results: {{ alert.results | to_json }}
      {% endif %}
  • 結構化資料展示

    將警示標籤的內容轉換為列表形式,內容為Markdown格式。

    • 不使用函數

      - 專案: {{ alert.project }}
      - 警示名稱: {{ alert.alert_name }}
      - 警示標籤:
      {%- for key, val in alert.labels.items() %}
      > - {{ key }}: {{ val }}
      {%- endfor %}
    • 使用函數

      使用to_list函數和blockquote函數簡化配置。

      - 專案: {{ alert.project }}
      - 警示名稱: {{ alert.alert_name }}
      - 警示標籤:
      {{ alert.labels | to_list | blockquote }}