文档文档

Kapacitor

模板任务

在 CLI 和 API 中使用模板来定义和重用任务。

要创建任务模板，请执行以下操作：

  1. 创建任务模板脚本
  2. 运行 define-template 命令
  3. 定义一个新任务

一些第三方服务会拒绝以换行符结尾的标准 json。要删除换行符，请在模板中将 {{ json . }} 替换为 {{ jsonCompact . }}。

创建任务模板时，请考虑以下几点：

Chronograf **不**显示模板详细信息，包括变量值。

创建任务模板脚本

以下任务模板脚本计算字段的平均值并触发警报。

示例：generic_alert_template.tick

// Which measurement to consume
var measurement string
// Optional where filter
var where_filter = lambda: TRUE
// Optional list of group by dimensions
var groups = [*]
// Which field to process
var field string
// Warning criteria, has access to 'mean' field
var warn lambda
// Critical criteria, has access to 'mean' field
var crit lambda
// How much data to window
var window = 5m
// The slack channel for alerts
var slack_channel = '#alerts'

stream
    |from()
        .measurement(measurement)
        .where(where_filter)
        .groupBy(groups)
    |window()
        .period(window)
        .every(window)
    |mean(field)
    |alert()
         .warn(warn)
         .crit(crit)
         .slack()
         .channel(slack_channel)

请注意，脚本中的所有字段都已声明为变量，这允许您在使用模板定义任务时自定义变量值。

定义变量

在任务模板中，使用以下模式定义变量：

// Required variable pattern
var varName dataType

// Optional variable patterns
var varName = dataType: defaultValue
var varName = [*]

有关可用数据类型的信息，请参阅 字面值类型。

可选变量

在某些情况下，模板任务可能用于不需要所有模板变量值的任务。为确保变量是可选的，请提供一个默认值。在大多数情况下，默认值可以简单地设置为 TRUE。

// Pattern
var varName = datatype: defaultValue

// Examples
var where_filter = lambda: TRUE
var warn = lambda: TRUE
var groups = [*]

运行 define-template 命令

要定义新模板，请运行 define-template 命令。

kapacitor define-template generic_mean_alert -tick path/to/template_script.tick

使用 show-template 查看有关新创建模板的更多信息。

kapacitor show-template generic_mean_alert

作为控制台输出的一部分，将返回一个已声明模板的变量列表，该列表包含在 vars 组中，如下例所示：

示例：kapacitor show-template 输出的 Vars 部分

...

Vars:
Name           Type      Default Value  Description
crit           lambda    <required>     Critical criteria, has access to 'mean' field
field          string    <required>     Which field to process
groups         list      [*]            Optional list of group by dimensions
measurement    string    <required>     Which measurement to consume
slack_channel  string    #alerts        The slack channel for alerts
warn           lambda    <required>     Warning criteria, has access to 'mean' field
where_filter   lambda    TRUE           Optional where filter
window         duration  5m0s           How much data to window

...

每个任务都将从模板继承其类型和 TICKscript 结构。变量描述源自模板中每个变量上方的注释。变量以及数据库/保留策略的具体值对于使用模板创建的每个任务都是唯一的。

定义一个新任务

使用模板定义一个新任务，以触发 CPU 使用率警报。

  1. 使用简单的 JSON 文件将变量值传递到模板。

    示例：JSON 变量文件

    {
   "measurement": {"type" : "string", "value" : "cpu" },
   "where_filter": {"type": "lambda", "value": "\"cpu\" == 'cpu-total'"},
   "groups": {"type": "list", "value": [{"type":"string", "value":"host"},{"type":"string", "value":"dc"}]},
   "field": {"type" : "string", "value" : "usage_idle" },
   "warn": {"type" : "lambda", "value" : "\"mean\" < 30.0" },
   "crit": {"type" : "lambda", "value" : "\"mean\" < 10.0" },
   "window": {"type" : "duration", "value" : "1m" },
   "slack_channel": {"type" : "string", "value" : "#alerts_testing" }
}

  2. 通过运行带有 -template 和 -vars 参数的命令，传入模板文件和 JSON 变量文件。

    kapacitor define cpu_alert -template generic_mean_alert -vars cpu_vars.json -dbrp telegraf.autogen

  3. 使用 show 命令显示与新创建任务关联的变量值。

    对于启用了身份验证的 Kapacitor 实例，请使用以下格式：

    ./kapacitor -url http://username:password@MYSERVER:9092 show TASKNAME
示例
kapacitor show cpu_alert
...

Vars:
Name           Type      Value
crit           lambda    "mean" < 10.0
field          string    usage_idle
groups         list      [host,dc]
measurement    string    cpu
slack_channel  string    #alerts_testing
warn           lambda    "mean" < 30.0
where_filter   lambda    "cpu" == 'cpu-total'
window         duration  1m0s

...

可以使用相同的模板创建类似的内存警报任务。创建 mem_vars.json 并使用此代码片段。

示例：内存警报的 JSON 变量文件

{
    "measurement": {"type" : "string", "value" : "mem" },
    "groups": {"type": "list", "value": [{"type":"star", "value":"*"}]},
    "field": {"type" : "string", "value" : "used_percent" },
    "warn": {"type" : "lambda", "value" : "\"mean\" > 80.0" },
    "crit": {"type" : "lambda", "value" : "\"mean\" > 90.0" },
    "window": {"type" : "duration", "value" : "10m" },
    "slack_channel": {"type" : "string", "value" : "#alerts_testing" }
}

现在可以像以前一样定义任务，但这次使用新的变量文件和不同的任务标识符。

kapacitor define mem_alert -template generic_mean_alert -vars mem_vars.json -dbrp telegraf.autogen

运行 show 将显示与此任务关联的 vars，这些 vars 特定于 mem_alert 任务。

kapacitor show mem_alert

再次显示 vars 输出。

示例：mem_alert 任务的 Vars 部分

...
Vars:
Name           Type      Value
crit           lambda    "mean" > 90.0
field          string    used_percent
groups         list      [*]
measurement    string    mem
slack_channel  string    #alerts_testing
warn           lambda    "mean" > 80.0
window         duration  10m0s
...

可以使用相同的模板定义任意数量的任务。

**注意：** 对模板的更新将更新所有关联的任务，并在必要时重新加载它们。

使用变量

变量也适用于普通任务，并可用于覆盖脚本中的任何默认值。由于任何 TICKscript 都可能在将来作为模板使用，因此推荐的最佳实践是在 TICKscripts 中始终使用 var 声明。普通任务可以正常工作，如果将来您决定需要另一个类似的，您可以轻松地从现有的 TICKscript 创建一个模板，并使用变量文件定义其他任务。

使用 -file 标志

从 Kapacitor 1.4 开始，可以使用任务定义文件从模板生成任务。任务定义文件扩展了之前版本中的变量文件。提供了三个新字段。

  • template-id 字段用于选择模板。
  • dbrps 字段用于定义任务将使用的数据库/保留策略集（一个或多个）。
  • vars 字段将变量组合在一起，这些变量是之前版本中文件的核心。

此文件可以是 JSON 或 YAML 格式。

可以使用上面定义的相同模板创建内存警报任务。创建一个 mem_template_task.json 文件，使用示例 7 中的代码片段。

示例：JSON 格式的任务定义文件

{
  "template-id": "generic_mean_alert",
  "dbrps": [{"db": "telegraf", "rp": "autogen"}],
  "vars": {
    "measurement": {"type" : "string", "value" : "mem" },
    "groups": {"type": "list", "value": [{"type":"star", "value":"*"}]},
    "field": {"type" : "string", "value" : "used_percent" },
    "warn": {"type" : "lambda", "value" : "\"mean\" > 80.0" },
    "crit": {"type" : "lambda", "value" : "\"mean\" > 90.0" },
    "window": {"type" : "duration", "value" : "10m" },
    "slack_channel": {"type" : "string", "value" : "#alerts_testing" }
  }
}

然后可以使用 file 参数定义任务，该参数带有任务定义文件的新内容，替换了命令行参数 template、dbrp 和 vars。

kapacitor define mem_alert -file mem_template_task.json

使用 YAML，任务定义文件 mem_template_task.yaml 如下所示：

示例：YAML 格式的任务定义文件

template-id: generic_mean_alert
dbrps:
- db: telegraf
  rp: autogen
vars:
  measurement:
    type: string
    value: mem
  groups:
    type: list
    value:
    - type: star
      value: "*"
  field:
    type: string
    value: used_percent
  warn:
    type: lambda
    value: '"mean" > 80.0'
  crit:
    type: lambda
    value: '"mean" > 90.0'
  window:
    type: duration
    value: 10m
  slack_channel:
    type: string
    value: "#alerts_testing"

然后可以使用如前所示的 file 参数定义任务。

kapacitor define mem_alert -file mem_template_task.yaml

隐式指定 dbrp

以下是一个简单的示例，定义了一个计算字段平均值并触发警报的模板，其中 dbrp 在模板中指定。

示例：在模板中定义数据库和保留策略

dbrp "telegraf"."autogen"

// Which measurement to consume
var measurement string
// Optional where filter
var where_filter = lambda: TRUE
// Optional list of group by dimensions
var groups = [*]
// Which field to process
var field string
// Warning criteria, has access to 'mean' field
var warn lambda
// Critical criteria, has access to 'mean' field
var crit lambda
// How much data to window
var window = 5m
// The slack channel for alerts
var slack_channel = '#alerts'

stream
    |from()
        .measurement(measurement)
        .where(where_filter)
        .groupBy(groups)
    |window()
        .period(window)
        .every(window)
    |mean(field)
    |alert()
         .warn(warn)
         .crit(crit)
         .slack()
         .channel(slack_channel)

从此模板脚本定义一个新模板。

kapacitor define-template implicit_generic_mean_alert -tick path/to/script.tick

然后以 YAML 文件 implicit_mem_template_task.yaml 定义任务。

示例：利用预定义数据库和保留策略的模板的 YAML 变量文件

template-id: implicit_generic_mean_alert
vars:
  measurement:
    type: string
    value: mem
  groups:
    type: list
    value:
    - type: star
      value: "*"
  field:
    type: string
    value: used_percent
  warn:
    type: lambda
    value: '"mean" > 80.0'
  crit:
    type: lambda
    value: '"mean" > 90.0'
  window:
    type: duration
    value: 10m
  slack_channel:
    type: string
    value: "#alerts_testing"

创建任务。

kapacitor define mem_alert -file implicit_mem_template_task.yaml

**注意：** 当 dbrp 值已在模板中声明时，任务定义文件中**不得**出现 dbrps 字段，例如在 implicit_mem_template_task.yaml 中。这样做会导致错误。

此页面是否有帮助？

感谢您的反馈！

© 2025 InfluxData, Inc.

您在哪里运行 InfluxDB？

选择您的 **InfluxDB Cloud 区域和集群** 或您的 **InfluxDB OSS URL**，我们将为您定制代码示例。识别您的 InfluxDB Cloud 集群。

  • InfluxDB Cloud
  • InfluxDB OSS 或 Enterprise
AWS

  • 美国西部（俄勒冈州）

GCP
Azure
默认
自定义

有关更多信息，请参阅 InfluxDB Cloud 区域 或 InfluxDB OSS URL。

感谢您的反馈！

让我们知道我们可以做得更好

谢谢！

不用了，谢谢

InfluxDB 3.8 新特性

InfluxDB 3.8 和 InfluxDB 3 Explorer 1.6 的主要增强功能。

查看博客文章

InfluxDB 3.8 现已适用于 Core 和 Enterprise 版本，同时发布了 InfluxDB 3 Explorer UI 的 1.6 版本。本次发布着重于操作成熟度，以及如何更轻松地部署、管理和可靠地运行 InfluxDB。

更多信息，请查看

InfluxDB Docker 的 latest 标签将指向 InfluxDB 3 Core

在 **2026 年 2 月 3 日**，InfluxDB Docker 镜像的 latest 标签将指向 InfluxDB 3 Core。为避免意外升级，请在您的 Docker 部署中使用特定的版本标签。

如果使用 Docker 来安装和运行 InfluxDB，latest 标签将指向 InfluxDB 3 Core。为避免意外升级，请在您的 Docker 部署中使用特定的版本标签。例如，如果使用 Docker 运行 InfluxDB v2，请将 latest 版本标签替换为 Docker pull 命令中的特定版本标签 — 例如

docker pull influxdb:2