正在加载

规则操作变量

Elastic Stack 无服务器

警报规则可以使用 Mustache 模板语法 ({{变量名称}}) 在操作运行时传递值。

可用变量因规则类型而异，但有一些常用变量

在某些情况下，当变量值用于需要转义的上下文中时，变量值将被“转义”。例如

  • 对于 电子邮件连接器，message 操作配置属性会对任何会被解释为 Markdown 的字符进行转义。
  • 对于 Slack 连接器，message 操作配置属性会对任何会被解释为 Slack Markdown 的字符进行转义。
  • 对于 Webhook 连接器，body 操作配置属性会对 JSON 字符串值中无效的任何字符进行转义。

Mustache 还支持 {{{变量名称}}} 形式的“三重大括号”，表示不应进行任何转义。谨慎使用此形式，因为它最终可能会呈现变量内容，从而导致生成的参数无效或格式不正确。

所有规则类型都传递以下变量

date
规则计划操作的日期，采用 ISO 格式。
kibanaBaseUrl
配置的 server.publicBaseUrl。如果未配置，则此值为空。
rule.id
规则标识符。
rule.name
规则名称。
rule.params
规则参数，因规则类型而异。
rule.spaceId
规则的空间标识符。
rule.tags
应用于规则的标签列表。
rule.url
生成警报的规则的 URL。如果未配置 server.publicBaseUrl 设置，则此值为空字符串。

如果规则的操作频率是警报摘要，则它会传递以下变量

alerts.all.count
所有警报的计数。
alerts.all.data

所有警报的对象数组。以下对象属性是示例；它不是一个全面的列表。

alerts.all.data 对象的属性:

kibana.alert.end
警报结束的时间戳。[预览]
kibana.alert.flapping
警报上的一个标志，指示警报状态是否正在重复更改。[预览]
kibana.alert.instance.id
生成警报的源的 ID。[预览]
kibana.alert.reason
警报的原因（使用规则条件生成）。[预览]
kibana.alert.start
警报开始的时间戳。[预览]
kibana.alert.status
警报状态（例如，活动或 OK）。[预览]
alerts.new.count
新警报的计数。
alerts.new.data

新警报的对象数组。以下对象属性是示例；它不是一个全面的列表。

alerts.new.data 对象的属性:

kibana.alert.end
警报结束的时间戳。[预览]
kibana.alert.flapping
警报上的一个标志，指示警报状态是否正在重复更改。[预览]
kibana.alert.instance.id
生成警报的源的 ID。[预览]
kibana.alert.reason
警报的原因（使用规则条件生成）。[预览]
kibana.alert.start
警报开始的时间戳。[预览]
kibana.alert.status
警报状态（例如，活动或 OK）。[预览]
alerts.ongoing.count
正在进行的警报的计数。
alerts.ongoing.data

正在进行的警报的对象数组。以下对象属性是示例；它不是一个全面的列表。

alerts.ongoing.data 对象的属性:

kibana.alert.end
警报结束的时间戳。[预览]
kibana.alert.flapping
警报上的一个标志，指示警报状态是否正在重复更改。[预览]
kibana.alert.instance.id
生成警报的源的 ID。[预览]
kibana.alert.reason
警报的原因（使用规则条件生成）。[预览]
kibana.alert.start
警报开始的时间戳。[预览]
kibana.alert.status
警报状态（例如，活动或 OK）。[预览]
alerts.recovered.count
已恢复警报的计数。
alerts.recovered.data

已恢复警报的对象数组。以下对象属性是示例；它不是一个全面的列表。

alerts.recovered.data 对象的属性:

kibana.alert.end
警报结束的时间戳。[预览]
kibana.alert.flapping
警报上的一个标志，指示警报状态是否正在重复更改。[预览]
kibana.alert.instance.id
生成警报的源的 ID。[预览]
kibana.alert.reason
警报的原因（使用规则条件生成）。[预览]
kibana.alert.start
警报开始的时间戳。[预览]
kibana.alert.status
警报状态（例如，活动或 OK）。[预览]

如果规则的操作频率不是警报摘要，则它会传递以下变量

alert.actionGroup
计划操作的警报的操作组 ID。
alert.actionGroupName
计划操作的警报的操作组名称。
alert.actionSubgroup
计划操作的警报的操作子组。
alert.consecutiveMatches
满足规则条件的连续运行次数。
alert.flapping
警报上的一个标志，指示警报状态是否正在重复更改。
alert.id
计划操作的警报的 ID。
alert.uuid
警报的通用唯一标识符。在警报处于活动状态时，每次规则运行时，UUID 值都保持不变。[预览]

如果规则的操作频率不是警报摘要，则规则将定义其他变量作为变量 context 的属性。例如，如果规则类型定义了变量 value，则可以在操作参数中将其用作 {{context.value}}。

出于诊断或探索目的，可以将值是对象的操作变量（例如 context）直接作为变量引用。结果值将是对象的 JSON 表示形式。例如，如果操作参数包含 {{context}}，它将展开为规则类型提供的所有变量和值的 JSON 表示形式。要查看所有特定于警报的变量，请使用 {{.}}。

对于规则响应返回数据数组的情况，您可以循环访问 context

{{#context}}{{.}}{{/context}}

例如，循环访问搜索结果命中

triggering data was:
{{#context.hits}} - {{_source.message}}
{{/context.hits}}
警告

此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览版中的功能不受官方 GA 功能的支持 SLA 的约束。

您可以通过将对象渲染为 JSON 或使用 Mustache lambdas 来增强 Mustache 模板在渲染时包含在 Mustache 变量中的值。

将对象渲染为 JSON

某些连接器（例如 Webhook 连接器）期望在调用连接器时将 JSON 值作为参数传递。以下功能可用

  • 在花括号中引用的数组值具有预定义的渲染，Mustache 将其渲染为数组元素的字符串版本，并用逗号 (,) 连接。要将数组值渲染为 JSON，请访问数组的 asJSON 属性，而不是直接访问数组。例如，给定一个 Mustache 变量 context.values，其值为 [1, 4, 9]，Mustache 模板 {{context.values}} 将渲染为 1,4,9，而 Mustache 模板 {{context.values.asJSON}} 将渲染为 [1,4,9]。
  • ParseHjson lambda Mustache lambda 使您可以通过使用 Hjson（JSON 的语法扩展）而不是严格的 JSON，更轻松地在模板中创建 JSON。

使用 Mustache Lambdas

Mustache lambdas 为 Mustache 模板提供额外的渲染功能。Mustache lambda 的格式类似于 Mustache 部分。例如

{{#EvalMath}} round(context.value, 1) {{/EvalMath}}

在该示例中，lambda EvalMath 被传递文本 round(context.value, 1) 并渲染 context.value 变量的舍入值。后续部分中描述的所有提供的 Mustache lambdas 都使用此模式。

EvalMath

EvalMath lambda 将评估传递给它的文本作为 TinyMath 函数。

例如，当 Mustache 变量 context.value 为 3.1234 时，以下模板将渲染为 3.1

{{#EvalMath}} round(context.value, 1) {{/EvalMath}}

此 lambda 可以访问 Mustache 变量，而无需将它们包装在 {{}} 中。但是，如果该值是字符串形式（例如，其源作为字符串编制索引的 Elasticsearch 数字字段），或者可能被转义，则使用三引号转义该值应允许其工作。例如，如果 Mustache 变量 context.value 为 "3.1234"，则以下模板将渲染为 3.1

{{#EvalMath}} round( {{{context.value}}} , 1) {{/EvalMath}}

ParseHjson lambda 在构造 JSON 对象时提供易用性功能。Hjson 是 JSON 的语法扩展。它具有以下功能

  • 在数组和对象中允许缺少和额外的尾随逗号。
  • 支持注释。
  • 可以不带引号指定属性名称。
  • 可以不带引号指定属性值（每行一个，没有逗号）。
  • 多行字符串具有 dedent 支持以删除前导空格。
  • 支持合法的 JSON 文档。

要使用它，请用 {{#ParseHjson}}...{{/ParseHjson}} 包围您的 Hjson 内容。例如

{{#ParseHjson}}
{
  # add the rule id and name to the JSON document
  ruleId:   "{{rule.id}}"
  ruleName: "{{rule.name}}"
}
{{/ParseHjson}}

渲染时，此模板将生成

{
  "ruleId": "<the rule id is here>",
  "ruleName": "<the rule name is here>"
}

FormatDate

FormatDate lambda 提供日期格式化功能。日期可以用任意时区和任意格式字符串进行格式化。

要使用它，请用 {{#FormatDate}}...{{/FormatDate}} 包围日期和格式化参数。

传递给 lambda 的文本格式为：<date>; <time zone>; <date format>，其中分号 (;) 分隔每个参数。<date> 参数是必需的；<time zone> 和 <date format> 参数是可选的。默认时区为 "UTC"，默认日期格式为 "YYYY-MM-DD hh:mma"。例如，以下模板都渲染相同的值

{{#FormatDate}} {{{timestamp}}} {{/FormatDate}}
{{#FormatDate}} {{{timestamp}}} ; UTC {{/FormatDate}}
{{#FormatDate}} {{{timestamp}}} ; UTC; YYYY-MM-DD hh:mma {{/FormatDate}}
{{#FormatDate}} {{{timestamp}}} ; ; YYYY-MM-DD hh:mma {{/FormatDate}}

<time zone> 参数必须是 TZ 数据库时区名称中列出的有效时区标识符，例如 "America/New_York"。

<date format> 参数必须是有效的日期格式字符串，如 Moment format() 文档中所述。例如，日期格式 "YYYY-MM-DD hh:mma" 将呈现为以下格式："2023-04-24 11:21pm"。

日期值本身通常应使用三重大括号引用，因为日期字符串中的某些字符可能包含需要转义的值，这将阻止它们被解析为日期。

FormatNumber

FormatNumber lambda 使用 Intl.NumberFormat 对象提供数字格式化功能。

数字可以使用以下 Intl.NumberFormat 选项进行格式化

  • compactDisplay
  • currencyDisplay
  • currencySign
  • notation
  • signDisplay
  • unitDisplay
  • unit
  • useGrouping - 但仅限 true 和 false 值
  • minimumIntegerDigits
  • minimumFractionDigits
  • maximumFractionDigits
  • minimumSignificantDigits
  • maximumSignificantDigits

要使用 lambda，请将数字和格式化选项用 {{#FormatNumber}}...{{/FormatNumber}} 包围。

传递给 lambda 的文本格式为：<number>; <locales>; <options>，其中分号 (;) 分隔每个参数。 <number> 参数是必需的； 它是要格式化的值。 <locales> 和 <options> 参数是可选的，但必须提供分号； 这些值可以为空字符串。 <locales> 参数是由逗号 (,) 分隔的区域设置列表。 <options> 参数是由逗号 (,) 分隔的键值对列表。 键值对是由冒号 (:) 分隔的字符串，其中键是选项的名称，值是选项的值。 默认区域设置是 en-US，默认情况下不设置任何选项。

有关区域设置字符串的更多信息，请参阅 Intl 参考中的 locales 参数文档。

可在 Intl.NumberFormat() 构造函数文档的 options 下找到可使用的选项和值。

例如

original value: {{{context.value.condition0}}}
formatted value: {{#FormatNumber}}
    {{{context.value.condition0}}} ; de-DE ; style: currency, currency: EUR
{{/FormatNumber}}

如果上下文变量 context.value.condition0 的值为 628.4，则会生成以下文本

original value: 628.4
formatted value: 628,40 €

{{FormatNumber}} 和 {{EvalMath}} lambda 可以一起使用，以对数字执行计算，然后对其进行格式化。 例如

original value: {{{context.value.condition0}}}
formatted value: {{#FormatNumber}}
  {{#EvalMath}} {{context.value.condition0}} * 0.1 {{/EvalMath}}
  ; de-DE ; style: currency, currency: EUR
{{/FormatNumber}}

如果上下文变量 context.value.condition0 的值为 628.4，则会生成以下文本

original value: 628.4
formatted value: 62,84 €

此示例演示了从 Elasticsearch 查询规则发送的电子邮件操作的 Mustache 模板。 该模板引用以下 Mustache 变量

  • date
  • context.title
  • context.conditions
  • context.link
  • context.hits[]._source.event.provider
  • context.hits[]._source.event.action
  • context.hits[]._source.event.duration

例如，如果你的数据像这样作为 Mustache 变量可用

{
  "date": "2023-04-27T22:40:34.153Z",
  "context": {
    "title": "rule 'esq' matched query for group host-2",
    "conditions": "Number of matching documents for group \"host-2\" is less than 1000",
    "link": "https://example.com/this-will-link-to-Discover",
    "hits": [
      {
        "_source": {
          "event": {
            "provider": "alerting",
            "action": "active-instance",
            "duration": "96023000000"
          }
        }
      },
      {
        "_source": {
          "@timestamp": "2023-04-27T22:40:22.251Z",
          "event": {
            "provider": "alerting",
            "action": "execute-action"
          }
        }
      }
    ]
  }
}

你可以在规则的电子邮件操作中创建以下 Mustache 模板

# {{context.title}}

{{#FormatDate}} {{{date}}} ; America/New_York {{/FormatDate}}

{{context.conditions}}

**documents** _[view in Discover]({{{context.link}}})_

| provider | action | duration |
| -------- | ------ | -------- |
{{#context.hits}}{{#_source.event}}| {{provider}} | {{action}} | {{#duration}}{{#EvalMath}} round( {{{duration}}} / 1000 / 1000 / 1000 ) {{/EvalMath}} sec{{/duration}} {{^duration}}-n/a-{{/duration}} |{{/_source.event}}
{{/context.hits}}
  1. 将 context.title 变量的值呈现为 1 级标题。
  2. 将 date 变量的值呈现为 America/New_York 时区中的格式化日期。
  3. 显示 **bold**、_italic_ 和 [text](url) 链接的示例。
  4. 显示一个包含三列的表格，context.hits 数组中的每个元素对应一行。 从这些元素中的每一个，你可以访问 _source.event 对象的 provider、action 和 duration 字段。 duration 字段呈现为秒数，四舍五入到最接近的秒。 它存储为纳秒，因此需要除以 10 亿才能产生秒数。 duration 字段是可选的，因此你可以使用 {{#duration}} ... {{/duration}} 部分来呈现 duration（如果存在），否则显示 -n/a-。

当呈现为 Markdown，然后呈现为 HTML 并在电子邮件客户端中查看时，它看起来像这样

Email template rendered in an email client

© . All rights reserved.