Documentation

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 = [*]

有关可用数据类型的信息，请参阅 literal value types。

可选变量

在某些情况下，模板任务可以用于不需要所有模板变量值的任务。为了确保变量是可选的，提供一个默认值。在大多数情况下，默认值可以简单地是 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，这些是独特于 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 格式。

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

示例：一个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 or Enterprise
AWS

  • 美国西部（俄勒冈州）

谷歌云平台
微软 Azure
默认
自定义

有关更多信息，请参见 InfluxDB Cloud regions 或 InfluxDB OSS URLs。

感谢您的反馈!

让我们知道我们可以做得更好的地方：

谢谢！

No thanks

Flux的未来

Flux 正在进入维护模式。您可以像现在一样继续使用它，而无需对您的代码进行任何更改。

阅读更多

InfluxDB 3 开源版本现已公开Alpha测试

InfluxDB 3 Open Source is now available for alpha testing, licensed under MIT or Apache 2 licensing.

我们将发布两个产品作为测试版的一部分。

InfluxDB 3 核心，是我们新的开源产品。 它是一个用于时间序列和事件数据的实时数据引擎。 InfluxDB 3 企业版是建立在核心基础之上的商业版本，增加了历史查询能力、读取副本、高可用性、可扩展性和细粒度安全性。

有关如何开始的更多信息，请查看：