statsd_exporter：实践指南

如果把statsd_exporter放进候选清单，不能只看热度；它的定位是StatsD 到 Prometheus 指标导出器。这类日常自动化工具真正难在输入边界、依赖和失败处理如果不清楚就很难稳定复用，仓库说明只能作为第一层证据。我的评估方法是用一项范围明确的真实任务完成最小试跑，然后检查配置时间、输出质量、异常信息和维护痕迹是否与文档一致。我会把它列入愿意先做小范围验证并复查原始文档的团队的候选清单，而不是仅凭项目介绍直接纳入生产。

StatsD 出口商

statsd_exporter 接收 StatsD-style 指标并将其导出为 Prometheus 指标。

概述

StatsD 导出器是 StatsD 的直接替代品。 该导出器通过配置的映射规则将 StatsD 指标转换为 Prometheus 指标。

我们建议仅使用导出器作为中间解决方案，并从长远来看切换到 原生 Prometheus 工具。 虽然运行集中式 StatsD 服务器很常见，但导出器作为 sidecar 效果最佳。

从现有 StatsD 设置过渡

中继功能允许逐步过渡。

通过将导出器添加为应用程序实例旁边的边车来引入导出器。 在 Kubernetes 中，这意味着将其添加到 pod。 使用 --statsd.relay.address 将指标转发到现有的 StatsD UDP 端点。 中继转发未经修改的 statsd 事件，以任何格式保留原始指标名称和标签。

+-------------+    +----------+                  +------------+
| 应用+--->| 出口商+----------------->|  StatsD    |
+-------------+    +----------+                  +------------+
                          ^
                          |                      +------------+
                          +----------------------+ 普罗米修斯 |
                                                 +------------+

来自 StatsD 的中继

要将指标从现有的 StatsD 环境通过管道传输到 Prometheus，请配置 StatsD 的中继器后端以将所有收到的指标重复到 statsd_exporter 进程。

+----------+                         +-------------------+                        +--------------+
|  StatsD  |---(UDP/TCP中继器)--->|  统计导出器  |<---（抓取/指标）---|  普罗米修斯  |
+----------+                         +-------------------+                        +--------------+

这允许以最小的努力尝试导出器，但不提供 sidecar 模式的每个实例指标。

标记扩展

导出器支持 Librato、InfluxDB、DogStatsD 和 SignalFX-style 标签， 它将被转换为 Prometheus 标签。

对于 Librato 风格的标签，必须将它们附加到指标名称后 界定 #，如下所示：

metric.name#tagName=val,tag2Name=val2:0|c

查看 statsd-librato-backend README 以获得更完整的描述。

对于 InfluxDB-style 标签，必须将它们附加到指标名称后 分隔逗号，如下所示：

metric.name,tagName=val,tag2Name=val2:0|c

请参阅 这篇 InfluxDB 博客文章 以获得更大的概览。

对于 DogStatsD-style 标签，它们被附加为 |# delimited section at the 指标的末尾，如下所示：

metric.name:0|c|#tagName:val,tag2Name:val2

查看 标签 在 DogStatsD 文档中的概念描述和 数据报格式。 如果您遇到问题，请注意此标记样式与 原始 statsd 实现。 导出器还支持 DogStatD 扩展聚合 与 DogStatsD 标记结合使用，但不支持其他标记样式。

对于 SignalFX 维度，将标签添加到方括号中的指标名称，如下所示：

metric.name[tagName=val,tag2Name=val2]:0|c

请注意：如果混合标记样式（e.g.、Librato/InfluxDB 与 DogStatsD），导出器将认为这是一个错误，并且行为未定义。 此外，不支持没有值的标签 (#some_tag)，并将被忽略。

导出器默认解析所有标记格式，但可以使用命令行标志禁用单个标记格式：

--no-statsd.parse-dogstatsd-tags
--no-statsd.parse-influxdb-tags
--no-statsd.parse-librato-tags
--no-statsd.parse-signalfx-tags

默认情况下，配置中显式指定的标签优先于标签中的标签。 要从 statsd 事件标签设置标签，请使用 honor_labels。

构建和运行

NOTE：版本0.7.0切换到主销标志库。通过此更改，标志行为为 POSIX-ish：

• 长标志以两个破折号开头 (--version)
• 通过添加 no 前缀来禁用布尔长标志（--flag-name 为 true，--no-flag-name 为 false）
• 可以组合多个短标志（但目前只有一个）
• 标志处理在第一个 -- 处停止
• 有关标志的完整列表，请参阅 --help

生命周期 API

statsd_exporter 有一个可选的生命周期 API （默认情况下禁用），可用于重新加载或退出导出器 通过向 /-/reload 或 /-/quit 端点发送 PUT 或 POST 请求。

继电器

statsd_exporter 有一个可选模式，可以缓冲传入的 statsd 行并将其中继到远程服务器。当迁移到使用导出器时，这对于“tee”数据很有用。中继每秒至少刷新一次缓冲区，以避免延迟指标的传送。

测试

$ go test

指标映射和配置

statsd_exporter 可配置为转换特定的点分隔 StatsD 通过简单的映射语言将指标转换为标记的 Prometheus 指标。配置 文件在 SIGHUP 上重新加载。

映射定义以与相关 StatsD 指标匹配的行开头， *s 充当每个点分隔的公制组件的通配符。的 匹配表达式后面的行必须包含一对 label="value" 每个，并至少定义度量名称（标签名称 name）。普罗米修斯 然后根据这些标签构建度量。 $n- 中的样式参考 标签值被匹配行中的第 n 个通配符匹配替换， 从 1 开始。多个匹配定义由一个或多个空分隔 线。第一个与 StatsD 指标匹配的映射规则获胜。

与配置文件中的任何映射都不匹配的指标将被转换 进入没有任何标签和任何非字母数字的 Prometheus 指标 字符（包括句点）翻译为下划线。

一般来说，不同的指标类型转换如下：

StatsD gauge   -> Prometheus gauge

StatsD counter -> Prometheus counter

StatsD timer, histogram, distribution   -> Prometheus summary or histogram

全局匹配

默认（也是最快）glob 映射样式使用 * 来表示 statsd 指标名称中可能变化的部分。 然后可以在 Prometheus 指标名称和标签的构造中引用这些不同的部分。

映射配置示例：

mappings:
- match: "test.dispatcher.*.*.*"
  name: "dispatcher_events_total"
  labels:
    processor: "$1"
    action: "$2"
    outcome: "$3"
    job: "test_dispatcher"
- match: "*.signup.*.*"
  name: "signup_events_total"
  labels:
    provider: "$2"
    outcome: "$3"
    job: "${1}_server"

这会将这些示例 StatsD 指标转换为 Prometheus 指标，如下所示 如下：

test.dispatcher.FooProcessor.send.success
 => dispatcher_events_total{processor="FooProcessor", action="send", outcome="success", job="test_dispatcher"}

foo_product.signup.facebook.failure
 => signup_events_total{provider="facebook", outcome="failure", job="foo_product_server"}

test.web-server.foo.bar
 => test_web_server_foo_bar{}

配置文件中的每个映射必须为指标定义 name。的 指标的名称可以包含 $n- 样式引用，以替换为第 n 个 匹配行中的通配符匹配，以及 $0 来引用原始内容， 未修改的 statsd 指标名称（请参阅 特殊匹配组）。 这允许动态重写，例如：

mappings:
- match: "test.*.*.counter"
  name: "${2}_total"
  labels:
    provider: "$1"

全局匹配为常见映射提供最佳性能。

排序全局规则

在通配符之前列出更具体的匹配项，从左到右：

a.b.c
a.b.*
a.*.d
a.*.*

这可以避免对后续规则的意外影响以及回溯对性能的影响。

或者，您可以完全禁用映射排序。 通过无序映射，在每个层次结构级别，最具体的匹配获胜。 这与使用推荐的排序具有相同的效果。

正则表达式匹配

regex 映射样式使用正则表达式来匹配完整的 statsd 指标名称。 如果 glob 映射不够灵活，无法从可用的 statsd 指标名称中提取结构化数据，请使用它。

正则表达式匹配比全局映射慢得多，因为必须按顺序测试所有映射。 因此，正则表达式映射仅在所有 glob 映射之后执行。 换句话说，全局映射优先于正则表达式匹配，无论它们的指定顺序如何。 正则表达式匹配始终按顺序求值，第一个匹配获胜。

指标名称还可以包含对正则表达式匹配的引用。上面的映射 可以写成：

mappings:
- match: "test\.(\w+)\.(\w+)\.counter"
  match_type: regex
  name: "${2}_total"
  labels:
    provider: "$1"
- match: "(.*)\.(.*)--(.*)\.status.(.*)\.count"
  match_type: regex
  name: "request_total"
  labels:
    hostname: "$1"
    exec: "$2"
    protocol: "$3"
    code: "$4"

请注意 yaml 转义规则，因为像下面这样的映射将不起作用。

mappings:
- match: "test\.(w+)\.(w+)\.counter"
  match_type: regex
  name: "${2}_total"
  labels:
    provider: "$1"

特殊比赛组别

通过 glob，$0 扩展为完整的 StatsD 指标名称。通过 regex，$0 扩展到完整的正则表达式匹配。两者都可用于将标签附加到度量上。 例子：

mappings:
- match: ".+"
  match_type: regex
  name: "$0"
  labels:
    statsd_metric_name: "$0"

如果收到指标 my.statsd_counter，指标名称仍将映射到 my_statsd_counter（Prometheus 兼容名称）。 但该指标还将具有标签 statsd_metric_name 和值 my.statsd_counter （未更改的值）。

注意：如果您像示例一样使用 match（i.e..+），请注意它将是一个“包罗万象”的块。所以它应该位于映射列表的最后。

注意：与其他 $n 引用（对于 glob 和 regex 模板）一样，当紧跟其他单词字符 e.g 时，请使用 ${0} 形式（而不是 $0）。 ${0}_total，否则将无法识别引用并将解析为空字符串。对于 glob 模板，当 $0 后紧跟着另一个 $- 引用 e.g 时，这也适用。 ${0}$1;在这种情况下，regex 模板不需要支撑，因此 $0$1 按原样工作。

命名、标签和帮助

请注意，具有相同名称的指标也必须具有相同的一组 标签名称。

如果默认指标帮助文本不足以满足您的需求，您可以使用 YAML 配置为每个映射指定自定义帮助文本：

mappings:
- match: "http.request.*"
  help: "Total number of http requests"
  name: "http_requests_total"
  labels:
    code: "$1"

荣誉标签

默认情况下，映射配置中指定的标签优先于 statsd 事件中的标签。

要将标签值设置为原始标签值（如果存在），请在映射配置中指定 honor_labels: true。 在这种情况下，映射中指定的标签将充当默认标签。

StatsD 定时器和发行版

默认情况下，statsd 计时器和发行版（统称为“观察者”）是 表示为带有分位数的 Prometheus 摘要。您可以选择 配置分位数和可接受的 error，以及 调整汇总指标的聚合方式：

mappings:
- match: "test.timing.*.*.*"
  observer_type: summary
  name: "my_timer"
  labels:
    provider: "$2"
    outcome: "$3"
    job: "${1}_server"
  summary_options:
    quantiles:
      - quantile: 0.99
        error: 0.001
      - quantile: 0.95
        error: 0.01
      - quantile: 0.9
        error: 0.05
      - quantile: 0.5
        error: 0.005
    max_age: 30s
    age_buckets: 3
    buf_cap: 1000

默认分位数为 0.99、0.9 和 0.5。

默认汇总年龄为10分钟，默认桶数 为 5，默认缓冲区大小为 500。 另请参阅 golang_client 文档。 max_summary_age对应于SummaryOptions.MaxAge，summary_age_buckets对应于SummaryOptions.AgeBuckets，stream_buffer_size对应于SummaryOptions.BufCap。

在配置中，还可以将观察者类型设置为“直方图”。例如， 设置单个计时器指标的观察者类型：

mappings:
- match: "test.timing.*.*.*"
  observer_type: histogram
  histogram_options:
    buckets: [ 0.01, 0.025, 0.05, 0.1 ]
    native_histogram_bucket_factor: 1.1
    native_histogram_max_buckets: 256
  name: "my_timer"
  labels:
    provider: "$2"
    outcome: "$3"
    job: "${1}_server"

如果没有设置，则默认 普罗米修斯客户端 values 用于直方图桶： [.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10]. +Inf 会自动添加。 如果您的 Prometheus 服务器启用了抓取本机直方图 (v2.40.0+)， 然后您可以设置native_histogram_bucket_factor来配置精度 稀疏直方图中的桶。有关此内容的更多信息，请参阅原始 client_golang 文档。 另外，可以通过 native_histogram_max_buckets 设置最大桶数的配置，这 避免直方图在内存中变得太大。有关此内容的更多信息，请参阅原始 client_golang 文档。

observer_type 仅在 statsd 指标类型为计时器、直方图或分布时使用。 仅当 statsd 指标类型为其中之一且 observer_type 设置为 histogram 时，才使用 buckets。

ms statsd 类型的计时器将被接受。 Statsd定时器数据以毫秒为单位传输，而Prometheus期望的单位是秒。 导出器将所有计时器观察值转换为秒。

直方图和分布事件（h 和 d 度量类型）不受单位转换的影响。

DogStatsD 客户端行为

timed() 装饰器

DogStatsD 客户端的 定时 装饰器以秒为单位发出指标，但使用 ms 类型。 设置 use_ms=True 以发送正确的单位。

正则表达式匹配

使用 YAML 配置时的另一个功能是定义匹配的能力 使用原始正则表达式而不是默认的通配符匹配样式。 这可能允许从其他名称不佳的 statsd 中提取结构化数据 指标 AND 允许更精确地定位匹配规则。当没有match_type时 指定参数时，将假定默认值 glob：

mappings:
- match: "(.*)\.(.*)--(.*)\.status\.(.*)\.count"
  match_type: regex
  name: "request_total"
  labels:
    hostname: "$1"
    exec: "$2"
    protocol: "$3"
    code: "$4"

全局默认值

人们还可以设置观察者类型、直方图选项、摘要选项和匹配类型的默认值。 这些将被所有未定义它们的映射使用。

只能在defaults中配置的选项是glob_disable_ordering，如果省略则为false。 通过将其设置为 true，glob 匹配类型将不考虑映射规则文件中规则的出现，并且始终将 * 视为低于具体字符串的优先级。

如果映射配置中存在 summary_options，则它只会覆盖映射中设置的字段。映射中未设置的字段将采用默认值。

有关带注释的示例配置，请参阅 config.exmple.yml。

drop 行动

您还可以通过对匹配指定“删除”操作来删除指标。对于 示例：

mappings:
# This metric would match as normal.
- match: "test.timing.*.*.*"
  name: "my_timer"
  labels:
    provider: "$2"
    outcome: "$3"
    job: "${1}_server"
# Any metric not matched will be dropped because "." matches all metrics.
- match: "."
  match_type: regex
  action: drop
  name: "dropped"

您可以使用普通匹配语法删除任何指标。 默认操作是“map”，它执行正常的指标映射。

显式度量类型映射

StatsD 允许在同一指标名称下发出不同的指标类型， 但 Prometheus 客户端库无法合并这些。对于这个用例 映射定义允许您指定要匹配的指标类型：

mappings:
- match: "test.foo.*"
  name: "test_foo"
  match_metric_type: counter
  labels:
    provider: "$1"

match_metric_type 的可能值为 gauge、counter 和 observer。

映射缓存大小和缓存替换策略

有一个缓存用于提高度量映射的性能，可以极大地提高性能。 缓存默认最多可以存储 1000 个唯一的 statsd 指标名称 -> prometheus 指标映射。 可以使用 statsd.cache-size 标志来调整该最大值。

如果达到最大值，则默认情况下使用 最近最少使用的替换策略 轮换条目。当内存有限时，此策略是最佳策略，因为仅保留最近的条目。

或者，您可以选择 随机替换缓存策略（）。如果缓存小于可缓存集，但需要较少的锁定，则这不是最佳选择。使用它可以获得非常高的吞吐量，但请确保允许缓存保存所有指标。

最佳缓存大小由_传入_指标的基数确定。

时间序列到期

ttl 参数可用于定义过时指标的过期时间。 该值是一个持续时间，有效时间单位为：“ns”、“us”（或“μs”）、 “ms”、“s”、“m”、“h”。例如，ttl: 1m20s。 0值用于指示 不会过期的指标。

针对每个映射指标 name/labels 组合存储 TTL 配置 每当收到新样品时。这意味着您不能立即 仅通过更改映射配置来使指标过期。至少一个 必须收到样本才能使更新的映射生效。

单位换算

scale 参数可用于定义公制值的单位转换。该值是一个浮点数，用于缩放指标值。这对于将非基本单位（e.g.毫秒，千字节）转换为基本单位（e.g.秒，字节）非常有用，如 prometheus 最佳实践 中建议的那样。

mappings:
- match: foo.latency_ms
  name: foo_latency_seconds
  scale: 0.001
- match: bar.processed_kb
  name: bar_processed_bytes
  scale: 1024
- match: baz.latency_us
  name: baz_latency_seconds
  scale: 1e-6

事件刷新配置

statsd_exporter 内部为每个网络器运行一个 goroutine（UDP、TCP 和 Unix Socket）。 它们各自接收并解析接收到事件中的指标。 出于性能目的，这些事件在内部排队并定期批量刷新到主导出器 Goroutine。 该队列的大小和刷新标准可以使用 --statsd.event-queue-size、--statsd.event-flush-threshold 和 --statsd.event-flush-interval 进行调整。 然而，即使对于非常高的流量环境，默认值也应该表现良好。

使用 Docker

您可以使用 prom/statsd-exporter Docker 映像部署此导出器。

例如：

docker pull prom/statsd-exporter

docker run -d -p 9102:9102 -p 9125:9125 -p 9125:9125/udp 
        -v $PWD/statsd_mapping.yml:/tmp/statsd_mapping.yml 
        prom/statsd-exporter --statsd.mapping-config=/tmp/statsd_mapping.yml

库包

该导出器的部分实现可作为单独的包提供。 有关详细信息，请参阅 文档。

目前，库接口“没有稳定性保证”。 我们将尝试在 变更日志 中指出任何重大更改。 导出器的语义版本控制基于对导出器用户的影响，而不是对库用户的影响。

我们鼓励重复使用这些包，并欢迎 问题 与它们作为库的可用性相关。