deepeval-tracing

DeepEval 跟踪

使用此技能为 AI 应用（LLM 应用、Agent、RAG 流水线或聊天机器人）添加 DeepEval 原生跟踪，让其执行过程能够在 Confident AI 的 Observatory 中按 span 逐一查看。工作内容包括：存在受支持的集成时选择该集成，否则回退到手动使用 @observe，为每个 span 设置有意义的类型，并添加标签和元数据。

此技能仅负责生成格式正确的跟踪记录。添加评估指标和运行评估属于 deepeval 技能的工作。

范围：仅限 AI 应用

仅为系统中的 AI 部分添加跟踪——Agent 循环和规划、LLM 调用、检索 / 向量搜索以及工具调用。span 类型（llm、 retriever、tool、agent）用于描述 AI 组件。不要跟踪非 AI 软件（Web 服务器、CRUD 后端、基础设施）。如果目标系统没有 LLM、Agent、检索或工具调用组件，则此技能不适用。

何时使用此技能、deepeval 技能和 deepeval-otel 技能

• 此技能（deepeval-tracing） — 使用 DeepEval SDK （@observe、框架集成）为应用添加跟踪，让跟踪记录发送到 Confident AI。
• deepeval 技能 — 构建 pytest 评估套件：数据集、指标、跟踪评估、 deepeval test run、迭代。它会针对由此技能添加跟踪的应用运行评估。
• deepeval-otel 技能 — 使用供应商中立的 OpenTelemetry SDK，而非 DeepEval SDK 添加跟踪（原始 OTLP，包括非 Python 应用）。

这三者可以互相配合。如果不确定该使用此技能还是 deepeval-otel： 当应用使用 Python 且你希望使用 DeepEval SDK 时，请使用此技能；需要原始 OpenTelemetry，或应用不是 Python 编写时，请使用 deepeval-otel。

前提条件

• 使用 Python 编写的 AI 应用，并已运行 pip install deepeval。
• 要将跟踪记录发送到 Confident AI：运行 deepeval login，或设置 CONFIDENT_API_KEY 环境变量（CI 和非交互式运行时优先使用）。

工作流

1. 确认目标是 AI 应用（包含 LLM 调用、Agent 循环、 检索或工具调用）。如果以上皆无，请停止——此技能不适用。
2. 检测所使用的框架、模型提供商、Agent SDK 和向量数据库。
3. 阅读 references/integrations.md 以及检测到的组件对应的确切集成文档。优先选择原生集成，而非手动添加跟踪。
4. 如果没有合适的原生集成，则使用 @observe 手动添加跟踪。阅读 references/tracing.md。
5. 为每个 span 设置有意义的 type（llm、retriever、tool、agent），并记录输入 / 输出。
6. 在有助于诊断故障模式时，添加跟踪级标签和元数据。 切勿跟踪机密、凭据或未经处理的敏感数据。
7. 确认已运行 deepeval login 或设置 CONFIDENT_API_KEY，然后确认跟踪记录已显示在 Confident AI Observatory 中。

核心原则

1. 仅为 AI 组件添加跟踪——使用 llm、retriever、tool、agent span。 切勿跟踪非 AI 软件。
2. 优先使用受支持的集成，而非手动使用 @observe。手动跟踪是对不受支持的框架和应用自有包装器边界的备用方案。
3. 编写跟踪代码前，先阅读确切的集成文档。
4. 为 span 设置有意义的类型；除非有充分理由覆盖名称，否则使用函数名作为默认名称。
5. 切勿跟踪机密、凭据、API 密钥或未经处理的敏感用户数据。
6. 此技能的范围是生成跟踪记录。添加指标和运行评估属于 deepeval 技能的工作；原始 OpenTelemetry 导出属于 deepeval-otel 的工作。

参考资料

主题	文件
手动添加跟踪：@observe、span 类型、标签、元数据	references/tracing.md
集成选择规则以及框架 / 模型 / 向量数据库文档索引	references/integrations.md