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://: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 上代码库中的最新示例。

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

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