OpenTelemetry Python服务无法将Trace导出至Jaeger问题排查求助

1. 确认OTLP HTTP导出器依赖已安装 #

Python的OTLP HTTP导出器需要单独的包，与GRPC导出器包不通用，执行以下命令检查依赖是否存在：

pip list | grep opentelemetry-exporter-otlp-proto-http

如果无输出，安装对应依赖：

pip install opentelemetry-exporter-otlp-proto-http

2. 调整端点配置，避免手动拼接路径 #

命令行中手动指定/v1/traces路径可能触发兼容性问题，尝试去掉路径，只保留基础端点地址：

opentelemetry-instrument \
    --traces_exporter console,otlp \
    --metrics_exporter console \
    --service_name llama-indexer \
    --exporter_otlp_protocol http/protobuf \
    --exporter_otlp_endpoint http://localhost:4318 \
    start_api

导出器会自动根据协议规则拼接正确的/v1/traces路径。

3. 启用调试日志定位错误 #

设置日志级别为debug，查看导出过程中的具体错误细节：

OTEL_LOG_LEVEL=debug opentelemetry-instrument \
    --traces_exporter console,otlp \
    --metrics_exporter console \
    --service_name llama-indexer \
    --exporter_otlp_protocol http/protobuf \
    --exporter_otlp_endpoint http://localhost:4318 \
    start_api

重点关注包含OTLP、exporter关键字的日志，比如请求失败状态码、连接超时、序列化错误等信息。

4. 直接测试Jaeger的OTLP HTTP端点可用性 #

用工具发送测试Trace，验证端点是否能正常接收数据：

方法1：使用opentelemetry-cli（需先安装：pip install opentelemetry-cli） #

opentelemetry-cli span create --name "test-http-span" --service "test-service" --endpoint http://localhost:4318/v1/traces

方法2：使用curl（需准备protobuf格式测试数据） #

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/x-protobuf" \
  --data-binary @test_trace.protobuf

如果Jaeger能收到测试Trace，说明端点正常，问题出在Python服务的Instrumentation配置。

5. 排查代理或防火墙拦截 #

检查Python进程是否受到代理影响，设置NO_PROXY环境变量排除本地地址：

NO_PROXY=localhost,127.0.0.1 opentelemetry-instrument \
    --traces_exporter console,otlp \
    --metrics_exporter console \
    --service_name llama-indexer \
    --exporter_otlp_protocol http/protobuf \
    --exporter_otlp_endpoint http://localhost:4318 \
    start_api

6. 升级OpenTelemetry相关包到最新版本 #

版本不兼容可能导致命令行工具或导出器异常，执行升级操作：

pip install --upgrade opentelemetry-distro opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-fastapi

7. 替换命令行配置为代码手动配置 #

如果命令行参数存在兼容性问题，尝试在FastAPI代码中手动配置导出器：

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import Resource
from fastapi import FastAPI

# 配置服务资源标识
resource = Resource(attributes={"service.name": "llama-indexer"})
trace.set_tracer_provider(TracerProvider(resource=resource))
tracer = trace.get_tracer(__name__)

# 配置OTLP HTTP导出器
otlp_exporter = OTLPSpanExporter(
    endpoint="http://localhost:4318/v1/traces",
)

# 添加批处理Span处理器
span_processor = BatchSpanProcessor(otlp_exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

# FastAPI应用核心代码
app = FastAPI()

@app.get("/")
def read_root():
    with tracer.start_as_current_span("read-root-operation"):
        return {"Hello": "World"}

直接运行该代码，无需opentelemetry-instrument命令，查看Jaeger是否能收到Trace。

8. 验证Jaeger容器的OTLP HTTP接收状态 #

查看Jaeger容器日志，确认OTLP HTTP服务已正常启动：

docker logs jaeger | grep "HTTP server"

若输出包含Starting HTTP server on :4318，说明Jaeger已正常监听OTLP HTTP端口。

内容的提问来源于stack exchange，提问作者Sammy Roberts