Starlark 处理器插件

此插件为每个匹配的指标调用提供的 Starlark 函数，允许自定义编程指标处理。

Starlark 语言是 Python 的一种方言，对于有 Python 语言经验的人来说会很熟悉。但是，存在重大差异。现有的 Python 代码不太可能在未修改的情况下正常工作。执行环境是沙箱化的，无法执行 I/O 操作，例如从文件或套接字读取。

Starlark 规范 包含有关语法和可用函数的详细信息。

引入于： Telegraf v1.15.0 标签：通用 操作系统支持：所有

全局配置选项

插件支持其他全局和插件配置设置，用于修改指标、标签和字段，创建别名以及配置插件顺序等任务。更多详情请参阅 CONFIGURATION.md。

配置

# Process metrics using a Starlark script
[[processors.starlark]]
  ## The Starlark source can be set as a string in this configuration file, or
  ## by referencing a file containing the script.  Only one source or script
  ## should be set at once.

  ## Source of the Starlark script.
  source = '''
def apply(metric):
  return metric
'''

  ## File containing a Starlark script.
  # script = "/usr/local/bin/myscript.star"

  ## The constants of the Starlark script.
  # [processors.starlark.constants]
  #   max_size = 10
  #   threshold = 0.75
  #   default_name = "Julia"
  #   debug_mode = true

用法

Starlark 代码应包含一个名为 apply 的函数，该函数以度量为唯一参数。该函数将与每个度量一起调用，并且可以返回 None、单个度量或度量列表。

def apply(metric):
    return metric

有关可在代码中使用的可用类型和函数的列表，请参阅 Starlark 规范。

除了这些之外，以下 InfluxDB 特定的类型和函数也暴露给脚本。

• Metric(name)：创建具有给定测量名称的新度量。该度量将没有标签或字段，并默认为当前时间。

• name：名称是包含度量测量名称的 字符串。

• tags：一个 类似字典 的对象，包含度量的标签。

• fields：一个 类似字典 的对象，包含度量的字段。值可以是 int、float、string 或 bool 类型。

• time：度量的时间戳，以自 Unix 纪元以来的纳秒为单位的整数。

• deepcopy(metric, track=false)：复制现有度量，是否包含跟踪信息。如果 track 设置为 true，则复制跟踪信息。注意：请务必始终返回所有带有跟踪信息的度量！否则，相应的输入将永远不会收到传递信息，并可能溢出！

Python 差异

虽然 Starlark 与 Python 类似，但有一些重要的区别需要注意

• Starlark 对错误处理的支持有限，并且没有异常。如果发生错误，脚本将立即终止，Telegraf 将丢弃该度量。有关错误的详细信息，请检查 Telegraf 日志文件。

• 无法导入其他包，并且 Python 标准库不可用。

• 无法打开文件或套接字。

• Starlark 语法不支持这些常用关键字

  as             finally        nonlocal
  assert         from           raise
  class          global         try
  del            import         with
  except         is             yield

可用库

加载除您自己的脚本之外的外部脚本的能力非常有限。以下库可供加载

• json：load("json.star", "json") 提供 json.encode()、json.decode()、json.indent() 函数。请参阅 json.star 了解示例。有关函数的详细信息，请参阅 库文档。
• log：load("logging.star", "log") 提供 log.debug()、log.info()、log.warn()、log.error() 函数。请参阅 logging.star 了解示例。
• math：load("math.star", "math") 提供 在库中记录的函数。请参阅 math.star 了解示例。
• time：load("time.star", "time") 提供 time.from_timestamp()、time.is_valid_timezone()、time.now()、time.parse_duration()、time.parse_time()、time.time() 函数。请参阅 time_date.star、time_duration.star 和 time_timestamp.star 了解示例。有关函数的详细信息，请参阅 库文档。

如果您希望在此处看到对其他内容的更多支持，请提交一个问题。

常见问题

使用 Starlark 的性能成本是多少？

在本地测试中，运行一个适度的脚本来处理一个度量大约需要 1µs（1 微秒）。这会随着脚本的大小而变化，但总影响很小。以这个速度，它不太可能成为您 Telegraf 设置中的瓶颈。

如何删除/丢弃度量？

如果不返回度量，它将被删除。通常这意味着函数应该 return None。

如何复制度量？

使用 deepcopy(metric) 创建度量的副本。

如何返回多个度量？

您可以返回一个度量列表

def apply(metric):
    m2 = deepcopy(metric)
    return [metric, m2]

如果脚本中发生错误，跟踪度量会怎样？

度量将被标记为未传递。

如何创建新度量？

使用 Metric(name) 函数并设置至少一个字段。

遍历标签/字段的最快方法是什么？

最快的遍历方式是使用 for 循环遍历标签或字段属性

def apply(metric):
    for k in metric.tags:
        pass
    return metric

当您使用此形式时，无法在循环中修改标签，如果需要，您应该使用 .keys()、.values() 或 .items() 方法之一

def apply(metric):
    for k, v in metric.tags.items():
        pass
    return metric

如何在多次调用脚本时保存值？

Telegraf 会冻结全局作用域，阻止其被修改，但一个名为 state 的特殊共享全局字典除外，该字典可供 apply 函数使用。请参阅“与上一个度量进行比较”中的示例。

除了 state 变量之外，尝试修改全局作用域将导致错误。

如何管理 apply 函数中发生的错误？

如果您需要调用可能返回错误的某些代码，则可以将调用委托给内置函数 catch，该函数接受一个 Callable 作为参数，并返回发生的错误（如果有），否则返回 None。

所以例如

load("json.star", "json")

def apply(metric):
    error = catch(lambda: failing(metric))
    if error != None:
        # Some code to execute in case of an error
        metric.fields["error"] = error
    return metric

def failing(metric):
    json.decode("non-json-content")

如何重用同一个脚本但使用不同的参数？

如果您有一个通用脚本，您想为插件的不同实例重用它，您可以使用常量作为脚本的输入参数。

所以，假设您有以下配置

[[processors.starlark]]
  script = "/usr/local/bin/myscript.star"

  [processors.starlark.constants]
    somecustomnum = 10
    somecustomstr = "mycustomfield"

然后，您的脚本可以像这样使用配置中定义的常量

def apply(metric):
    if metric.fields[somecustomstr] >= somecustomnum:
        metric.fields.clear()
    return metric

无法表示整数... 是什么意思？

如果 starlark 中的整数值超过了有符号 64 位整数限制，则会发生此错误。当您将大值相加到 starlark 整数值中，或将无符号 64 位整数转换为 starlark 然后从中创建新的度量字段时，可能会发生此情况。

这是因为 starlark 中的整数值总是有符号的，并且可以增长到超过 64 位大小。因此，在上述情况下，将其转换回会失败。

作为一种变通方法，您可以将字段值裁剪到有符号 64 位限制，或者将值作为浮点数返回。

示例

• 丢弃包含字符串值的字段
• 丢弃类型意外的字段
• 获取 IOPS 进行聚合和计算最大 IOPS)
• 处理度量字段中的 JSON - 有关函数文档，请参阅 库文档
• 使用数学函数计算字段值 - 有关函数文档，请参阅 库文档
• 转换数值
• 将键的值作为另一个字段的键进行透视
• 计算两个整数字段的比率
• 使用名称映射重命名标签或字段
• 缩放字段值
• 解析日期并提取年、月、日 - 有关函数文档，请参阅 库文档
• 解析持续时间并转换为秒
• 根据秒中的时间戳过滤度量
• 根据带纳秒的时间戳过滤度量
• 将度量时间戳设置为当前/本地时间
• 根据字段值过滤度量
• 使用 Telegraf 日志记录器记录消息
• 使用列表返回多个度量
• 从 JSON 数组返回多个度量
• 使用 fail 返回自定义错误
• 使用共享状态将度量与上一个度量进行比较
• 重命名 Prometheus remote-write 测量名称

所有示例均位于 testdata 文件夹中。

提交 Pull Request 以添加任何其他有用的 Starlark 示例。