Simple Log Service:Syntax for new alert templates

Overview

The syntax for the new alert templates is fully compatible and can be used with the syntax for the original alert templates. However, the syntax for the new alert templates uses different types, values, and styles for alert attributes than the syntax for the original alert templates. Therefore, we recommend that you do not simultaneously use the syntax for the new alert templates and the syntax for the original alert templates. We recommend that you use the syntax for the new alert templates.

Quick start

This section provides example notification content that can be defined in the new alert templates.

• Alert content:

  {
      "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 template configuration:

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

• Output result:

  - 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

Basic syntax

By default, when you use delimiters to mark the start and end of an expression, Simple Log Service ignores the spaces between a delimiter and the expression inside the delimiters. For example, Simple Log Service renders both {{ 23 }} < {{ 45 }} and {{23}} < {{45}} into 23 < 45. However, Simple Log Service retains the empty strings such as spaces, tabs, and line feeds outside the delimiters. For example, Simple Log Service renders {{ 23 }} < {{ 45 }} into 23 < 45 rather than 23<45.

Conditional flows are used to evaluate the values of parameters and the results of logical expressions. Simple Log Service can render data based on conditional flows.

• If the if clause is followed by a constant or a regular variable, Simple Log Service evaluates the constant or the value of the regular variable to true or false. Simple Log Service evaluates all Boolean values false, numbers 0, empty strings "", empty values null, empty arrays [], and empty objects {} to false and evaluates all the other values to true.

• If the if clause is followed by a logical expression, Simple Log Service evaluates the result of the logical expression to true or false. For example, {{ if alert.severity >= 8 }} is used to evaluate whether the severity level of an alert is greater than or equal to 8.

{% if alert.severity >= 8 %}
Critical alert
{% endif %}

{% if alert.severity >= 8 %}
Critical alert
{% else %}
Normal alert
{% endif %}

{% if alert.severity >= 8 %}
Critical alert
{% elif alert.severity >= 4 %}
Normal alert
{% endif %}

{% if alert.severity >= 8 %}
Critical alert
{% elif alert.severity >= 4 %}
Normal alert
{% else %}
Notification
{% endif %}

{% if alert.severity >= 8 %}
Critical alert
{% else %}
{% if alert.severity >= 4 %}
Normal alert
{% else %}
Notification
{% endif %}
{% endif %}

Loop statements are used to perform iterative operations on arrays and objects. The following table describes the loop statements that are supported by the new alert templates.

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

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

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

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

If you do not want Simple Log Service to parse or render strings such as {{ that consist of special characters, you can escape the strings. For example, the following alert template configuration specifies to retain all content between {% raw %} and {% endraw %}:

• Alert template configuration

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

• Result

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

Alert templates provide built-in functions. You can use the built-in functions to flexibly configure the formats and styles of alert notifications. For more information, see Built-in functions in alert templates.

For example, if you want Simple Log Service to push alert notifications in the JSON format by using a webhook URL, you must specify the following alert template configuration:

• Query statement with a line feed included

  * |
  select count(*) as cnt

• Comparison between different alert template configurations

  Item	Alert template	Result	Remarks
  No functions used	{ "query": "{{ alert.results[0].query }}" }	{ "query": "* | select count(*) as pv" }	The JSON format is invalid.
  The quote function used	{ "query": {{ quote(alert.results[0].query) }} }	{ "query": "* | \nselect count(*) as pv" }	The JSON format is valid.

If nested functions such as {{ block(to_list(alert.labels)) }} are used, edits to notification content are laborious. In this situation, you can use filters to edit notification content. Filters use vertical bars (|) as operators and can be invoked by using method chaining. In most cases, you can specify filters in the {{ xxx | filiter1 | filter2 | ... }} format. For example, {{ blockquote(to_list(alert.labels)) }} is equivalent to {{ alert.labels | to_list | blockquote }}.

Before you specify filters in a built-in function, you must check that the built-in function supports filters. Most of the built-in functions that are available in the new alert templates support filters. For more information, see Built-in functions in alert templates.

The following table describes the operators that are supported by the new alert templates. For more information about the priorities of the operators, see Operator precedence.

Alert variables

In the new alert templates, alert variables are in the alert.xxx format. For example, the alert.project variable is a valid alert variable. For more information, see Variables in new alert templates.

Configuration examples

• Example 1: Display the information about each alert based on the status of the alert.

  After an alert is triggered, the information such as the status, severity level, and result of the alert is provided. When an alert is cleared, only the status of the alert is provided.

  • The following alert template configuration does not include functions:

    {% if alert.status == "firing" %}
    - Status: <font color="#E03C39">Firing</font>
    - Severity level: {{ alert.severity | format_severity }}
    - Results: {{ alert.results | to_json }}
    {% else %}
    - Status: <font color="#72C140">Cleared</font>
    {% endif %}

  • The following alert template configuration includes functions:

    The format_status function and the format_severity function are used to simplify the alert template configuration:

    - Status: {{ alert.status | format_status }}
    {% if alert.status == "firing" %}
    - Severity level: {{ alert.severity | format_severity }}
    - Results: {{ alert.results | to_json }}
    {% endif %}

• Example 2: Display the information about each alert in a structured format.

  The labels of each alert are converted into an array in the Markdown format.

  • The following alert template configuration does not include functions:

    - Project: {{ alert.project }}
    - Alert name: {{ alert.alert_name }}
    - Label:
    {%- for key, val in alert.labels.items() %}
    > - {{ key }}: {{ val }}
    {%- endfor %}

  • The following alert template configuration includes functions:

    The to_list function and the blockquote function are used to simplify the alert template configuration.

    - Project: {{ alert.project }}
    - Alert name: {{ alert.alert_name }}
    - Label:
    {{ alert.labels | to_list | blockquote }}