Traefik Proxy 指标观测实战：Metrics 提供者配置、Per-Router 指标开关与源码级原理剖析

Traefik Proxy 的 Metrics 能力为基础设施健康度提供全面视图，可用于监控入站流量、配置热加载状态、TLS 证书有效期等关键指标，在故障定位（incident triage）与主动运维中发挥核心作用。本文基于官方文档 docs/content/observe/metrics.md，完整讲解如何在静态配置（YAML/TOML/Helm Values）中启用 OpenTelemetry、Prometheus、Datadog、InfluxDB 2.X、StatsD 五类指标提供者，如何按 Router 粒度开关指标采集，并结合 pkg/observability 与 pkg/config 下的源码剖析指标注册表、继承链路与默认值的真实实现，帮助你把指标体系真正落地到生产监控栈。

一、Traefik 支持的指标提供者

Traefik Proxy 内置支持以下 metrics providers：

• OpenTelemetry（OTLP 协议，gRPC 或 HTTP）
• Prometheus
• Datadog
• InfluxDB 2.X
• StatsD

这一清单与源码中的静态配置结构完全一致。在 静态配置结构体 中，Metrics 字段指向 otypes.Metrics，该结构体以指针字段形式声明了 Prometheus、Datadog、StatsD、InfluxDB2、OTLP 五个可选导出器，并额外提供一个 AddInternals 布尔开关用于为内部服务（ping、dashboard 等）采集指标：

type Metrics struct {
    AddInternals bool
    Prometheus *Prometheus
    Datadog    *Datadog
    StatsD     *Statsd
    InfluxDB2  *InfluxDB2
    OTLP       *OTLP
}

由于各导出器均为独立指针字段，从源码结构看，多个提供者可以同时启用——运行时由 NewMultiRegistry 将多个 Registry 包装为组合注册表，各导出器未注册的指标会被安全忽略；未启用任何提供者时则使用 NewVoidRegistry()（noop 实现）以避免各处空值判断。

二、在静态配置中启用 Metrics

启用指标需要在 Traefik 的静态配置（static configuration）中声明 metrics 提供者；如果使用 Helm Chart，则在 values 中配置。以下示例来自官方文档，展示如何配置 OpenTelemetry 提供者向 Collector 推送指标：

Structured (YAML)

metrics:
  otlp:
    http:
      endpoint: http://myotlpcollector:4318/v1/metrics

Structured (TOML)

[metrics.otlp.http]
  endpoint = "http://myotlpcollector:4318/v1/metrics"

Helm Chart Values

# values.yaml
metrics:
  # Disable Prometheus (enabled by default)
  prometheus: null
  # Enable providing OTel metrics
  otlp:
    enabled: true
    http:
      enabled: true
      endpoint: http://myotlpcollector:4318/v1/metrics

注意 Helm values 中 prometheus: null 这一行：Traefik 官方 Helm Chart 默认开启 Prometheus，切换为 OTLP 时需要显式置空禁用，避免双出口。静态配置与 Helm values 的字段最终都映射到同一份 Metrics 类型定义。

仓库根目录下的 traefik.sample.toml 与 traefik.sample.yml 提供了完整的静态配置样例骨架，可用于对照各字段书写位置。

三、各提供者的完整参数与默认值

以下参数表直接来源于 types/metrics.go 中各 SetDefaults() 方法与字段注释，是官方文档未逐一展开的底层默认值事实依据。

3.1 Prometheus 拉取式导出

参数	说明	默认值
buckets	时延直方图的分桶边界（秒）	[0.1, 0.3, 1.2, 5]
addEntryPointsLabels	是否在指标中加入 entrypoint 标签	true
addRoutersLabels	是否在指标中加入 router 标签	false（未设默认开启）
addServicesLabels	是否在指标中加入 service 标签	true
entryPoint	暴露 /metrics 端点的入口点	traefik
manualRouting	不自动添加内部路由，由用户手动挂载	false
headerLabels	依据请求头为 requests_total 等指标附加自定义标签	空

默认值见 Prometheus.SetDefaults。当 manualRouting 关闭时，Traefik 会在 entryPoint 指定的入口（默认内部入口 traefik）上自动注册 /metrics 路由；源码 static_config.go 中对该组合做了专门校验。

暴露逻辑实现在 prometheus.go：PrometheusHandler() 基于 promhttp.HandlerFor 对外提供抓取端点，RegisterPrometheus() 注册进程与 Go 运行时收集器，并额外挂载一个自研的 promState 收集器。promState 的设计意图在源码注释中写得很清楚（prometheus.go L59-L72）：它跟踪 Traefik 的动态配置，当某个 service/entrypoint 被删除后，对应已生成的指标会在被至少抓取过一次后自动清理，防止下线服务的陈旧指标在 Traefik 重启前一直残留在 metrics 端点中。

3.2 OpenTelemetry（OTLP）推送

OTLP 支持 gRPC 与 HTTP 两种传输，配置结构见 types/otel.go：

参数	说明	默认值
grpc.endpoint	Collector gRPC 端点（host:port）	localhost:4317
grpc.insecure	禁用客户端传输安全	false
grpc.tls / http.tls	客户端 TLS 参数	-
headers	随 payload 发送的自定义头	空
http.endpoint	Collector HTTP 端点（scheme://host:port/path）	https://localhost:4318
explicitBoundaries	时延指标的显式边界（秒）	[.005, .01, .025, .05, .075, .1, .25, .5, .75, 1, 2.5, 5, 7.5, 10]
pushInterval	两次 checkpoint 采集的间隔	10s
serviceName	OTel resource 属性中的服务名	traefik
resourceAttributes	附加 resource 属性（key:value）	空

默认值见 OTLP.SetDefaults。文档示例中的 endpoint: http://myotlpcollector:4318/v1/metrics 即覆盖了 HTTP 端点默认值。一个容易踩的坑在 static_config.go 的校验逻辑中：otlp.grpc 不允许同时设置 insecure: true 与 tls 配置，二者语义冲突，启动时会被拒绝。

3.3 Datadog / StatsD / InfluxDB 2.X 推送型

提供者	参数	说明	默认值
Datadog	address	Agent 地址	DD_AGENT_HOST:DD_DOGSTATSD_PORT，缺省 localhost:8125
Datadog	pushInterval	推送间隔	10s
Datadog	prefix	指标前缀	traefik
StatsD	address	StatsD 服务端地址	localhost:8125
StatsD	pushInterval	推送间隔	10s
StatsD	prefix	指标前缀	traefik
InfluxDB2	address	InfluxDB v2 地址	http://localhost:8086
InfluxDB2	token	访问令牌，支持令牌值或令牌文件路径（FileOrContent）	必填
InfluxDB2	org / bucket	组织与桶 ID	必填
InfluxDB2	pushInterval	推送间隔	10s
InfluxDB2	additionalLabels	附加到所有指标的 influxdb tags	空

三者都支持 addEntryPointsLabels / addRoutersLabels / addServicesLabels 三个标签开关，默认 entrypoint 与 service 标签开启。值得注意的是 Datadog 的 默认地址取自环境变量 DD_AGENT_HOST 与 DD_DOGSTATSD_PORT，在 Datadog Agent sidecar 部署场景下可免配置自动发现 Agent。

四、暴露了哪些指标

从 Registry 接口定义 与 Prometheus 指标命名常量 可以完整枚举 Traefik 暴露的指标族（Prometheus 命名，均带 traefik_ 前缀）：

层级	指标	含义
server	traefik_config_reloads_total	配置热加载次数
server	traefik_config_last_reload_success	最近一次配置加载是否成功
server	traefik_open_connections	当前打开的连接数
TLS	traefik_tls_certs_not_after	证书过期时间戳（秒）
entrypoint	traefik_entrypoint_requests_total / requests_tls_total / request_duration_seconds / requests_bytes_total / responses_bytes_total	入口点请求量、TLS 请求量、时延、收发字节数
router	traefik_router_requests_total / requests_tls_total / request_duration_seconds / requests_bytes_total / responses_bytes_total	路由级同维度指标
service	traefik_service_requests_total / requests_tls_total / request_duration_seconds / retries_total / server_up / requests_bytes_total / responses_bytes_total	服务级请求、重试、上游存活状态与流量

这解释了文档开头“监控入站流量、支撑故障定位”的说法：requests_total 按入口/路由/服务三级下钻，request_duration_seconds 直方图可用于构建 P99 延迟面板，server_up 与 retries_total 组合可快速发现上游不健康，tls_certs_not_after 则支持证书到期告警。

五、Per-Router Metrics：按路由开关指标采集

官方文档提供了在单个 router 上禁用指标（例如把调试路由、健康检查路由排除在监控数据之外）的四种配置形态：

Structured (YAML)

http:
  routers:
    my-router:
      rule: "Host(`example.com`)"
      service: my-service
      observability:
        metrics: false

Structured (TOML)

[http.routers.my-router.observability]
  metrics = false

Kubernetes（IngressRoute CRD）

# ingressroute.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: my-router
spec:
  routes:
    - kind: Rule
      match: Host(`example.com`)
      services:
        - name: my-service
          port: 80
      observability:
        metrics: false

Labels / Tags（Docker、Swarm、EC2 等 label 驱动 provider）

labels:
  - "traefik.http.routers.my-router.observability.metrics=false"

JSON Tags 等价写法：

{
  "Tags": [
    "traefik.http.routers.my-router.observability.metrics=false"
  ]
}

5.1 源码中的字段与继承规则

该配置的动态配置字段是 RouterObservabilityConfig：

type RouterObservabilityConfig struct {
    AccessLogs *bool // 本路由是否启用访问日志
    Metrics  *bool   // 本路由是否启用指标
    Tracing  *bool   // 本路由是否启用追踪
    TraceVerbosity otypes.TracingVerbosity // minimal / detailed
    ...
}

Metrics 采用 *bool 三态设计：nil（未配置）表示“未表态”，true/false 表示显式启用或禁用。这个“未表态”状态正是文档所述继承语义的实现基础。

继承链路在 aggregator.go 中完成：路由器配置在聚合时，如果 router 自身未设置 Observability.Metrics，就从所属入口点（entrypoint）的 observability 配置继承；若入口点也未设置，则由 applyDefaultObservabilityModel 兜底填充默认值 Metrics: new(true)——即默认全局开启指标采集，并保证最终值被序列化、可经 API 查询。Kubernetes 侧的 CRD provider（kubernetes_http.go）与 Ingress provider（kubernetes.go）同样将 observability.metrics 字段透传进该结构，因此 IngressRoute CRD 写法与静态 YAML 写法行为一致。

5.2 请求链路上的指标门控

聚合完成后，router 构建阶段会取出每个 router 的 observability 配置，调用 observabilityMgr.BuildEPChain(...) 生成观测链（access log、metrics、tracing 等中间件）并 Then(handler) 挂到该路由的 handler 之前。真正决定“这一次请求是否计入指标”的判断发生在中间件内部：observability.go 的 MetricsEnabled(ctx) 从请求 context 中读取 Observability.MetricsEnabled 状态——该状态由 WithObservabilityHandler 在链头注入。因此：

1. 每个 router 的指标开关是逐请求生效的 context 值，而非进程级全局开关；
2. metrics: false 的 router 命中的请求不会调用任何 Registry 的 counter/histogram 方法，监控数据中自然不再出现该路由的维度值；
3. 结合第 3.1 节提到的 promState 清理机制，被禁用或下线的路由对应的陈旧 series 也会在后续抓取中被逐步回收。

六、验证与进一步阅读

• 仓库集成测试目录 integration/ 中包含大量带观测配置的 fixture，例如 simple_stats.toml 等，可作为最小可运行的指标配置参照；
• 指标采集的单元测试见 pkg/observability/metrics/，覆盖 Prometheus、StatsD、Datadog、InfluxDB2、OTel 各导出器的行为断言；
• 更完整的字段级参考可查阅 docs/content/reference/install-configuration/ 目录下的静态配置参考文档（原文档提示的 reference 页），以及动态配置参考 docs/content/reference/dynamic-configuration/ 中 router 的 observability 章节。

适用前提小结：以上配置面向当前仓库对应的 Traefik v3 代码；observability.metrics 的三态继承（router → entrypoint → 全局默认 true）与多提供者并存能力均以 pkg/server/aggregator.go 与 pkg/observability/metrics/metrics.go 的当前实现为准，升级版本后建议复核默认值（尤其是 Prometheus 默认入口点 traefik 与 OTLP 默认端点 localhost:4317/4318）。