链路追踪¶

可视化请求流程

链路追踪系统让开发者能够可视化基础设施中的调用流程。

Traefik 使用 OpenTelemetry，这是一项专为分布式链路追踪设计的开放标准。

配置示例¶

启用链路追踪：

文件 (YAML)

tracing: {}

文件 (TOML)

[tracing]

CLI

--tracing=true

Helm Chart 值

  tracing:
    otlp:
        enabled: true

配置选项¶

字段	说明	默认值	必填
`tracing.addInternals`	为内部资源（例如 `ping@internal`）启用链路追踪。	false	否
`tracing.serviceName`	定义服务名称资源属性。	"traefik"	否
`tracing.resourceAttributes`	定义发送到收集器的附加资源属性。详情参见 resourceAttributes。	{}	否
`tracing.sampleRate`	要进行链路追踪的请求比例，介于 0.0 和 1.0 之间。 Traefik 支持基于父 span 的采样比例，因此根 span（即由 Traefik 发起的 span）按此比率采样，而子 span 继承父 span 的采样决定（即来自传入请求的链路追踪上下文）。详情参见 sampleRate。	1.0	否
`tracing.capturedRequestHeaders`	定义作为属性添加的请求头列表。适用于客户端和服务器类型的 span。	[]	否
`tracing.capturedResponseHeaders`	定义作为属性添加的响应头列表。适用于客户端和服务器类型的 span。	[]	否
`tracing.safeQueryParams`	默认对所有查询参数脱敏。定义不脱敏的查询参数列表。	[]	否
`tracing.otlp.http`	指示导出器通过 HTTP 将链路追踪发送到 OpenTelemetry Collector。子选项使用默认值。	null/false	否
`tracing.otlp.http.endpoint`	接收链路追踪的 OpenTelemetry Collector URL。格式为 "`<scheme>://<host>:<port><path>`"	"https://localhost:4318"	是
`tracing.otlp.http.headers`	导出器随链路追踪发送到 OpenTelemetry Collector 的附加请求头。		否
`tracing.otlp.http.tls.ca`	用于安全连接到 OpenTelemetry Collector 的证书颁发机构文件路径，默认为系统证书包。	""	否
`tracing.otlp.http.tls.cert`	用于安全连接到 OpenTelemetry Collector 的公钥证书路径。使用此选项时，必须设置 `key` 选项。	""	否
`tracing.otlp.http.tls.key`	定义 TLS 连接使用的私钥路径。	""	否
`tracing.otlp.http.tls.insecureskipverify`	若 `insecureSkipVerify` 为 `true`，到 OpenTelemetry Collector 的 TLS 连接将接受服务器提供的任何证书，无论证书涵盖哪些主机名。	false	是
`tracing.otlp.grpc`	指示导出器通过 gRPC 将链路追踪发送到 OpenTelemetry Collector。	false	否
`tracing.otlp.grpc.endpoint`	接收链路追踪的 OpenTelemetry Collector 地址。格式为 "`<host>:<port>`"	"localhost:4317"	是
`tracing.otlp.grpc.headers`	导出器随链路追踪发送到 OpenTelemetry Collector 的附加请求头。	[]	否
`tracing.otlp.grpc.insecure`	允许导出器不使用安全协议向 OpenTelemetry Collector 发送链路追踪。	false	是
`tracing.otlp.grpc.tls.ca`	用于安全连接到 OpenTelemetry Collector 的证书颁发机构文件路径，默认为系统证书包。	""	否
`tracing.otlp.grpc.tls.cert`	用于安全连接到 OpenTelemetry Collector 的公钥证书路径。使用此选项时，必须设置 `key` 选项。	""	否
`tracing.otlp.grpc.tls.key`	定义 TLS 连接使用的私钥路径。	""	否
`tracing.otlp.grpc.tls.insecureskipverify`	若 `insecureSkipVerify` 为 `true`，到 OpenTelemetry Collector 的 TLS 连接将接受服务器提供的任何证书，无论证书涵盖哪些主机名。	false	是

sampleRate¶

sampleRate 选项使用 ParentBased(TraceIDRatioBased) 策略控制链路追踪采样。

采样策略行为

根 span（起始于 Traefik 的链路追踪）：使用基于链路追踪 ID 比例的采样方式，按照配置的 sampleRate 采样。
子 span（已有链路追踪上下文的请求）：继承父 span 的采样决定，不受本地 sampleRate 影响。

这确保分布式链路追踪中的采样决定保持一致：一旦某条链路追踪被采样，该链路追踪中的所有 span 都会被采样，从而提供完整的端到端可见性。

resourceAttributes¶

resourceAttributes 选项允许设置随链路追踪发送的资源属性。 Traefik 也支持通过 OTEL_RESOURCE_ATTRIBUTES 环境变量设置资源属性。

Kubernetes 资源属性检测

此外，在 Kubernetes 集群中运行时，Traefik 会自动发现以下 Kubernetes 资源属性：

k8s.namespace.name
k8s.pod.uid
k8s.pod.name

请注意，自动检测可能失败，例如 Traefik Pod 运行在主机网络模式时。此时，应通过该选项或环境变量提供这些属性。