TICKscript 语言简介

• 概述
• 节点
• 管道
• 基本示例
• 下一步

概述

Kapacitor 使用一种名为 TICKscript 的领域特定语言 (DSL) 来定义任务，这些任务涉及数据的提取、转换和加载，并且还涉及跟踪任意更改和检测数据中的事件。一个常见的任务是定义警报。TICKscript 在 .tick 文件中使用，用于定义处理数据的管道。TICKscript 语言旨在将节点中定义的数据处理操作的调用链接在一起。Kapacitor 入门 指南介绍了该产品背景下的 TICKscript 基础知识。为了更好地理解后续内容，建议读者首先回顾该文档。

每个脚本都有一个扁平的作用域，并且作用域中的每个变量都可以引用字面值（例如字符串、整数或浮点值）或节点实例，然后可以调用该实例的方法。

这些方法有两种形式。

• 属性方法 – 属性方法修改节点的内部属性并返回对同一节点的引用。属性方法使用点（“.”）表示法调用。
• 链式方法 – 链式方法创建一个新的子节点并返回对其的引用。链式方法使用管道（“|”）表示法调用。

节点

在 TICKscript 中，基本类型是节点。节点具有属性和链式方法（如前所述）。可以使用父节点或同级节点的链式方法从父节点或同级节点创建新节点。对于每种节点类型，此方法的签名都将相同，而与父节点或同级节点类型无关。链式方法可以接受零个或多个参数，这些参数用于初始化新节点实例的内部属性。常见的节点类型有 batch、query、stream、from、eval 和 alert，尽管还有几十种其他类型。

顶层节点（用于建立要定义的任务的处理类型）stream 和 batch 只是简单地声明，不带任何参数。具有更复杂属性集的节点依赖于属性方法进行内部配置。

每种节点类型想要以批处理或流模式处理数据。有些可以同时处理两者。每种节点类型还提供批处理或流模式的数据。有些可以同时提供两者。这种想要/提供模式是理解节点如何协同工作的关键。考虑到想要/提供模式，可以定义四种通用的节点用例

• 想要批处理并提供流 - 例如，当计算平均值或最小值或最大值时。
• 想要批处理并提供批处理 - 例如，当识别一批数据中的异常值时。
• 想要流并提供批处理 - 例如，当将相似数据点分组在一起时。
• 想要流并提供流 - 例如，当将数学函数（如对数）应用于点中的值时。

节点参考文档列出了每个节点的属性和链式方法，以及示例和描述。

管道

每个 TICKscript 都被分解为一个或多个管道。管道是沿着不能循环回到链中较早节点的边的逻辑组织的节点链。管道中的节点可以分配给变量。这允许使用例如 join 或 union 节点组合不同管道的结果。它还允许将管道的各个部分分解为合理可理解的自描述功能单元。在简单的 TICKscript 中，可能不需要将管道节点分配给变量。管道中的初始节点设置它们定义的 Kapacitor 任务的处理类型。这些可以是 stream 或 batch。这两种类型的管道不能组合。

流处理还是批处理？

使用 stream 处理，数据点像经典数据流一样，在到达时逐点读取。使用 stream，Kapacitor 订阅 InfluxDB 中所有感兴趣的写入。使用 batch 处理，从数据库中读取“历史”数据帧，然后进行处理。使用 stream 处理，可以在写入 InfluxDB 之前转换数据。使用 batch 处理，数据应已存储在 InfluxDB 中。处理后，也可以将其写回。

使用哪种取决于系统资源和正在进行的计算类型。当处理长时间范围的大量数据时，首选 batch。它将数据存储在磁盘上，直到需要时才使用，但查询在触发时会导致数据库突然高负载。使用 stream 处理长时间范围的大量数据意味着不必要地在内存中保存可能数十亿个数据点。当处理较小的时间范围时，首选 stream。它降低了 InfluxDB 的查询负载。

管道作为图

Kapacitor 中的管道是有向无环图 (DAG)。这意味着每条边都有一个数据流动的方向，并且管道中不能有任何循环。边也可以被认为是父节点与其子节点之间存在的数据流关系。

在任何管道的开头，都将声明两个基本边之一。第一条边建立任务的处理类型，但是，随后的每个节点都建立自身及其子节点之间的边类型。

• stream→from()– 一次传输单个数据点的边。
• batch→query()– 以块而不是一次一个点传输数据的边。

管道有效性

当连接节点然后创建新的 Kapacitor 任务时，Kapacitor 将检查 TICKscript 语法是否格式良好，以及新边是否适用于最近的节点。但是，管道的完整功能将在运行时才进行验证，届时错误消息可能会出现在 Kapacitor 日志中。

示例 1 – 运行时错误

...
[cpu_alert:alert4] 2017/10/24 14:42:59 E! error evaluating expression for level CRITICAL: left reference value "usage_idle" is missing value
[cpu_alert:alert4] 2017/10/24 14:42:59 E! error evaluating expression for level CRITICAL: left reference value "usage_idle" is missing value
...

示例 1 显示了一个运行时错误，该错误是由于管道中缺少字段值而引发的。这通常在 eval 节点之后发生，当 eval 节点的属性 keep() 未设置时。一般来说，Kapacitor 无法预测任务在运行时将遇到的所有数据模式。某些任务可能未编写为处理所有偏离或异常情况，例如字段或标签丢失时。在这些情况下，Kapacitor 将记录错误。

基本示例

示例 2 – 基本的 stream → from() 管道

dbrp "telegraf"."autogen"

stream
    |from()
        .measurement('cpu')
    |httpOut('dump')

示例 2 中的简单脚本可用于创建具有默认 Telegraf 数据库的任务。

$ kapacitor define sf_task -tick sf.tick

任务 sf_task 将仅将最新的 cpu 数据点作为 JSON 缓存到 HTTP REST 端点（例如 http://localhost:9092/kapacitor/v1/tasks/sf_task/dump）。

此示例包含数据库和保留策略语句：dbrp。

此示例还包含三个节点

• 基本 stream 节点。
• 必需的 from() 节点，用于定义数据点流。
• 处理节点 httpOut()，用于将接收到的数据缓存到 Kapacitor 的 REST 服务。

它包含两条边。

• stream→from()– 设置任务的处理类型和数据流。
• from()→httpOut()– 将数据流传递到 HTTP 输出处理节点。

它包含一个属性方法，即对 from() 节点的 .measurement('cpu') 调用，用于定义要用于进一步处理的指标。

示例 3 – 基本的 batch → query() 管道

batch
    |query('SELECT * FROM "telegraf"."autogen".cpu WHERE time > now() - 10s')
        .period(10s)
        .every(10s)
    |httpOut('dump')

示例 3 中的脚本可用于定义具有默认 Telegraf 数据库的任务。

$ kapacitor define bq_task -tick bq.tick -dbrp "telegraf"."autogen"

当用于使用默认 Telegraf 数据库创建 bq_task 时，示例 3 中的 TICKscript 将仅将代表最近 10 秒活动的批处理指标的最后一个 cpu 数据点缓存到 HTTP REST 端点（例如 http://localhost:9092/kapacitor/v1/tasks/bq_task/dump）。

此示例包含三个节点

• 基本 batch 节点。
• 必需的 query() 节点，用于定义数据集。
• 处理节点 httpOut()，用于定义处理数据集的一个步骤。在本例中，它是将其发布到 Kapacitor 的 REST 服务。

它包含两条边。

• batch→query()– 设置处理样式和数据集。
• query()→httpOut()– 将数据集传递到 HTTP 输出处理节点。

它包含两个从 query() 节点调用的属性方法。

• period()– 设置数据批处理将覆盖的时间段。
• every()– 设置将处理数据批处理的频率。

下一步？

有关使用 TICKscript 的基本示例，请参阅 GitHub 上代码库中的最新示例：GitHub。

有关中级到高级用例的 TICKscript 解决方案，请参阅指南文档。

下一节更详细地介绍 TICKscript 语法。继续…