1. 为什么你的 AI 调度官一慢，日志就彻底失声
先说一个我踩过的真实场景。用户问“帮我查下明天杭州天气，顺便推荐两件适合穿的衣服”，系统转了 28 秒，最后回一句“抱歉，我暂时无法回答”。你打开日志，只有一行Error: Context Deadline Exceeded。这 28 秒里，AI 调度官到底是在反复调用天气 API，还是卡在向量检索，还是 LLM 自己陷入了循环推理？完全不知道。这就是 AI 调度官可观测性缺失的典型症状——你有一个会思考的调度中枢，却没有任何仪表盘。
传统微服务时代，我们靠 TraceID 串起一次 HTTP 请求，链路清晰。但 Agentic AI 不一样：AI 调度官（Dispatcher）会动态规划、会调用多个子 Agent、会在 LLM 和工具之间来回跳转。它的执行路径是非确定性的，今天走 A 分支，明天同样输入可能走 B 分支。日志（Logging）只能记录离散事件，无法还原“思考链”；而单纯的 Metrics 又看不到单次请求内部的因果。你需要的是OpenTelemetry 的 Trace + Metrics + Logs 三件套，把 AI 调度官的每一次“思考”和“行动”都变成可回放的 Span。
这篇文章面向正在构建多智能体协作系统的工程师。我会交付三样能直接复制的东西：一份可运行的 OpenTelemetry Collector 配置、一段 Python 侧的 OTel 埋点代码（覆盖 Plan→Act→Observe 生命周期）、以及通过 TaoToken 统一 Key 接入模型调用的完整步骤。目标很明确：让你在 Jaeger 里看到 AI 调度官的完整调用链，在 Grafana 里看到 Token 消耗曲线，从此拒绝黑盒。
适合谁？如果你正在用 LangChain、AutoGen 或自研调度框架，并且已经被“为什么这次慢了”“Token 花哪了”折磨过，这篇就是写给你的。下面从架构设计开始，一步步落地。
2. TaoToken 统一 Key 接入：让 AI 调度官的模型调用可被追踪
在讲埋点之前，必须先解决一个前置问题：AI 调度官调用的 LLM 请求，怎么和 Trace 关联起来？如果模型调用走的是散落各处的 Key，你既没法统一观测，也没法在 Span 里标注是哪个模型、消耗了多少 Token。我的做法是用 TaoToken 作为统一的模型接入层，所有 Agent 的 LLM 调用都走同一个 Base URL 和 Key，这样 Trace 里的llm.model、llm.usage.*属性才有统一来源。
TaoToken 在这里扮演的是“模型网关”角色，它兼容 OpenAI 风格的接口，所以你的 OTel 埋点代码不需要为不同模型写适配。先拿到 Key：访问https://taotoken.net/api-keys（带 UTM 的完整链接是https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite），创建一个新 Key。注意，这个 Key 只用于服务端调用，不要写进前端代码。
拿到 Key 后，你的 AI 调度官初始化 LLM 客户端时，Base URL 指向https://taotoken.net/api，Model ID 按你实际使用的模型填，比如gpt-4o或claude-3-5-sonnet。这里有个关键点：Base URL、Key、Model ID 三件套必须同时出现在配置里，缺一个都会导致 401 或模型找不到。我见过有人只改了 Base URL 忘了换 Key，结果请求打到旧网关，Trace 里全是 401，排查半天。
为什么要在可观测性文章里先讲接入？因为 Trace 的价值在于“端到端”。如果模型调用这一段是断的，你在 Jaeger 里只能看到dispatch_request这个 Span，看不到它内部 LLM 推理的耗时和 Token。把 TaoToken 作为统一入口后，你可以在 OTel 的 Span 里放心地记录llm.usage.prompt_tokens和llm.usage.completion_tokens，这些数据会随 Trace 一起上报，最终在 Grafana 里聚合成成本看板。
配置示例（Python 环境变量方式，避免硬编码）：
export TAOTOKEN_API_KEY="sk-你的Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api" export TAOTOKEN_MODEL_ID="gpt-4o"然后在代码里读取：
import os from openai import OpenAI client = OpenAI( api_key=os.environ["TAOTOKEN_API_KEY"], base_url=os.environ["TAOTOKEN_BASE_URL"], )这样你的 AI 调度官无论调用哪个子 Agent，模型请求都经过同一个可观测入口。下一步，我们把这个客户端包进 OTel 的 Span 里。
3. 可复制配置：Collector + SDK 埋点 + Jaeger 全链路
这一节是核心，直接给可复制的配置和代码。整体数据流是：Python Agent 用 OTel SDK 产生 Trace/Metrics → OTLP 协议发给 Collector → Collector 分发到 Jaeger（Trace）和 Prometheus（Metrics）。
3.1 OpenTelemetry Collector 配置
新建otel-collector-config.yaml，这是经过我实测能跑通的版本：
receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: timeout: 5s send_batch_size: 512 memory_limiter: check_interval: 1s limit_mib: 512 exporters: otlp/jaeger: endpoint: jaeger:4317 tls: insecure: true prometheus: endpoint: "0.0.0.0:8889" namespace: ai_agent service: pipelines: traces: receivers: [otlp] processors: [memory_limiter, batch] exporters: [otlp/jaeger] metrics: receivers: [otlp] processors: [memory_limiter, batch] exporters: [prometheus]用 Docker Compose 把 Collector 和 Jaeger 拉起来：
version: "3.8" services: otel-collector: image: otel/opentelemetry-collector-contrib:0.100.0 command: ["--config=/etc/otel-collector-config.yaml"] volumes: - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml ports: - "4317:4317" - "4318:4318" - "8889:8889" jaeger: image: jaegertracing/all-in-one:1.57 ports: - "16686:16686" - "4317" environment: - COLLECTOR_OTLP_ENABLED=true启动后，Jaeger UI 在http://localhost:16686，Collector 的 Prometheus 指标在http://localhost:8889/metrics。
3.2 Python SDK 埋点：覆盖 Plan→Act→Observe
安装依赖：
pip install opentelemetry-api opentelemetry-sdk \ opentelemetry-exporter-otlp \ opentelemetry-instrumentation-requests初始化 Tracer 和 Meter：
from opentelemetry import trace, metrics from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.sdk.metrics import MeterProvider from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter trace_provider = TracerProvider() trace_provider.add_span_processor( BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4317", insecure=True)) ) trace.set_tracer_provider(trace_provider) metric_reader = PeriodicExportingMetricReader( OTLPMetricExporter(endpoint="http://localhost:4317", insecure=True), export_interval_millis=5000, ) metrics.set_meter_provider(MeterProvider(metric_readers=[metric_reader])) tracer = trace.get_tracer("ai-agent-commander") meter = metrics.get_meter("ai-agent-commander") token_counter = meter.create_counter( "ai_token_usage", description="Total tokens used by agents", unit="1" )现在写 AI 调度官的核心逻辑，把 LLM 调用包进 Span：
class Commander: def __init__(self, client): self.client = client def think_and_plan(self, query: str): with tracer.start_as_current_span("commander_thinking") as span: span.set_attribute("user.query", query) plan = self._generate_plan(query) span.set_attribute("agent.plan", str(plan)) self._execute_tools(plan) def _generate_plan(self, query): with tracer.start_as_current_span("llm_inference") as span: resp = self.client.chat.completions.create( model=os.environ["TAOTOKEN_MODEL_ID"], messages=[{"role": "user", "content": query}], ) span.set_attribute("llm.model", os.environ["TAOTOKEN_MODEL_ID"]) span.set_attribute("llm.usage.prompt_tokens", resp.usage.prompt_tokens) span.set_attribute("llm.usage.completion_tokens", resp.usage.completion_tokens) token_counter.add(resp.usage.prompt_tokens, {"type": "input"}) token_counter.add(resp.usage.completion_tokens, {"type": "output"}) return resp.choices[0].message.content3.3 跨 Agent 的 Context 传播
当调度官把任务分发给子 Agent 时，必须把 Trace 上下文注入 HTTP Header，否则链路会断：
from opentelemetry.propagate import inject import requests def dispatch_task(payload, target_url): with tracer.start_as_current_span("dispatch_request") as span: headers = {} inject(headers) span.set_attribute("peer.service", target_url) return requests.post(target_url, json=payload, headers=headers)子 Agent 侧用extract还原上下文，这样 Jaeger 里就能看到完整的父子 Span 关系。
4. 验证请求：确认链路数据真的上报成功了
配置写完不代表数据通了。我习惯用三步验证法，确保 Trace 和 Metrics 都进了后端。
第一步，发一个测试请求。启动你的 Agent 服务，调用一次think_and_plan("你好")。如果代码没报错，说明 SDK 初始化正常。
第二步，看 Collector 日志。执行docker logs -f otel-collector，正常情况你会看到类似TracesExporter和MetricsExporter的发送记录。如果日志里出现connection refused，说明 Collector 没连上 Jaeger，检查otel-collector-config.yaml里的 endpoint 是否写成了jaeger:4317（Docker 网络内用服务名）。
第三步，打开 Jaeger UI。在http://localhost:16686的 Service 下拉框里选择ai-agent-commander，点击 Find Traces。你应该能看到一条名为commander_thinking的 Trace，展开后结构是：
commander_thinking (5.2s) ├── llm_inference (3.1s) attributes: llm.model=gpt-4o, llm.usage.prompt_tokens=128 └── dispatch_request (2.0s) └── database_agent_query (1.8s)如果只看到commander_thinking而没有子 Span，说明start_as_current_span的嵌套有问题，检查是否在异步代码里丢了上下文。如果 Jaeger 里完全没数据，先确认 Collector 的 4317 端口是否被占用，再检查 Python 端 exporter 的 endpoint 是不是http://localhost:4317（本地跑）或http://otel-collector:4317（容器内跑）。
Metrics 的验证更直接：访问http://localhost:8889/metrics，搜索ai_agent_ai_token_usage，如果能看到type="input"和type="output"的计数，说明 Token 指标已经上报。这一步成功后，你就可以把 Prometheus 数据源接入 Grafana，画出 Token 燃烧速率曲线。
5. 本篇常见错排查：401、local proxy failed、reading choices
落地过程中，报错集中在几个地方。我把真实遇到的错误和排查路径列出来，你对照着看。
错误一：401 Unauthorized。这个最常见，通常是 TaoToken 的 Key 没配对。检查三件套：Base URL 是不是https://taotoken.net/api，Key 是不是从https://taotoken.net/api-keys新创建的，Model ID 是不是当前 Key 有权限的模型。如果 Key 复制时带了空格，也会 401。建议用echo $TAOTOKEN_API_KEY | wc -c确认长度。
错误二：local proxy failed。这个报错说明你的请求根本没发出去，卡在本地网络层。先确认https://taotoken.net/api是否可达，用curl -I https://taotoken.net/api测试。如果公司网络有出口限制，联系运维放行。注意，这里不要配置任何本地代理工具，直接走正常网络即可。
错误三：reading choices 相关报错。比如AttributeError: 'NoneType' object has no attribute 'choices'。这通常是因为 LLM 返回体结构和你预期不一致，或者请求超时后返回了空。在 OTel 埋点里，建议在llm_inferenceSpan 中加一个try/except，把异常记录为 Span Event：
with tracer.start_as_current_span("llm_inference") as span: try: resp = self.client.chat.completions.create(...) span.set_attribute("llm.status", "success") except Exception as e: span.set_attribute("llm.status", "error") span.record_exception(e) raise这样在 Jaeger 里能直接看到错误堆栈，不用翻日志。
错误四：OAuth 相关报错。如果你用的是需要 OAuth 的模型服务，注意 TaoToken 的 Key 是 API Key 模式，不需要走 OAuth 流程。如果代码里混入了 OAuth 逻辑，先移除，统一用 API Key。
错误五：Trace 断链。表现为子 Agent 的 Span 没有挂在父 Span 下。检查inject和extract是否成对出现，以及 HTTP Header 是否被中间件过滤。有些网关会丢弃traceparent头，需要在网关配置里放行。
6. 从 Trace 到 Metrics：把可观测性变成成本控制力
链路通了之后，真正的价值在于用数据做决策。我在实际项目里发现，80% 的 Token 消耗集中在无效的上下文重复提交上。通过 OTel 的 Metrics，你可以把ai_token_usage按model和type维度聚合，在 Grafana 里画出“单任务成本”曲线。
具体做法：在 Collector 的 Prometheus exporter 里已经带了namespace: ai_agent，所以指标名是ai_agent_ai_token_usage_total。在 Grafana 里建一个 Panel，查询sum(rate(ai_agent_ai_token_usage_total[5m])) by (type)，就能看到输入和输出 Token 的实时消耗速率。再建一个 Panel 查sum(ai_agent_ai_token_usage_total) by (model)，看模型分布。
更进一步，你可以把 Trace 里的agent.plan属性导出，分析哪些规划路径导致了最多的工具调用。如果发现某个子 Agent 的database_agent_querySpan 平均耗时 1.8 秒，而它只是查一个缓存就能拿到的数据，那就该优化了。
对于长期运行的 Agent 服务，建议把 Coding Plan 纳入日常：访问https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite了解适合持续编码场景的接入方式。如果你只是想先验证模型对话是否正常，可以用https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite快速测试。接入文档在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite，里面有完整的参数说明。
最后说一个实用技巧：在 Jaeger 里给commander_thinkingSpan 加一个sampling.priority标签，对慢请求（>5s）强制采样，这样你既能控制存储成本，又不会漏掉关键故障。可观测性不是装完就完事，而是持续调优的过程。当你能在 Jaeger 里一眼看出“这次慢是因为 LLM 推理占了 3 秒，而不是数据库”，你就真正掌控了 AI 调度官。
