Grafana Tempo 中的 OTLP HTTP Exporterotlp_http配置实战与源码解析【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo本篇技术指南聚焦于 OpenTelemetry Collector 的otlp_httpExporter 组件它通过 HTTP 协议、采用 OTLP 格式把 traces、metrics、logs 与 profiles 四类遥测数据发送到 Grafana Tempo 等后端。本文会完整讲解它的全部配置项、默认值与可选参数结合仓库内vendor/go.opentelemetry.io/collector/exporter/otlphttpexporter/的源码级证据剖析其 URL 拼接、编码、压缩、重试与发送队列的工作原理并给出直接可运行的 YAML 配置与推送示例读完即可独立完成从 Collector 到 Tempo 的 HTTP 遥测链路搭建。组件概览用 HTTP 承载 OTLP 的导出器otlp_http是 OpenTelemetry Collector 生态中的标准 Exporter 组件其核心职责是把内存中的遥测数据序列化后通过 HTTP POST 请求发送到远端接收端典型场景即 Grafana Tempo 的 OTLP/HTTP 接收器。它支持四类信号的导出traces、metrics、logs 已进入stable稳定阶段profiles 目前处于alpha阶段该组件随 core、contrib、k8s、otlp 等官方发行版分发。从 metadata.yaml 生成的稳定性声明 可以看到TracesStability Stable、MetricsStability Stable、LogsStability StableProfilesStability Alpha组件类型名为otlp_http同时保留了一个将被移除的废弃别名otlphttp注意如果存量配置中仍在使用otlphttp别名应尽快改为otlp_http未来版本会将其删除。核心配置必须项与可选项全表必填配置endpoint无默认值发送数据的目标基础 URL例如https://example.com:4318。导出器会在该基础 URL 后按信号类型自动拼接对应路径traces →/v1/tracesmetrics →/v1/metricslogs →/v1/logsprofiles →/v1development/profiles可选配置配置项默认值说明traces_endpoint无发送 trace 数据的完整 URL一旦设置对 traces 信号将忽略endpointmetrics_endpoint无发送 metric 数据的完整 URL一旦设置对 metrics 信号将忽略endpointlogs_endpoint无发送 log 数据的完整 URLprofiles_endpoint无发送 profile 数据的完整 URL一旦设置对 profiles 信号将忽略endpointtls见下文TLS 客户端配置完整选项见 TLS 配置说明timeout30sHTTP 请求超时时间语义等价于net/http包中Client.Timeoutread_buffer_size0HTTP 客户端读取缓冲区大小对应http.Transport.ReadBufferSizewrite_buffer_size512 * 1024HTTP 客户端写入缓冲区大小对应http.Transport.WriteBufferSizeencodingproto消息编码格式合法值proto、jsonretry_on_failure见下文失败重试策略完整选项见 Retry on Failuresending_queue见下文发送队列配置完整选项见 Sending Queue这些字段的定义可以在 config.go 中逐一核对Config结构体通过mapstructure标签与 YAML 配置建立映射并内嵌confighttp.ClientConfig、exporterhelper.QueueBatchConfig、configretry.BackOffConfig三组公共配置。最简示例exporters: otlp_http: endpoint: https://example.com:4318仅配置endpoint即可工作导出的 traces 会发往https://example.com:4318/v1/tracesmetrics 发往https://example.com:4318/v1/metricslogs 发往https://example.com:4318/v1/logs。配置校验规则Config.Validate() 定义了该组件的唯一强制校验必须至少指定一个端点——endpoint、traces_endpoint、metrics_endpoint、logs_endpoint、profiles_endpoint五者至少其一非空否则启动时报错at least one endpoint must be specified。默认值从哪来工厂函数与源码级证据组件默认值并非散落在文档中而是集中定义在 factory.go 的 createDefaultConfigclientConfig : confighttp.NewDefaultClientConfig() clientConfig.Timeout 30 * time.Second // Default to gzip compression clientConfig.Compression configcompression.TypeGzip // We almost read 0 bytes, so no need to tune ReadBufferSize. clientConfig.WriteBufferSize 512 * 1024 return Config{ RetryConfig: configretry.NewDefaultBackOffConfig(), QueueConfig: configoptional.Some(exporterhelper.NewDefaultQueueConfig()), Encoding: EncodingProto, ClientConfig: clientConfig, }从中可以看到几个关键默认行为默认timeout 30s、默认write_buffer_size 512 * 1024、默认read_buffer_size 0导出器几乎不读取响应数据因此无需调整读缓冲默认启用 gzip 压缩默认encoding protoEncoding类型在 config.go 中通过UnmarshalText实现严格的枚举解析非法编码会直接报invalid encoding type。NewFactory还通过xexporter.WithDeprecatedTypeAlias(metadata.DeprecatedType)注册了otlphttp废弃别名这正是文档要求用户迁移到otlp_http的代码依据。URL 拼接原理composeSignalURL 与路径追加规则composeSignalURL 是理解端点行为的关键函数其逻辑分三支信号级端点优先如果配置了traces_endpoint/metrics_endpoint/logs_endpoint/profiles_endpoint直接使用该完整 URLendpoint对该信号失效未配置任何端点报错either endpoint or signal_endpoint must be specified基于endpoint拼接若endpoint以/结尾则拼接为endpoint version / signalName否则拼接为endpoint / version / signalName。四类信号在各自工厂函数中传入不同的版本与名称traces(traces, v1)→/v1/tracesmetrics(metrics, v1)→/v1/metricslogs(logs, v1)→/v1/logsprofiles(profiles, v1development)→/v1development/profiles注意 profile 使用的是实验性版本前缀v1development对应实现分别见 createTraces、createMetrics、createLogs 与 createProfiles。此外endpointAttributes会把解析出的主机名、端口、路径作为语义化属性server.address、server.port、url.path附加到导出器自身的遥测指标上便于在监控面板中按目标端点区分不同导出器实例。编码与压缩proto/json 与 gzip编码格式默认使用protoprotobuf编码对应Content-Type: application/x-protobuf可切换为json对应Content-Type: application/json。在 otlp.go 的 pushTraces 等函数 中可以看到编码通过tr.MarshalJSON()或tr.MarshalProto()完成非法编码会被包装为consumererror.NewPermanent永久性错误不参与重试。exporters: otlp_http: ... encoding: json压缩默认启用gzip压缩详见 compression comparison 的基准对比。若目标接收端不支持或调试需要可显式关闭exporters: otlp_http: ... compression: none在 client.go 的 ToClient 中压缩通过newCompressRoundTripper以RoundTripper装饰器方式实现支持 gzip、zlib、deflate、snappy、zstd 等格式none表示不压缩未显式指定压缩级别时使用configcompression.DefaultCompressionLevel。失败处理重试、限流与部分成功retry_on_failure该配置段完整定义于 Retry on Failure参数默认值说明enabledtrue是否启用重试initial_interval5s首次失败后的等待时间max_interval30s退避间隔上限max_elapsed_time300s尝试发送单个批次的总时间上限设为0表示永不停止重试multiplier1.5每次重试间隔的放大系数可重试状态码与限流throttling在 export 函数 中HTTP 响应的处理遵循 OTLP 规范2xx请求成功随后交给部分成功处理器解析响应可重试状态码由 isRetryableStatusCode 判定仅包括429 Too Many Requests、502 Bad Gateway、503 Service Unavailable、504 Gateway Timeout永久错误其他 4xx/5xx 状态码被包装为永久性错误直接丢弃该批次不再重试限流处理对429/503响应导出器会解析Retry-After响应头支持秒数或 RFC1123 日期两种格式若服务器明确给出了重试时间则返回带延迟的ThrottleRetry让重试器按服务端要求等待若未携带该头则按普通可重试错误处理。错误响应体解析readResponseStatus 按 OTLP 规范读取 4xx/5xx 响应体应为一个 protobuf 编码的google.rpc.Status消息将其message与details并入错误信息使排障时能看到服务端返回的具体原因。部分成功Partial Success当响应为 2xx 但携带PartialSuccess信息时traces/metrics/logs/profiles 各自的 partialSuccessHandler 会解析响应体并打印 WARN 日志报告被拒绝的 span 数、数据点数、日志记录数或 profile 样本数。例如Partial success response message... dropped_spans123发送队列与持久化sending_queue完整选项见 Sending Queue参数默认值说明enabledtrue是否启用发送队列num_consumers10从队列取批次发送的消费者数量queue_size1000队列容量上限计量单位由sizer决定sizerrequests队列计量方式requests按请求批次数性能最好、items按最小数据单元如 span/数据点/日志记录、bytes按序列化字节数性能最差wait_for_resultfalse是否阻塞等待请求处理完成block_on_overflowfalse队列满时是阻塞等待空间释放还是立即拒绝batch禁用批处理配置flush_timeout默认200ms、min_size默认8192、max_size默认0即无上限、sizer、partitionstorage无指定存储扩展后启用持久化队列几个重要行为说明队列溢出数据无法进入队列时默认直接丢弃并上报otelcol_exporter_enqueue_failed_*指标启用block_on_overflow后调用方会等待空间释放持久化队列设置sending_queue.storage后改用指定存储扩展filestorage是常用且安全的选择落盘缓冲Collector 重启后未发送完的数据会被继续导出但注意 Auth 扩展设置的上下文不会随持久化数据传播超时单位initial_interval、max_interval、max_elapsed_time、timeout等时长参数均接受 Go duration 字符串ns、us/µs、ms、s、m、h。TLS 客户端配置要点tls段复用 TLS Configuration Settings 中的客户端选项常用项包括参数默认值说明insecurefalse是否完全关闭传输层安全ca_file无校验服务端的 CA 证书路径cert_file/key_file无客户端证书与私钥双向 TLS 用insecure_skip_verifyfalse是否跳过服务端证书校验min_version1.2最低可接受 TLS 版本max_version由 crypto/tls 决定当前为 TLS 1.3最高可接受 TLS 版本server_name_override无覆盖用于证书校验的服务器名include_system_ca_certs_poolfalse是否加载系统 CA 证书池底层实现上confighttp.ClientConfig.ToClient 会克隆http.DefaultTransport套用 TLS 配置、代理proxy_url、读写缓冲、连接池参数max_idle_conns默认 100、idle_conn_timeout默认 90s、force_attempt_http2默认开启后再依次叠加 middleware、Auth RoundTripper、自定义 headers 与压缩 RoundTripper最终用otelhttp.NewTransport包装以注入 OpenTelemetry 链路追踪与指标埋点。若配置中引用了 auth 或 middleware 扩展但宿主不支持 extensions会直接报错拒绝启动。实战把遥测数据推到 Grafana TempoOTLP/HTTP 是 Grafana Tempo 接收遥测数据的标准途径之一Tempo 默认在4318 端口监听 OTLP/HTTP 请求gRPC 走 4317 端口。下面对接示例与仓库内官方指南 Push spans with HTTP or gRPC 一致。Collector 侧配置receivers: otlp: protocols: grpc: http: exporters: otlp_http: endpoint: http://tempo:4318 # Tempo 的 OTLP/HTTP 接收地址 tls: insecure: true retry_on_failure: enabled: true initial_interval: 5s max_interval: 30s max_elapsed_time: 300s sending_queue: enabled: true num_consumers: 10 queue_size: 1000 service: pipelines: traces: receivers: [otlp] exporters: [otlp_http]启用多租户时需通过X-Scope-OrgID请求头传递租户 IDexporters: otlp_http: endpoint: http://tempo:4318 headers: X-Scope-OrgID: my-tenant直接用 curl 验证 /v1/traces 端点无需任何 Collector可直接向 Tempo 的/v1/traces端点 POST 一段 OTLP/JSON 负载这是验证整条链路最直接的方式curl -X POST -H Content-Type: application/json http://localhost:4318/v1/traces -d { resourceSpans: [{ resource: { attributes: [{ key: service.name, value: {stringValue: my.service} }] }, scopeSpans: [{ scope: {name: my.library, version: 1.0.0}, spans: [{ traceId: 5B8EFFF798038103D269B633813FC700, spanId: EEE19B7EC3C1B100, name: I am a span!, startTimeUnixNano: 1689969302000000000, endTimeUnixNano: 1689970000000000000, kind: 2, attributes: [{ key: my.span.attr, value: {stringValue: some value} }] }] }] }] }注意startTimeUnixNano/endTimeUnixNano的单位是纳秒Linux 下可用date %s%N获取当前纳秒时间echo $((epochTimeMilliseconds * 1000000))可把毫秒换算成纳秒。检索验证通过 Tempo 的查询 API 按 service 名检索启用多租户时同样需要X-Scope-OrgID头curl -G -s http://localhost:3200/api/search --data-urlencode q{ resource.service.name my.service } | jq .也可以按 traceId 直接取回整条 tracecurl http://localhost:3200/api/v2/traces/5b8efff798038103d269b633813fc700常见问题与排障现象可能原因与排查方向启动报at least one endpoint must be specified五类端点配置全部为空参见 Validate报endpoint must be a valid URLendpoint或各信号_endpoint不是合法 URL见 newExporter报invalid encoding typeencoding只能是proto或json收到429/503且大量重试目标端在限流按服务端Retry-After头的延迟等待可调大max_elapsed_time数据丢失但无报错检查发送队列是否溢出otelcol_exporter_enqueue_failed_*指标必要时调大queue_size或启用block_on_overflow响应 400/500 无法解析检查错误响应体是否为合法的google.rpc.Status并核对目标端点路径traces 应为/v1/traces配置中用了otlphttp别名尽快迁移为otlp_http别名将在未来版本移除扩展阅读组件全部配置字段定义config.go组件出厂默认值与工厂注册factory.goHTTP 发送、状态码处理与部分成功解析otlp.go发送队列与重试机制的完整参数exporterhelper/README.mdHTTP 客户端连接池、压缩、Auth、headers配置confighttp/client.goTempo 侧 OTLP/HTTP 推送实战指南docs/sources/tempo/api_docs/pushing-spans-with-http.md【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Grafana Tempo 中的 OTLP HTTP Exporter（otlp_http）配置实战与源码解析
Grafana Tempo 中的 OTLP HTTP Exporterotlp_http配置实战与源码解析【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo本篇技术指南聚焦于 OpenTelemetry Collector 的otlp_httpExporter 组件它通过 HTTP 协议、采用 OTLP 格式把 traces、metrics、logs 与 profiles 四类遥测数据发送到 Grafana Tempo 等后端。本文会完整讲解它的全部配置项、默认值与可选参数结合仓库内vendor/go.opentelemetry.io/collector/exporter/otlphttpexporter/的源码级证据剖析其 URL 拼接、编码、压缩、重试与发送队列的工作原理并给出直接可运行的 YAML 配置与推送示例读完即可独立完成从 Collector 到 Tempo 的 HTTP 遥测链路搭建。组件概览用 HTTP 承载 OTLP 的导出器otlp_http是 OpenTelemetry Collector 生态中的标准 Exporter 组件其核心职责是把内存中的遥测数据序列化后通过 HTTP POST 请求发送到远端接收端典型场景即 Grafana Tempo 的 OTLP/HTTP 接收器。它支持四类信号的导出traces、metrics、logs 已进入stable稳定阶段profiles 目前处于alpha阶段该组件随 core、contrib、k8s、otlp 等官方发行版分发。从 metadata.yaml 生成的稳定性声明 可以看到TracesStability Stable、MetricsStability Stable、LogsStability StableProfilesStability Alpha组件类型名为otlp_http同时保留了一个将被移除的废弃别名otlphttp注意如果存量配置中仍在使用otlphttp别名应尽快改为otlp_http未来版本会将其删除。核心配置必须项与可选项全表必填配置endpoint无默认值发送数据的目标基础 URL例如https://example.com:4318。导出器会在该基础 URL 后按信号类型自动拼接对应路径traces →/v1/tracesmetrics →/v1/metricslogs →/v1/logsprofiles →/v1development/profiles可选配置配置项默认值说明traces_endpoint无发送 trace 数据的完整 URL一旦设置对 traces 信号将忽略endpointmetrics_endpoint无发送 metric 数据的完整 URL一旦设置对 metrics 信号将忽略endpointlogs_endpoint无发送 log 数据的完整 URLprofiles_endpoint无发送 profile 数据的完整 URL一旦设置对 profiles 信号将忽略endpointtls见下文TLS 客户端配置完整选项见 TLS 配置说明timeout30sHTTP 请求超时时间语义等价于net/http包中Client.Timeoutread_buffer_size0HTTP 客户端读取缓冲区大小对应http.Transport.ReadBufferSizewrite_buffer_size512 * 1024HTTP 客户端写入缓冲区大小对应http.Transport.WriteBufferSizeencodingproto消息编码格式合法值proto、jsonretry_on_failure见下文失败重试策略完整选项见 Retry on Failuresending_queue见下文发送队列配置完整选项见 Sending Queue这些字段的定义可以在 config.go 中逐一核对Config结构体通过mapstructure标签与 YAML 配置建立映射并内嵌confighttp.ClientConfig、exporterhelper.QueueBatchConfig、configretry.BackOffConfig三组公共配置。最简示例exporters: otlp_http: endpoint: https://example.com:4318仅配置endpoint即可工作导出的 traces 会发往https://example.com:4318/v1/tracesmetrics 发往https://example.com:4318/v1/metricslogs 发往https://example.com:4318/v1/logs。配置校验规则Config.Validate() 定义了该组件的唯一强制校验必须至少指定一个端点——endpoint、traces_endpoint、metrics_endpoint、logs_endpoint、profiles_endpoint五者至少其一非空否则启动时报错at least one endpoint must be specified。默认值从哪来工厂函数与源码级证据组件默认值并非散落在文档中而是集中定义在 factory.go 的 createDefaultConfigclientConfig : confighttp.NewDefaultClientConfig() clientConfig.Timeout 30 * time.Second // Default to gzip compression clientConfig.Compression configcompression.TypeGzip // We almost read 0 bytes, so no need to tune ReadBufferSize. clientConfig.WriteBufferSize 512 * 1024 return Config{ RetryConfig: configretry.NewDefaultBackOffConfig(), QueueConfig: configoptional.Some(exporterhelper.NewDefaultQueueConfig()), Encoding: EncodingProto, ClientConfig: clientConfig, }从中可以看到几个关键默认行为默认timeout 30s、默认write_buffer_size 512 * 1024、默认read_buffer_size 0导出器几乎不读取响应数据因此无需调整读缓冲默认启用 gzip 压缩默认encoding protoEncoding类型在 config.go 中通过UnmarshalText实现严格的枚举解析非法编码会直接报invalid encoding type。NewFactory还通过xexporter.WithDeprecatedTypeAlias(metadata.DeprecatedType)注册了otlphttp废弃别名这正是文档要求用户迁移到otlp_http的代码依据。URL 拼接原理composeSignalURL 与路径追加规则composeSignalURL 是理解端点行为的关键函数其逻辑分三支信号级端点优先如果配置了traces_endpoint/metrics_endpoint/logs_endpoint/profiles_endpoint直接使用该完整 URLendpoint对该信号失效未配置任何端点报错either endpoint or signal_endpoint must be specified基于endpoint拼接若endpoint以/结尾则拼接为endpoint version / signalName否则拼接为endpoint / version / signalName。四类信号在各自工厂函数中传入不同的版本与名称traces(traces, v1)→/v1/tracesmetrics(metrics, v1)→/v1/metricslogs(logs, v1)→/v1/logsprofiles(profiles, v1development)→/v1development/profiles注意 profile 使用的是实验性版本前缀v1development对应实现分别见 createTraces、createMetrics、createLogs 与 createProfiles。此外endpointAttributes会把解析出的主机名、端口、路径作为语义化属性server.address、server.port、url.path附加到导出器自身的遥测指标上便于在监控面板中按目标端点区分不同导出器实例。编码与压缩proto/json 与 gzip编码格式默认使用protoprotobuf编码对应Content-Type: application/x-protobuf可切换为json对应Content-Type: application/json。在 otlp.go 的 pushTraces 等函数 中可以看到编码通过tr.MarshalJSON()或tr.MarshalProto()完成非法编码会被包装为consumererror.NewPermanent永久性错误不参与重试。exporters: otlp_http: ... encoding: json压缩默认启用gzip压缩详见 compression comparison 的基准对比。若目标接收端不支持或调试需要可显式关闭exporters: otlp_http: ... compression: none在 client.go 的 ToClient 中压缩通过newCompressRoundTripper以RoundTripper装饰器方式实现支持 gzip、zlib、deflate、snappy、zstd 等格式none表示不压缩未显式指定压缩级别时使用configcompression.DefaultCompressionLevel。失败处理重试、限流与部分成功retry_on_failure该配置段完整定义于 Retry on Failure参数默认值说明enabledtrue是否启用重试initial_interval5s首次失败后的等待时间max_interval30s退避间隔上限max_elapsed_time300s尝试发送单个批次的总时间上限设为0表示永不停止重试multiplier1.5每次重试间隔的放大系数可重试状态码与限流throttling在 export 函数 中HTTP 响应的处理遵循 OTLP 规范2xx请求成功随后交给部分成功处理器解析响应可重试状态码由 isRetryableStatusCode 判定仅包括429 Too Many Requests、502 Bad Gateway、503 Service Unavailable、504 Gateway Timeout永久错误其他 4xx/5xx 状态码被包装为永久性错误直接丢弃该批次不再重试限流处理对429/503响应导出器会解析Retry-After响应头支持秒数或 RFC1123 日期两种格式若服务器明确给出了重试时间则返回带延迟的ThrottleRetry让重试器按服务端要求等待若未携带该头则按普通可重试错误处理。错误响应体解析readResponseStatus 按 OTLP 规范读取 4xx/5xx 响应体应为一个 protobuf 编码的google.rpc.Status消息将其message与details并入错误信息使排障时能看到服务端返回的具体原因。部分成功Partial Success当响应为 2xx 但携带PartialSuccess信息时traces/metrics/logs/profiles 各自的 partialSuccessHandler 会解析响应体并打印 WARN 日志报告被拒绝的 span 数、数据点数、日志记录数或 profile 样本数。例如Partial success response message... dropped_spans123发送队列与持久化sending_queue完整选项见 Sending Queue参数默认值说明enabledtrue是否启用发送队列num_consumers10从队列取批次发送的消费者数量queue_size1000队列容量上限计量单位由sizer决定sizerrequests队列计量方式requests按请求批次数性能最好、items按最小数据单元如 span/数据点/日志记录、bytes按序列化字节数性能最差wait_for_resultfalse是否阻塞等待请求处理完成block_on_overflowfalse队列满时是阻塞等待空间释放还是立即拒绝batch禁用批处理配置flush_timeout默认200ms、min_size默认8192、max_size默认0即无上限、sizer、partitionstorage无指定存储扩展后启用持久化队列几个重要行为说明队列溢出数据无法进入队列时默认直接丢弃并上报otelcol_exporter_enqueue_failed_*指标启用block_on_overflow后调用方会等待空间释放持久化队列设置sending_queue.storage后改用指定存储扩展filestorage是常用且安全的选择落盘缓冲Collector 重启后未发送完的数据会被继续导出但注意 Auth 扩展设置的上下文不会随持久化数据传播超时单位initial_interval、max_interval、max_elapsed_time、timeout等时长参数均接受 Go duration 字符串ns、us/µs、ms、s、m、h。TLS 客户端配置要点tls段复用 TLS Configuration Settings 中的客户端选项常用项包括参数默认值说明insecurefalse是否完全关闭传输层安全ca_file无校验服务端的 CA 证书路径cert_file/key_file无客户端证书与私钥双向 TLS 用insecure_skip_verifyfalse是否跳过服务端证书校验min_version1.2最低可接受 TLS 版本max_version由 crypto/tls 决定当前为 TLS 1.3最高可接受 TLS 版本server_name_override无覆盖用于证书校验的服务器名include_system_ca_certs_poolfalse是否加载系统 CA 证书池底层实现上confighttp.ClientConfig.ToClient 会克隆http.DefaultTransport套用 TLS 配置、代理proxy_url、读写缓冲、连接池参数max_idle_conns默认 100、idle_conn_timeout默认 90s、force_attempt_http2默认开启后再依次叠加 middleware、Auth RoundTripper、自定义 headers 与压缩 RoundTripper最终用otelhttp.NewTransport包装以注入 OpenTelemetry 链路追踪与指标埋点。若配置中引用了 auth 或 middleware 扩展但宿主不支持 extensions会直接报错拒绝启动。实战把遥测数据推到 Grafana TempoOTLP/HTTP 是 Grafana Tempo 接收遥测数据的标准途径之一Tempo 默认在4318 端口监听 OTLP/HTTP 请求gRPC 走 4317 端口。下面对接示例与仓库内官方指南 Push spans with HTTP or gRPC 一致。Collector 侧配置receivers: otlp: protocols: grpc: http: exporters: otlp_http: endpoint: http://tempo:4318 # Tempo 的 OTLP/HTTP 接收地址 tls: insecure: true retry_on_failure: enabled: true initial_interval: 5s max_interval: 30s max_elapsed_time: 300s sending_queue: enabled: true num_consumers: 10 queue_size: 1000 service: pipelines: traces: receivers: [otlp] exporters: [otlp_http]启用多租户时需通过X-Scope-OrgID请求头传递租户 IDexporters: otlp_http: endpoint: http://tempo:4318 headers: X-Scope-OrgID: my-tenant直接用 curl 验证 /v1/traces 端点无需任何 Collector可直接向 Tempo 的/v1/traces端点 POST 一段 OTLP/JSON 负载这是验证整条链路最直接的方式curl -X POST -H Content-Type: application/json http://localhost:4318/v1/traces -d { resourceSpans: [{ resource: { attributes: [{ key: service.name, value: {stringValue: my.service} }] }, scopeSpans: [{ scope: {name: my.library, version: 1.0.0}, spans: [{ traceId: 5B8EFFF798038103D269B633813FC700, spanId: EEE19B7EC3C1B100, name: I am a span!, startTimeUnixNano: 1689969302000000000, endTimeUnixNano: 1689970000000000000, kind: 2, attributes: [{ key: my.span.attr, value: {stringValue: some value} }] }] }] }] }注意startTimeUnixNano/endTimeUnixNano的单位是纳秒Linux 下可用date %s%N获取当前纳秒时间echo $((epochTimeMilliseconds * 1000000))可把毫秒换算成纳秒。检索验证通过 Tempo 的查询 API 按 service 名检索启用多租户时同样需要X-Scope-OrgID头curl -G -s http://localhost:3200/api/search --data-urlencode q{ resource.service.name my.service } | jq .也可以按 traceId 直接取回整条 tracecurl http://localhost:3200/api/v2/traces/5b8efff798038103d269b633813fc700常见问题与排障现象可能原因与排查方向启动报at least one endpoint must be specified五类端点配置全部为空参见 Validate报endpoint must be a valid URLendpoint或各信号_endpoint不是合法 URL见 newExporter报invalid encoding typeencoding只能是proto或json收到429/503且大量重试目标端在限流按服务端Retry-After头的延迟等待可调大max_elapsed_time数据丢失但无报错检查发送队列是否溢出otelcol_exporter_enqueue_failed_*指标必要时调大queue_size或启用block_on_overflow响应 400/500 无法解析检查错误响应体是否为合法的google.rpc.Status并核对目标端点路径traces 应为/v1/traces配置中用了otlphttp别名尽快迁移为otlp_http别名将在未来版本移除扩展阅读组件全部配置字段定义config.go组件出厂默认值与工厂注册factory.goHTTP 发送、状态码处理与部分成功解析otlp.go发送队列与重试机制的完整参数exporterhelper/README.mdHTTP 客户端连接池、压缩、Auth、headers配置confighttp/client.goTempo 侧 OTLP/HTTP 推送实战指南docs/sources/tempo/api_docs/pushing-spans-with-http.md【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考