为Claude Code构建OpenTelemetry可观测性：从黑盒到透明盒的实践

1. 项目概述：为Claude Code构建可观测性基础设施

最近在折腾一个挺有意思的项目，起因是团队里用Claude Code（一个基于Claude模型的代码生成工具）的人越来越多，但每次它“卡壳”或者生成的结果不太对劲时，排查起来特别费劲。你只知道它“慢了”或者“错了”，但具体是哪个环节耗时、内部处理逻辑是怎样的、资源消耗如何，基本是两眼一抹黑。这感觉就像开一辆没有仪表盘的车，油门踩下去不知道转速，方向盘打了不知道轮胎角度，全凭感觉。

于是，我决定给我们的Claude Code部署一套完整的OpenTelemetry（简称OTel）可观测性方案。这个项目仓库flysloughofdespond447/claude-code-opentelemetry-setup就是整个实践的结晶。简单说，它的目标就是把Claude Code这个“黑盒”变成一个“透明盒”，让我们能清晰地看到每一次代码生成请求的完整生命周期：从请求发起到模型推理，再到最终响应，期间的延迟、错误、内部函数调用链路、资源指标全部一目了然。

这不仅仅是加个日志那么简单。OpenTelemetry是一套云原生基金会（CNCF）孵化的标准，它统一了追踪（Traces）、指标（Metrics）、日志（Logs）这三大可观测性支柱的数据采集和导出。通过它，我们可以用标准化的方式，在Claude Code的代码关键位置插入“探针”（Instrumentation），自动收集细粒度的性能数据，并发送到我们喜欢的后端分析平台，比如Jaeger、Prometheus或者商业化的Datadog、New Relic。

对于任何在生产环境或重度使用场景下依赖Claude Code的开发者或团队来说，这套 setup 的价值是巨大的。它能帮你：

• 精准定位性能瓶颈：是网络延迟？是模型加载慢？还是某个后处理函数效率低下？追踪链路会告诉你答案。
• 快速诊断错误根源：当Claude Code返回意外结果或抛出异常时，完整的追踪上下文能帮你重现问题现场，而不是靠猜。
• 量化资源消耗与成本：监控每次调用的Token消耗、内存使用、CPU时间，为资源规划和成本优化提供数据支撑。
• 提升团队协作与调试效率：拥有统一的、可视化的数据视图，不同角色的成员（开发、运维、算法）能用同一种“语言”讨论问题。

接下来，我会详细拆解整个方案的架构设计、核心组件的选型与配置、具体的代码插桩实践，以及在实际部署中踩过的坑和总结出的技巧。无论你是想为自己使用的代码生成工具增加可观测性，还是对OpenTelemetry如何接入AI应用感兴趣，这份经验分享都应该能给你提供一条清晰的路径。

2. 架构设计与核心组件选型

给Claude Code套上OpenTelemetry，听起来简单，但做之前得先想清楚整个数据流怎么走。你不能胡乱插几个日志点就完事，需要一个清晰、可扩展、且对原应用侵入性最小的架构。我的核心思路是：“插桩采集 -> 统一处理 -> 导出可视化”。

2.1 整体架构视图

整个可观测性栈可以分成三层：

1. 应用层（Claude Code）：这是被观测的对象。我们需要在它的Python代码中，通过OpenTelemetry的API和SDK，在关键的业务逻辑处（如接收请求、调用模型、处理响应）添加追踪Span和记录指标。
2. 采集与处理层（OpenTelemetry Collector）：这是中枢神经。我强烈推荐使用OpenTelemetry Collector作为一个独立的守护进程。它的好处是解耦。应用（Claude Code）只负责把数据用一种标准格式（OTLP/gRPC或HTTP）发送给本地的Collector，而不需要关心后端是什么。Collector负责接收、处理（过滤、采样、添加属性）、批量发送数据到不同的后端。这样，当你需要更换可视化工具（比如从Jaeger换成Tempo）时，只需修改Collector的配置，无需触动Claude Code的代码。
3. 后端存储与可视化层：这是观察数据的窗口。根据团队习惯和基础设施，可以选择开源组合或商业方案。我这次实践用的是经典的开源组合：
   • 追踪（Traces）：Jaeger。它专为分布式追踪设计，界面直观，能清晰展示调用链和时序关系。
   • 指标（Metrics）：Prometheus+Grafana。Prometheus拉取Collector暴露的指标，Grafana则用于制作丰富的监控仪表盘。
   • 日志（Logs）：虽然OTel也支持日志，但考虑到Claude Code本身可能已有日志框架（如logging），我采用了将日志关联到追踪的模式。即在打印日志时，注入当前追踪的Trace ID和Span ID，这样在Grafana Loki或Elasticsearch中查日志时，能一键跳转到对应的追踪链路，实现联动分析。

这个架构的灵活性很高。如果你在Kubernetes环境中，Collector可以以DaemonSet或Sidecar形式部署；如果是单机或虚拟机，作为一个系统服务运行即可。

2.2 关键组件选型与考量

OpenTelemetry Python SDK vs. 自动插桩（Instrumentation）库这是第一个决策点。OpenTelemetry提供了两种主要方式来为Python应用添加可观测性：

• 手动插桩：使用opentelemetry-api和opentelemetry-sdk，在代码中显式地创建Span、记录属性。这种方式控制力最强，可以精确地在你认为重要的业务逻辑处埋点。
• 自动插桩：使用opentelemetry-instrumentation系列包。它们通过Python的“猴子补丁”（Monkey-patching）机制，自动为流行的框架和库（如Flask、Django、requests、httpx等）注入追踪逻辑。你几乎不需要修改代码。

对于Claude Code，我选择了结合使用。原因在于：

1. Claude Code很可能基于某个Web框架（如FastAPI或Flask）来提供HTTP API，也可能使用httpx或requests来调用Claude的模型API。对于这些通用组件，使用自动插桩（如opentelemetry-instrumentation-fastapi,opentelemetry-instrumentation-httpx）能事半功倍，自动捕获HTTP请求的入站和出站链路。
2. 但是，Claude Code核心的“代码生成逻辑”——比如提示词组装、模型参数设置、响应解析、后处理（代码格式化、安全检查）——这些是独特的业务逻辑。自动插桩无法覆盖。这就需要我们手动创建Span来描绘这些内部细节，这样才能形成有业务意义的完整追踪链路。

因此，依赖项会包括：opentelemetry-sdk,opentelemetry-exporter-otlp-proto-grpc（用于向Collector发送数据），以及若干个opentelemetry-instrumentation-*包。

OpenTelemetry Collector 配置模式Collector的配置是其强大功能的体现。主要配置在otel-collector-config.yaml文件中，核心包括：

• 接收器（Receivers）：配置如何接收数据。我们通常启用otlp接收器，支持gRPC和HTTP两种协议，并指定监听端口。

  receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318

• 处理器（Processors）：定义数据管道。常用的有：
  • batch：将数据批量发送，显著提升后端存储效率和网络利用率。
  • memory_limiter：防止内存溢出，是生产环境的必备安全阀。
  • attributes：可以插入或删除Span/指标上的属性（键值对），比如添加一个deployment.environment=production的标签。
• 导出器（Exporters）：配置数据发往何处。我们需要为追踪和指标分别配置。

  exporters: debug: # 用于本地调试，将数据打印到控制台 verbosity: detailed jaeger: # 将追踪发送到Jaeger endpoint: "jaeger:14250" tls: insecure: true prometheus: # 将指标暴露给Prometheus拉取 endpoint: "0.0.0.0:8889" logging: # 将数据也打印到日志，便于调试 verbosity: detailed

• 服务（Service）：将上述组件连接成数据流水线（Pipeline）。

  service: pipelines: traces: receivers: [otlp] processors: [batch, memory_limiter] exporters: [jaeger, logging] # 可以同时导出到多个地方 metrics: receivers: [otlp] processors: [batch, memory_limiter] exporters: [prometheus, logging]

注意：处理器batch和memory_limiter的顺序很重要。通常memory_limiter应在batch之前，以便在数据进入批处理队列前就进行内存限制检查，避免OOM（内存溢出）。batch处理器中的send_batch_size和timeout参数需要根据实际流量调整，在延迟和吞吐量之间取得平衡。

3. 核心细节：Claude Code的插桩实践

架构搭好了，现在进入最核心的部分：如何对Claude Code的代码进行“手术”，植入OpenTelemetry的探针。我们的目标是既要获取有价值的洞察，又要保持代码的整洁和可维护性。

3.1 环境初始化与自动插桩

首先，需要在Claude Code应用启动的最早期，初始化OpenTelemetry SDK。这通常在主程序入口（如main.py或app.py）中完成。我创建了一个单独的模块otel_setup.py来管理这部分配置，保持主业务代码的纯净。

# otel_setup.py import os from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter from opentelemetry.sdk.resources import Resource, SERVICE_NAME, SERVICE_VERSION def setup_tracing(service_name="claude-code-service", service_version="1.0.0"): """ 初始化OpenTelemetry追踪。 环境变量 OTEL_EXPORTER_OTLP_ENDPOINT 可用于指定Collector地址， 例如：OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 """ # 1. 创建资源标识，这些信息会附加到所有的Span上 resource = Resource.create({ SERVICE_NAME: service_name, SERVICE_VERSION: service_version, "deployment.environment": os.getenv("DEPLOYMENT_ENV", "development"), }) # 2. 设置全局的TracerProvider tracer_provider = TracerProvider(resource=resource) trace.set_tracer_provider(tracer_provider) # 3. 创建OTLP导出器（指向Collector）和批处理处理器 otlp_exporter = OTLPSpanExporter() span_processor = BatchSpanProcessor(otlp_exporter) tracer_provider.add_span_processor(span_processor) # 4. （可选）同时添加一个控制台导出器用于本地调试 if os.getenv("OTEL_DEBUG", "false").lower() == "true": from opentelemetry.sdk.trace.export import ConsoleSpanExporter console_processor = BatchSpanProcessor(ConsoleSpanExporter()) tracer_provider.add_span_processor(console_processor) print(f"OpenTelemetry tracing initialized for service: {service_name}") return tracer_provider

接下来是自动插桩。假设Claude Code使用FastAPI作为Web框架，并使用httpx调用Claude API。我们可以在应用启动时，通过环境变量或代码调用来自动启用这些插桩。

方式一：通过opentelemetry-instrument命令行包装器（推荐用于简单启动）这是最简单的方式，你不需要修改任何代码。只需在启动命令前加上opentelemetry-instrument。

opentelemetry-instrument \ --traces_exporter otlp \ --metrics_exporter otlp \ --service_name claude-code \ python -m uvicorn main:app --host 0.0.0.0 --port 8000

这个命令会自动检测并插桩支持的库。但它的灵活性稍差，对于复杂的手动埋点支持不够。

方式二：在代码中显式初始化自动插桩库（更灵活）我更倾向于这种方式，因为它可以和上面的手动setup_tracing函数更好地集成。

# 在 otel_setup.py 中补充 from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor # ... 其他可能用到的库，如 logging, sqlalchemy 等 def instrument_applications(app=None): """初始化自动插桩""" # 插桩 httpx HTTPXClientInstrumentor().instrument() # 如果传入了FastAPI app实例，则插桩它 if app: FastAPIInstrumentor().instrument_app(app) # 还可以插桩标准库logging，将日志与追踪关联 from opentelemetry.instrumentation.logging import LoggingInstrumentor LoggingInstrumentor().instrument() print("Auto-instrumentation for FastAPI and HTTPX has been enabled.")

然后，在你的FastAPI应用主文件中：

# main.py from fastapi import FastAPI from . import otel_setup app = FastAPI(title="Claude Code API") # 初始化追踪和自动插桩 otel_setup.setup_tracing() otel_setup.instrument_applications(app) # ... 你的路由和业务逻辑

这样一来，所有进入FastAPI的HTTP请求都会自动创建一个根Span，所有通过httpx发起的对外部服务（如Claude API）的调用，都会自动创建子Span，并建立父子关系。分布式追踪的骨架就自动搭建好了。

3.2 手动业务埋点：照亮“黑盒”内部

自动插桩解决了框架层面的追踪，但Claude Code的核心价值——代码生成逻辑——仍然是“黑盒”。我们需要手动埋点来照亮它。关键在于识别核心的业务函数，并在其中创建有意义的Span。

假设Claude Code处理请求的核心函数是generate_code(prompt: str, context: dict)。我们可以这样改造它：

from opentelemetry import trace from opentelemetry.trace import Status, StatusCode tracer = trace.get_tracer(__name__) # 获取这个模块的Tracer def generate_code(prompt: str, context: dict): """ 生成代码的核心函数。 """ # 为整个代码生成过程创建一个Span with tracer.start_as_current_span("generate_code") as span: # 在Span上记录业务相关的属性（Attributes），这些是后续筛选和查询的关键 span.set_attribute("claude.prompt_length", len(prompt)) span.set_attribute("claude.model", context.get("model", "claude-3-opus")) span.set_attribute("claude.temperature", context.get("temperature", 0.7)) try: # 1. 构建最终提示词 with tracer.start_as_current_span("build_final_prompt"): final_prompt = _build_prompt_with_context(prompt, context) span.set_attribute("claude.final_prompt_snippet", final_prompt[:100]) # 记录前100字符 # 2. 调用Claude API with tracer.start_as_current_span("call_claude_api") as api_span: # 注意：由于我们已经插桩了httpx，这个对外调用会自动生成一个子Span。 # 但我们可以在这个手动Span上记录一些额外的业务信息。 response = _call_claude_api(final_prompt, context) api_span.set_attribute("claude.api.response_id", response.id) api_span.set_attribute("claude.api.usage.prompt_tokens", response.usage.prompt_tokens) api_span.set_attribute("claude.api.usage.completion_tokens", response.usage.completion_tokens) # 将自动生成的HTTP Span的Trace ID记录下来，实现更强的关联（如果API返回的话） # 3. 解析和清理响应 with tracer.start_as_current_span("parse_and_clean_response"): generated_code = _extract_code_from_response(response) span.set_attribute("claude.generated_code_length", len(generated_code)) # 4. （可选）后处理：安全检查、格式化 with tracer.start_as_current_span("post_processing"): safe_code = _security_check(generated_code) formatted_code = _format_code(safe_code) # 标记整个Span为成功 span.set_status(Status(StatusCode.OK)) return formatted_code except Exception as e: # 记录异常信息到当前Span span.record_exception(e) # 将Span状态标记为错误 span.set_status(Status(StatusCode.ERROR, str(e))) # 重新抛出异常 raise

手动埋点的核心技巧：

1. Span的命名要有意义：使用动词或动宾结构，如call_claude_api、parse_response，而不是step1、step2。
2. 属性（Attributes）是黄金：记录所有有助于事后分析的上下文信息。例如：提示词长度、模型名称、温度参数、Token用量、生成的代码长度、用户ID（需脱敏）、任务类型等。OpenTelemetry对属性数量没有硬性限制，但应避免记录过大的数据（如完整的提示词）。
3. 合理设置Status：成功时设为OK，失败时设为ERROR并附上错误描述。这能让你在Jaeger等UI中快速过滤出所有失败的请求。
4. 记录异常：使用span.record_exception(e)可以将异常的堆栈信息记录到Span事件中，这对于调试至关重要。
5. 利用上下文传播：start_as_current_span会自动管理Span的上下文，确保在异步或并发环境中，子Span能正确关联到父Span。这是构建正确调用链的关键。

通过这种“自动插桩打骨架，手动埋点填血肉”的方式，我们就能得到一条极其详细的追踪链路。在Jaeger中，你将看到一次/generate的HTTP请求，如何展开为generate_code->build_final_prompt->call_claude_api（其下还有自动生成的HTTP Span）->parse_and_clean_response->post_processing的完整视图，每个步骤的耗时、属性都清晰可见。

4. 指标（Metrics）收集与业务监控

追踪让我们看到了请求的“纵剖面”，而指标（Metrics）则提供了系统的“横截面”视图，比如每秒请求数（RPS）、平均响应时间、错误率、Token消耗速率等。这些指标对于容量规划、告警和健康度评估必不可少。

OpenTelemetry Metrics API 的使用方式与Tracing类似。我们需要在代码中定义和记录指标。针对Claude Code，我定义了以下几个核心业务指标：

# metrics.py from opentelemetry import metrics from opentelemetry.sdk.metrics import MeterProvider from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter # 创建MeterProvider（通常与TracerProvider一起初始化） metric_reader = PeriodicExportingMetricReader( exporter=OTLPMetricExporter(), export_interval_millis=60000 # 每60秒导出一次指标 ) meter_provider = MeterProvider(metric_readers=[metric_reader]) metrics.set_meter_provider(meter_provider) # 获取一个Meter来创建指标 meter = metrics.get_meter("claude.code.service") # 定义指标 # 1. 计数器（Counter）：用于记录只会增加的值，如总请求数、总Token数。 request_counter = meter.create_counter( name="claude.code.requests.total", description="Total number of code generation requests", unit="1" ) prompt_token_counter = meter.create_counter( name="claude.code.tokens.prompt.total", description="Total prompt tokens consumed", unit="1" ) completion_token_counter = meter.create_counter( name="claude.code.tokens.completion.total", description="Total completion tokens consumed", unit="1" ) # 2. 直方图（Histogram）：用于记录值的分布，如响应延迟、生成代码长度。 # 它自动计算平均值、分位数（如p95, p99）等。 generation_duration_histogram = meter.create_histogram( name="claude.code.generation.duration", description="Duration of code generation in milliseconds", unit="ms" ) generated_code_length_histogram = meter.create_histogram( name="claude.code.generated.length", description="Length of generated code in characters", unit="1" ) # 3. 可观察仪表（ObservableGauge）：用于记录当前瞬间的值，如内存使用率、队列长度。 # 需要提供一个回调函数来获取值。 # 例如，监控待处理请求队列长度（假设有个全局变量 `pending_queue`） def get_pending_queue_size(): return len(pending_queue) meter.create_observable_gauge( name="claude.code.queue.pending", callbacks=[get_pending_queue_size], description="Current size of pending request queue", unit="1" )

定义好指标后，在业务代码中记录它们：

# 在 generate_code 函数中 def generate_code(prompt: str, context: dict): start_time = time.time() # 增加请求计数，并添加属性以便按维度聚合（如按模型、环境） request_counter.add(1, attributes={"model": context.get("model"), "env": os.getenv("DEPLOYMENT_ENV")}) try: # ... 原有的生成逻辑 ... response = _call_claude_api(final_prompt, context) # 记录Token消耗 prompt_token_counter.add(response.usage.prompt_tokens) completion_token_counter.add(response.usage.completion_tokens) generated_code = _extract_code_from_response(response) # 记录生成代码长度 generated_code_length_histogram.record(len(generated_code)) return formatted_code finally: # 记录请求耗时 duration_ms = (time.time() - start_time) * 1000 generation_duration_histogram.record(duration_ms)

指标设计的经验：

• 为指标添加有意义的属性（Attributes/Tags）：这是指标分析威力的来源。例如，给request_counter加上model和status_code属性，你就能轻松分析不同模型的请求分布和成功率。给耗时直方图加上model属性，就能对比不同模型的性能。
• 注意基数爆炸：避免使用可能取值无限多的属性，比如user_id或request_id。这会导致指标后端（如Prometheus）产生海量的时间序列，拖垮系统。属性应该用于有意义的、取值有限的维度划分（如model,env,error_type）。
• 单位要明确：unit参数虽然可选，但最好加上，如ms、s、1（无量纲）、By（字节），避免混淆。

配置好Collector的Prometheus导出器后，这些指标就会被Prometheus抓取。你可以在Grafana中创建仪表盘，监控诸如“各模型每分钟请求量”、“平均响应时间与P99延迟”、“Token消耗速率”、“错误率”等关键业务图表，实现对Claude Code服务健康状况和资源消耗的实时掌控。

5. 部署、集成与问题排查实录

将这套可观测性方案部署到实际环境（无论是开发机、测试环境还是生产环境）时，会遇到一些具体问题。下面是我在实践过程中记录的关键步骤和踩过的坑。

5.1 部署OpenTelemetry Collector

Collector是数据枢纽，其部署的稳定性和配置正确性至关重要。

1. 使用Docker Compose（开发/测试环境首选）这是最快捷的方式。创建一个docker-compose.yaml文件，定义Collector、Jaeger、Prometheus和Grafana服务。

version: '3.8' services: # OpenTelemetry Collector otel-collector: image: otel/opentelemetry-collector-contrib:latest command: ["--config=/etc/otel-collector-config.yaml"] volumes: - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml ports: - "4317:4317" # OTLP gRPC 接收端口 - "4318:4318" # OTLP HTTP 接收端口 - "8889:8889" # Prometheus 指标暴露端口 networks: - observability-net # Jaeger (用于追踪) jaeger: image: jaegertracing/all-in-one:latest ports: - "16686:16686" # Jaeger UI - "14250:14250" # Jaeger gRPC接收端口（Collector使用） environment: - COLLECTOR_OTLP_ENABLED=true networks: - observability-net # Prometheus (用于指标) prometheus: image: prom/prometheus:latest volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml ports: - "9090:9090" networks: - observability-net # Grafana (用于可视化) grafana: image: grafana/grafana-enterprise:latest ports: - "3000:3000" environment: - GF_SECURITY_ADMIN_PASSWORD=admin volumes: - grafana-storage:/var/lib/grafana networks: - observability-net volumes: grafana-storage: networks: observability-net: driver: bridge

对应的prometheus.yml需要配置抓取Collector暴露的指标：

scrape_configs: - job_name: 'otel-collector' static_configs: - targets: ['otel-collector:8889']

2. Collector配置的常见陷阱

• 内存限制：一定要配置memory_limiter处理器。生产环境流量不可预测，没有内存限制的Collector可能因突发流量而崩溃。配置示例：

  processors: memory_limiter: check_interval: 1s limit_mib: 512 # 根据容器内存限制调整，例如设置为容器内存的80% spike_limit_mib: 128 batch: send_batch_size: 10000 timeout: 10s

• 数据丢失：在batch处理器中，timeout参数决定了数据在内存中停留的最长时间。如果设置过长（如1小时），在Collector重启时，内存中未发送的数据会丢失。需要根据后端存储的可靠性和你对数据丢失的容忍度来权衡。对于关键业务，可以考虑启用Collector的file_storage扩展，将队列中的数据持久化到磁盘。
• 网络连通性：确保Collector容器能访问Jaeger、Prometheus等后端服务。在Docker Compose中，使用自定义网络（如observability-net）并确保服务名可解析。

5.2 集成到Claude Code应用

环境变量配置为了让Claude Code应用知道将数据发送到哪里，最佳实践是通过环境变量配置。OpenTelemetry SDK会自动读取一系列标准环境变量。

在你的Claude Code应用的Dockerfile或启动脚本中设置：

export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 export OTEL_SERVICE_NAME=claude-code-production export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,service.version=1.2.0 # 启用自动检测（如果使用opentelemetry-instrument命令） export OTEL_PYTHON_LOG_LEVEL=DEBUG # 可选，用于调试

依赖管理在Claude Code的requirements.txt或pyproject.toml中添加必要的依赖：

opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc # 或 opentelemetry-exporter-otlp-proto-http opentelemetry-instrumentation-fastapi opentelemetry-instrumentation-httpx opentelemetry-instrumentation-logging # 根据你使用的其他库添加对应的instrumentation包

5.3 常见问题排查技巧

在实际部署中，你可能会遇到数据看不到、链路不完整等问题。以下是我总结的排查清单：

问题1：Jaeger UI中看不到任何追踪数据。

• 检查链路：
  1. 应用端是否成功发送？在Claude Code应用启动时，设置OTEL_PYTHON_LOG_LEVEL=DEBUG，查看日志中是否有关于Span导出成功或失败的信息。或者，在Collector配置中启用debug或logging导出器，将接收到的数据打印到Collector日志中，这是最直接的验证方式。
  2. Collector是否收到？查看Collector容器的日志。确保其配置的接收器（otlp）端口与应用发送的端口一致（默认gRPC是4317，HTTP是4318）。
  3. Collector是否成功导出？检查Collector日志中是否有连接到Jaeger后端失败的错误（如网络不通、TLS证书问题）。确保Jaeger服务地址（如jaeger:14250）在Collector容器内可访问。
• 快速调试工具：在开发初期，可以在Collector配置中临时添加logging导出器，并设置verbosity: detailed，这样所有经过Collector的数据都会以JSON格式打印到日志，非常直观。

问题2：追踪链路不完整，缺少手动创建的Span。

• 检查Tracer作用域：确保你在函数中使用的tracer是通过trace.get_tracer(__name__)在同一个模块中获取的，或者确保全局TracerProvider已正确设置。
• 检查上下文传播：在异步函数或使用线程池/进程池时，OpenTelemetry的上下文可能不会自动传递。你需要使用opentelemetry.context模块来手动附着（attach）和提取（extract）上下文。对于asyncio，通常SDK能较好处理，但对于concurrent.futures.ThreadPoolExecutor，则需要额外处理。
• 验证Span是否被记录：在手动创建Span的代码块中，添加简单的日志输出，确认代码执行路径确实经过了那里。

问题3：Prometheus抓不到指标。

• 检查指标导出器配置：Collector配置中prometheus导出器的endpoint是否正确（如:8889），并且该端口是否已映射到主机。
• 检查Prometheus配置：prometheus.yml中的targets地址是否正确（如果是Docker Compose，使用服务名otel-collector:8889）。
• 检查指标是否有数据：直接访问Collector暴露的指标端点（如http://localhost:8889/metrics），看是否有claude_code_开头的指标输出。如果没有，说明应用端没有成功记录或导出指标。

问题4：性能开销是否可接受？这是引入任何可观测性方案都必须考虑的问题。OpenTelemetry的设计目标之一就是低开销。

• 采样（Sampling）是关键：在生产环境，对所有请求进行100%追踪（头部采样）可能开销巨大且不必要。通常采用尾部采样或概率采样。可以在Collector端配置probabilistic_sampler处理器，例如只对1%的请求进行全量追踪。对于错误请求，可以配置基于属性的采样，确保所有错误都被记录。

  processors: probabilistic_sampler: sampling_percentage: 1.0 # 1%的采样率

• 批处理（Batching）：确保使用了batch处理器，它能大幅减少网络往返次数。
• 异步导出：OpenTelemetry SDK默认使用异步模式导出数据，不会阻塞主业务线程。

经过这些步骤，你应该能拥有一个运行稳定、数据全面的Claude Code可观测性系统。当再次遇到生成慢或出错时，打开Jaeger，输入相关的服务名或Trace ID，请求的完整旅程和所有细节都将展现在你面前。结合Grafana仪表盘上的实时指标，你不仅能快速定位问题，还能提前发现潜在的性能退化趋势，从被动的“救火”转向主动的“预防”。这套 setup 的价值，会在每一次高效的问题排查和每一次有数据支撑的架构决策中体现出来。