用途
llmobs-testing 是 dd-trace-js 中面向 LLMObs 插件测试的技能说明，用于在编写、修改或调试 LLMObs 插件测试时提供统一策略。它帮助判断每类被埋点的接口应使用何种响应来源和测试方式。
分类与响应策略
文档将操作分为三类：
- LLM 客户端/多提供方：直接访问提供方 HTTP，或通过 openai、anthropic、genai、ai、langchain 等包访问，使用 VCR 录像或预设 fetch。
- 编排：承载工作流或图状态但不自行调用提供方（如 langgraph），不使用 VCR，节点以普通返回值驱动。
- 基础设施：实现协议或服务器（如 modelcontextprotocol-sdk），使用 SDK 自身的内存传输运行服务端与客户端。
部分场景由测试规范自带响应：google-cloud-vertexai 每个测试替换 global.fetch 并打桩 Google 认证；openai-agents 等向客户端传入 fetch 选项。
核心测试概念
测试结构使用 useLlmObs() 初始化环境、getEvents() 获取捕获的 span 事件、assertLlmObsSpanEvent() 校验 span 结构。基本流程为：初始化环境 → 调用被埋点方法 → 获取事件 → 校验结构。
VCR 录像：提供方流量录制一次后回放，客户端访问 http://127.0.0.1:9126/vcr/{provider}。该代理来自测试代理容器，需先执行 docker compose up -d testagent，否则出现 ECONNREFUSED 127.0.0.1:9126。录像存放在 packages/dd-trace/test/llmobs/cassettes/{provider}/ 共享目录。
断言匹配器：MOCK_STRING（任意字符串，含空串）、MOCK_NOT_NULLISH（非 null/undefined）、MOCK_NUMBER（任意数字）、MOCK_OBJECT（typeof 为 object，含 null）。必填字段为 span、spanKind、name、tags；缺少 tags 会抛 TypeError。可选字段省略即断言其不存在，traceId 例外，默认使用 MOCK_STRING。
span 类型与字段
SPAN_KINDS 定义于 packages/dd-trace/src/llmobs/constants/tags.js，包含 llm、workflow、agent、task、tool、embedding、retrieval；插件可直接设置类型，因此也存在 step 等列表外类型。llm 携带 modelName、modelProvider、输入输出消息及 token 指标；embedding 携带 modelName、modelProvider、inputDocuments、outputValue；retrieval 携带 inputValue、outputDocuments；workflow/agent/task/step/tool 只携带各自的输入输出值，不携带模型字段或 token 指标。
文件组织与错误处理
测试文件位于 packages/dd-trace/test/llmobs/plugins/{integration}/index.spec.js；SDK 跨大版本形态变化时按版本拆分文件，如 openaiv3.spec.js、openaiv4.spec.js。标准导入包括 useLlmObs、assertLlmObsSpanEvent 及各 MOCK 匹配器。错误场景中 span 仍会提交；传入 error: {} 表示期望 status 为 'error'，可通过 apmSpans[0].meta['error.message'] 断言具体错误信息。
限制
该技能面向 dd-trace-js 仓库内部的 LLMObs 插件测试，具体命令、模板和矩阵需参阅其 references 目录下的文档；本文档未提供独立安装方式、收费信息或对外服务说明。