statsd exporter

statsd_exporter 接收StatsD风格的指标并将其导出为Prometheus指标。

概述

StatsD exporter是StatsD的替代品。该exporter通过配置的映射规则将StatsD指标转换为Prometheus指标。

我们建议仅将该exporter用作中间解决方案，长期应切换到原生Prometheus instrumentation。虽然运行集中式StatsD服务器很常见，但该exporter作为边车运行时效果最佳。

从现有StatsD设置过渡

中继功能允许逐步过渡。

通过将exporter作为边车添加到应用实例旁来引入它。在Kubernetes中，这意味着将其添加到Pod中。使用--statsd.relay.address将指标转发到现有StatsD UDP端点。中继会无修改地转发statsd事件，保留原始指标名称和任何格式的标签。

+-------------+    +----------+                  +------------+
| 应用程序     +--->| Exporter +----------------->|  StatsD    |
+-------------+    +----------+                  +------------+
                          ^
                          |                      +------------+
                          +----------------------+ Prometheus |
                                                 +------------+

从StatsD中继

要将现有StatsD环境中的指标传输到Prometheus，配置StatsD的repeater后端以将所有接收到的指标重复发送到statsd_exporter进程。

+----------+                         +-------------------+                        +--------------+
|  StatsD  |---(UDP/TCP repeater)--->|  statsd_exporter  |<---(scrape /metrics)---|  Prometheus  |
+----------+                         +-------------------+                        +--------------+

这允许以最小的工作量试用exporter，但不提供边车模式的每实例指标。

标签扩展

exporter支持Librato、InfluxDB、DogStatsD和SignalFX风格的标签，这些标签将转换为Prometheus标签。

对于Librato风格的标签，必须使用分隔符#将其附加到指标名称后，如下所示：

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

有关更完整的描述，请参见statsd-librato-backend README。

对于InfluxDB风格的标签，必须使用分隔符逗号将其附加到指标名称后，如下所示：

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

有关更全面的概述，请参见这篇InfluxDB博客文章。

对于DogStatsD风格的标签，它们作为|#分隔的部分附加在指标末尾，如下所示：

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

有关概念描述，请参见DogStatsD文档中的标签和数据报格式。如果遇到问题，请注意这种标签风格与原始statsd实现不兼容。exporter还支持结合DogStatsD标签使用DogStatD扩展聚合，但不支持其他标签风格。

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

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

注意：如果混合标签风格（例如Librato/InfluxDB与DogStatsD），exporter会将其视为错误，行为未定义。此外，没有值的标签（#some_tag）不受支持，将被忽略。

exporter默认解析所有标签格式，但可以通过命令行标志禁用特定标签格式：

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

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

构建和运行

注意：0.7.0版本切换到kingpin标志库。此更改后，标志行为符合POSIX风格：

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

生命周期API

statsd_exporter具有可选的生命周期API（默认禁用），可通过向/-/reload或/-/quit端点发送PUT或POST请求来重新加载或退出exporter。

中继

statsd_exporter有一种可选模式，可将传入的statsd行缓冲并中继到远程服务器。这在迁移到使用exporter时"分流"数据很有用。中继将至少每秒刷新一次缓冲区，以避免延迟指标传递。

测试

$ go test

指标映射与配置

statsd_exporter可通过简单的映射语言配置，将特定的点分隔StatsD指标转换为带标签的Prometheus指标。配置文件在收到SIGHUP信号时重新加载。

映射定义以匹配相关StatsD指标的行开始，其中*作为每个点分隔指标组件的通配符。匹配表达式后的行必须每行包含一个label="value"对，并且至少定义指标名称（标签名称name）。然后从这些标签构造Prometheus指标。标签值中的$n风格引用将替换为匹配行中的第n个通配符匹配，从1开始。多个匹配定义由一个或多个空行分隔。与StatsD指标匹配的第一个映射规则生效。

未在配置文件中匹配任何映射的指标将转换为不带标签的Prometheus指标，任何非字母数字字符（包括句点）转换为下划线。

通常，不同的指标类型转换如下：

StatsD gauge   -> Prometheus gauge

StatsD counter -> Prometheus counter

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

Glob匹配

默认（且最快）的glob映射风格使用*表示statsd指标名称中可能变化的部分。这些变化的部分可用于构造Prometheus指标名称和标签。

示例映射配置：

yaml
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.***.failure
 => signup_events_total{provider="***", outcome="failure", job="foo_product_server"}

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

配置中的每个映射必须定义指标的name。指标名称中可以包含$n风格的引用，以替换匹配行中的通配符匹配。例如：

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

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

Glob规则排序

从左到右，先列出更具体的匹配，再列出通配符：

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

这避免意外遮蔽后续规则，以及回溯导致的性能影响。

或者，可以完全禁用映射排序。启用无序映射后，在每个层级，更具体的匹配优先。这与推荐的排序效果相同。

正则表达式匹配

regex映射风格使用正则表达式匹配完整的statsd指标名称。如果glob映射不足以从statsd指标名称中提取结构化数据，可以使用此方式。

正则表达式匹配比glob映射慢得多，因为所有映射必须按顺序测试。因此，regex映射仅在所有glob映射之后执行。换句话说，无论指定顺序如何，glob映射优先于regex匹配。正则表达式匹配始终按顺序计算，第一个匹配生效。

指标名称也可以包含对regex匹配的引用。上面的映射可以写为：

yaml
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转义规则，如下映射将无法工作：

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

特殊匹配组

使用regex时，匹配组0是完整匹配，可用于为指标附加标签。示例：

yaml
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（即.+），请注意它将作为"全能"块。因此应放在映射列表的最后。

使用glob匹配无法实现相同功能，详情参见此issue。

命名、标签和帮助文本

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

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

yaml
mappings:
- match: "http.request.*"
  help: "HTTP请求总数"
  name: "http_requests_total"
  labels:
    code: "$1"

Honor labels

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

要将标签值设置为statsd事件标签中的原始值（如果存在），在映射配置中指定honor_labels: true。此时，映射中指定的标签作为默认值。

StatsD计时器和分布

默认情况下，statsd计时器和分布（统称为"observer"）表示为带有分位数的Prometheus summary。可以选择配置分位数和可接受误差，以及调整summary指标的聚合方式：

yaml
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。

默认summary时长为10分钟，默认桶数为5，默认缓冲区大小为500。另请参见golang_client文档。max_summary_age对应SummaryOptions.MaxAge，summary_age_buckets对应SummaryOptions.AgeBuckets，stream_buffer_size对应SummaryOptions.BufCap。

在配置中，还可以将observer类型设置为"histogram"。例如，为单个计时器指标设置observer类型：

yaml
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"

如果未设置，直方图桶使用默认的Prometheus客户端值：[.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指标类型为计时器、直方图或分布时使用。buckets仅在statsd指标类型为这些类型且observer_type设置为histogram时使用。

计时器将以ms类型接收。Statsd计时器数据以毫秒为单位传输，而Prometheus期望单位为秒。exporter会将所有计时器观测值转换为秒。

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

DogStatsD客户端行为

timed()装饰器

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

正则表达式匹配

使用YAML配置时，另一个功能是能够使用原始正则表达式定义匹配，而不是默认的glob风格匹配。这可以从命名不佳的statsd指标中提取结构化数据，并允许更精确地定位匹配规则。如果未指定match_type参数，默认值为glob：

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

全局默认值

还可以为observer类型、直方图选项、summary选项和匹配类型设置默认值。所有未定义这些值的映射将使用默认值。

defaults中唯一可配置的选项是glob_disable_ordering，省略时为false。将其设置为true后，glob匹配类型将不考虑映射规则文件中规则的顺序，始终将*视为比具体字符串优先级低。

在默认值中设置buckets或quantiles已弃用，建议使用histogram_options和summary_options，它们将覆盖弃