Jaeger可通过Docker Compose一键部署并集成全链路追踪，核心是让Trace ID贯穿请求全程、与结构化日志对齐，各服务通过OTEL环境变量上报数据至jaeger:4317或UDP端口，并统一置于自定义网络确保通信稳定。
直接在 Docker Compose 中集成分布式链路追踪，能将原本分散在各服务的日志和调用路径自动关联起来，让延迟问题从“猜哪里慢”变成“点开就看到哪一环卡住了”。关键不是堆工具，而是让 Trace ID 贯穿请求全程，并与日志对齐。
让每个服务输出带 Trace ID 的结构化日志
日志若不含上下文，再好的追踪系统也连不上线。服务启动时需自动注入 Trace ID，并随日志一起输出。
- Java 服务（如 Spring Boot）：引入 OpenTelemetry Java Agent，启动时加 JVM 参数
-javaagent:/path/to/opentelemetry-javaagent.jar，它会自动为 logback/log4j 日志添加trace_id和span_id字段 - Python 服务：使用 opentelemetry-instrument 命令启动应用，例如
opentelemetry-instrument --traces-exporter jaeger_thrift python app.py，同时配置 logging 模块输出 JSON 格式日志，包含 trace_id - 所有服务统一日志格式：推荐输出标准 JSON，字段至少含
time、level、service、trace_id、span_id、msg，便于后续聚合与检索
用 Docker Compose 统一部署 Jaeger 并打通网络
Jaeger 是轻量、易集成的追踪后端，适合 Compose 环境。重点是让各服务能稳定上报数据，且 UI 可访问。
- 在
docker-compose.yml中新增jaeger服务，使用官方镜像：jaeger:image: jaegertracing/all-in-one:1.55ports: ["16686:16686", "6831:6831/udp"]environment: [COLLECTOR_ZIPKIN_HOST_PORT=:9411]networks: [compreface-network] - 确保所有业务服务（如 api、embedder、db-proxy）与 Jaeger 在同一自定义网络（如
compreface-network），避免因默认 bridge 网络导致 UDP 上报失败 - 各服务环境变量中设置追踪出口：
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317（gRPC）或OTEL_EXPORTER_JAEGER_UDP_HOST=jaeger（Thrift UDP），根据 SDK 选用
通过日志命令快速反查调用链
开发或排障时，不需要切页面——一条命令就能从异常日志定位到完整调用链。
- 查某次错误的 Trace ID：
docker compose logs api | grep -o 'trace_id:[a-f0-9]\{32\}' | head -1 - 拿到 Trace ID 后，直接打开 Jaeger UI：
http://localhost:16686/trace/{trace_id}，查看各 span 耗时、状态、标签和日志注释 - 进一步关联其他服务日志：
docker compose logs embedder | grep "{trace_id}"，验证上下游是否收到同一上下文
结合健康检查避免追踪断链
服务刚启动时若未完成 SDK 初始化，可能漏报前几个请求的追踪数据。用健康检查确保追踪就绪后再接入流量。
- 为关键服务（如网关、计算服务）添加
healthcheck，探测路径可设为/health?include=tracing，由应用返回当前 tracer 是否已注册 - 设置足够宽的
start_period（建议 ≥45s），尤其对 JVM 类服务，避免 tracer 初始化未完成就被判定 unhealthy - 在依赖关系中明确声明顺序：
depends_on:jaeger:condition: service_healthy
