Grafana Tempo Generic Forwarding将摄入的 Trace 异步复制到外部端点【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempoGeneric forwarding 是 Grafana Tempo 提供的一项 trace 异步复制能力在启用后distributor 会把收到的 span 同时写入内部存储链路Kafka / live store和外部定义的端点用于数据复制、审计、二次分析等场景。本文基于 Tempo 仓库的源码与配置文档完整讲解该功能的配置方法、全部参数含义、per-tenant 控制方式与底层实现原理读完即可在自己的集群中落地一套可复制的 trace 转发方案。Generic Forwarding 是什么Generic forwarding 允许对摄入ingested的 trace 进行异步复制。当该特性启用后distributor 会把接收到的 spans 同时写入 Kafka或本地消费链路以及配置中定义的端点。从源码看这一逻辑位于 modules/distributor/distributor.go 的pushToWriter流程中if err : d.forwardersManager.ForTenant(userID).ForwardTraces(ctx, traces); err ! nil { _ level.Warn(d.logger).Log(msg, failed to forward batches for tenant%s: %w, userID, err) }转发调用发生在向 Kafka 或 live store 推送之前并且转发失败只记录一条 warning 日志不会影响正常的数据写入这正是该功能 best-effort尽力而为设计的具体体现。关键特性异步复制转发动作通过 per-tenant 队列异步执行不阻塞主摄入链路。best-effort 语义如果复制过程中出现错误不会发生重试。部分 trace 可能被跳过或转发失败这是设计预期而非故障。与 Kafka 互补无论是否启用 Kafka 作为内部写入目标转发都是独立于内部存储的额外复制通道。使用边界与限制原文档明确强调了一个重要警告Generic forwarding 不追溯doesnt work retroactively。启用之后distributor 只复制新摄入的 span之前已经进入系统的数据不会被补发。这意味着该功能适合作为长期、持续的复制通道而不是数据迁移或历史数据补齐工具。在开启之前需要评估这一时间边界是否符合业务需求。配置 Generic Forwarding启用 generic forwarding 需要同时修改两处配置distributor和overrides分为两步在distributor段定义 forwarder 列表每个 forwarder 必须指定一个全局唯一的name、受支持的backend以及该 backend 特有的配置。在overrides段引用这些 forwarder通过 overrides 实现细粒度控制可以全局启用也可以按租户per-tenant启用。关于所有配置项的完整说明可以参见仓库内的 distributor 与 overrides 配置文档。配置项深度解析distributor.forwarders 完整参数以下是当前仓库支持的全部 forwarder 配置项来源于 docs/sources/tempo/configuration/_index.md 与 modules/distributor/forwarder/config.godistributor: forwarders: # Forwarder 名称。在 forwarders 列表中必须唯一。 # 该名称会在 overrides 配置中被引用用于为租户启用 forwarder。 - name: string # forwarder 使用的 backend当前仅支持 otlpgrpc。 backend: string # otlpgrpc 配置仅在 backend 为 otlpgrpc 时生效。 otlpgrpc: # otlpgrpc 兼容的端点列表。 endpoints: list of string tls: # 可选。设为 true 时禁用 TLS。 [insecure: boolean | default false] # 可选。TLS 证书路径。当 insecure false 时必须设置。 [cert_file: string | default ] # 可选。配置 forwarder 的过滤能力 # 使用 OpenTelemetry Transformation Language (OTTL) 语法 # 丢弃不需要的 span 与 span 事件。 filter: traces: span: list of string spanevent: list of string各字段含义与校验规则如下字段类型必填说明namestring是Forwarder 唯一名称overrides 中通过它引用为空时配置校验直接失败backendstring是当前唯一受支持的值是otlpgrpc其余值会报backend backend is not supportedotlpgrpc.endpointslist of string是目标 gRPC 端点列表格式为host:portotlpgrpc.tls.insecurebool否默认false为true时使用非安全明文连接otlpgrpc.tls.cert_filestring条件必填insecurefalse时必填指向服务端证书文件filter.traces.spanlist of string否OTTL 格式的 span 过滤条件命中条件外的 span 会被丢弃filter.traces.spaneventlist of string否OTTL 格式的 span event 过滤条件后端配置的校验逻辑可以在 modules/distributor/forwarder/otlpgrpc/config.go 中看到若insecure为false而cert_file为空校验会直接报错cert_file is empty而 forwarder 整体校验config.go会依次检查name非空、backend受支持再进入 backend 特有的校验。overrides 中的 forwarders 引用在 overrides 段中通过forwarders列表按名称引用在 distributor 中定义的 forwarder见 modules/overrides/config.gooverrides: defaults: forwarders: [forwarder-name-1, forwarder-name-2]放在defaults下即对所有租户全局生效如果希望按租户隔离则可以把forwarders放到对应租户的 overrides 条目下实现 per-tenant 的细粒度控制。除了静态配置文件Tempo 还支持通过 HTTP API 动态更新 per-tenant 的用户可配置 overrides其中同样包含forwarders字段详见 user-configurable-overrides 文档例如使用curl -X PATCH -H X-Scope-OrgID: 3 .../api/overrides动态调整某个租户的转发列表。一个完整可运行的配置示例下面是一份可直接落地的示例配置定义一个名为replica的 otlpgrpc forwarder把 trace 复制到两个外部端点并通过 OTTL 过滤只转发带http.route属性的 spandistributor: forwarders: - name: replica backend: otlpgrpc otlpgrpc: endpoints: - otlp-collector-a.example.com:4317 - otlp-collector-b.example.com:4317 tls: insecure: true # 测试环境可关闭 TLS生产环境建议改为 cert_file 方式 filter: traces: span: - attributes[http.route] ! nil spanevent: [] overrides: defaults: forwarders: [replica]示例中两个端点的含义需要结合实际网络环境替换。如果目标端点要求 TLS则将insecure设为false并提供cert_file路径。过滤条件支持任意合法的 OTTL 表达式具体语法可参考 OpenTelemetry 官方 Transformation Language 文档。源码视角一次转发请求的生命周期1. 队列缓冲与 worker 消费distributor 中的 forwarder.Manager 负责 forwarder 的整个生命周期。它为每个启用转发的租户维护一个队列列表queueList每个 forwarder 对应一个队列队列默认大小为100worker 数为2见 manager.go 中的defaultWorkerCount与defaultQueueSize。trace 先入队再由 worker 异步取出并调用底层 forwarder这正是异步复制的实现基础。2. 租户隔离与动态更新Manager 的ForTenant(tenantID)方法会按租户返回对应的 forwarder 列表如果租户的 overrides 中没有配置任何 forwarder则返回空列表直接跳过转发。Manager 的后台循环每10 秒检查一次各租户的 overrides 配置一旦发现转发列表发生变化新增/删除 forwarder会优雅关闭旧队列并重建新队列从而实现转发规则的动态生效无需重启进程。3. otlpgrpc 后端如何发送数据当后端为otlpgrpc时modules/distributor/forwarder/otlpgrpc/forwarder.go 会为endpoints中的每个地址创建一个 gRPC 连接并基于 OpenTelemetry Collector 的ptraceotlp.GRPCClient构造 OTLP/HTTPgRPC 导出客户端。ForwardTraces会把ptrace.Traces封装为ExportRequest并发地向所有端点执行Export任一端点失败都会收集到错误中返回。连接建立时还会挂载 gRPC 拦截器用户头传递以及 OpenTelemetry 的otelgrpc统计处理器保证转发请求自身也可被观测、可被追踪。4. OTTL 过滤的实现如果配置了filter.traces.span或filter.traces.spaneventManager 在创建 forwarder 时会用 NewFilterForwarder 将其包装为一层过滤器内部直接复用 OpenTelemetry Collector 的filterprocessor把 OTTL 条件注入SpanConditions/SpanEventConditions并将错误模式设为IgnoreError表达式求值出错时忽略该条数据而非中断。转发时先复制一份 trace再通过 filter processor 过滤最后把通过的数据交给下游 forwarder从而保证原始数据不被修改MutatesData: false。运维与排错建议确认生效范围因为功能不追溯启用后请用小流量或单租户先行验证观察外部端点是否开始收到新数据。观察日志转发失败时distributor 会输出包含failed to forward batches、forwarderName、tenantID与具体错误的 warning 日志可据此定位是端点不可达、TLS 证书问题还是 OTTL 表达式错误。理解 best-effort 边界队列满、worker 忙、端点抖动都可能导致部分 trace 丢失且不重试。若业务要求严格不丢需要在该功能之外另行设计确认机制。变更转发规则修改 overrides 中的 forwarders 列表后Manager 会在约 10 秒内自动重建对应租户的队列无需重启 Tempo动态 per-tenant 变更可通过用户可配置 overrides 的 HTTP API 完成。生产安全生产环境建议关闭tls.insecure改为配置cert_file与服务端证书校验避免明文传输敏感的 trace 数据。【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考