# OpenTelemetry Agent 追踪：把一次任务的工具调用串成同一条 trace

OpenTelemetry Node SDK实跑五个span和HTTP traceparent传播，父子关系、真实耗时与错误状态均回读。

## 环境

- Node.js 24+；进入 reference 后 npm install。依赖为锁定的直接版本，首次安装需要网络。

## 启动

~~~sh
cd reference
npm install
node verify.mjs
# 运行后查看原生结果阅读器（读取records.json）
python3 -m http.server 8787
# 打开 http://127.0.0.1:8787/report.html
~~~

## 七步操作

1. 准备三类工具

输入是一条原创本机任务，依次调用快工具、HTTP远端练习工具和故意失败工具。HTTP 服务仅监听回环地址，不接真实业务请求。

2. 创建任务根Span

使用 NodeTracerProvider 和 SimpleSpanProcessor，先建立 agent.task 根 span。每个工具用 startActiveSpan 创建子 span，确保异步调用期间保留活动上下文。

3. 传播HTTP上下文

发起 localhost HTTP 请求前用 propagation.inject 写入 W3C traceparent，服务端 extract 后创建 remote.lookup。只复制 request_id 字符串并不能代替真正的分布式父子关系。

4. 记录真实耗时

查看原生导出的 durationMs，慢步骤需要真实等待和请求返回后再结束 span。图中的条形长度来自实际 duration，不是预先写好的示意耗时。

5. 保留错误关联

故意失败的工具记录 exception 事件并设置 ERROR。它的 traceId 仍应等于根任务；失败不能丢失上下文而变成另一条无关联请求。

6. 查看父子关系

核对 remote.lookup 的 parentSpanId 指向 tool.remote，三个工具指向 agent.task。本题共五个实际 span，拓扑和状态都从导出器回读。

7. 导出最小字段

结果保存在 records.json，可用阅读器查看时间条。练习只采集声明的虚构 task.id 和路由，没有导出真实密钥；这不是 Langfuse 云平台截图，也未运行实际 LLM 调用。

## 目录身份

- starter：待完成的任务接口与原创输入，TODO不是已完成实现。
- reference：作者原生完成参考和实际产物。records.json/browser-result.json为本地实测记录，不是AI助手回复。
- TASK.md：可交给相应AI助手的原始任务合同。该助手账号生成会话未运行。

## 依赖与许可

原创教学代码以MIT许可提供。第三方项目、模型及浏览器遵循其自身许可。第三方依赖由本地安装获取，不包含node_modules、模型权重、WASM运行时、数据库、缓存或凭据。

## 官方依据

- https://opentelemetry.io/docs/languages/js/instrumentation/