DeepEval OTel 指南confident.trace.*追踪级属性全解与 Confident AI 观测数据契约【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval本篇基于 DeepEval 仓库中 trace-attributes.md 参考文档系统讲解 Confident AI 观测平台Observatory在接收原始 OpenTelemetryOTLP追踪时如何识别整条 Trace级别的元数据全部 15 个confident.trace.*属性的键名、类型与语义、环境environment的解析优先级以及 OTLP 数据类型编码规则。读完后你能够不依赖deepevalPython 包、仅用任意语言的 OpenTelemetry SDK把 AI 应用LLM 应用、Agent、RAG 管线、聊天机器人的完整追踪以正确的数据契约导出到 Confident AI并用仓库内的模板代码做冒烟验证。追踪级属性与 Span 级属性的边界在动手之前必须先分清两级数据的语义边界Trace追踪是一次端到端的完整执行例如一次用户提问触发的 Agent 运行它的各个组成部分是 SpanSpan 级属性confident.span.*及按类型划分的confident.llm.*、confident.agent.*、confident.retriever.*、confident.tool.*描述的是单个 Span——也就是追踪中的某一个组件这些字段单独记录在 span-attributes.md 中Trace 级属性即本篇主题用confident.trace.*前缀描述的是整条追踪。设置方式非常直接把它们作为普通属性写到该追踪中的任意一个 Span上——最自然的位置是根 Span。Confident AI 的导出端会把这些属性聚合aggregate到 Trace 层面你无需在 OTLP 协议之外再做任何 Trace 级封装。这个设计带来两个实用推论其一属性写在哪个 Span 上都合法但集中在根 Span 上可读性最好其二父子嵌套关系不靠属性表达而完全来自原生 OpenTelemetry 的 Span 上下文在tracer.start_as_current_span(...)的with块内开启的子 Span 会自动挂到父 Span 下。confident.trace.*属性全表以下是参考文档定义的完整属性表。所有属性均为可选——只设置对你的应用有意义的字段即可。属性键类型说明confident.trace.namestring人类可读的追踪名称。confident.trace.inputstring追踪输入。透传字段若值本身不是字符串先 JSON 编码。confident.trace.outputstring追踪输出。透传字段若值本身不是字符串先 JSON 编码。confident.trace.user_idstring终端用户 / 客户标识符。confident.trace.thread_idstring对话或会话线程标识符。confident.trace.tagslist of strings分组标签。原生 OTLP 字符串数组或 JSON 数组字符串。confident.trace.metadataJSON string任意键值上下文。必须是 JSON 编码的对象字符串OTLP 没有 map 类型。confident.trace.environmentstring部署环境。默认production解析规则见下文专节。confident.trace.retrieval_contextlist of strings该追踪检索到的文本块 / 文档。原生 OTLP 字符串数组或 JSON 数组字符串。confident.trace.contextlist of strings该追踪的真值ground-truth上下文。原生 OTLP 字符串数组或 JSON 数组字符串。confident.trace.tools_calledlist of strings追踪过程中实际调用的工具。原生 OTLP 列表其中每个元素是一个 JSON 序列化的ToolCall。confident.trace.expected_toolslist of strings本应被调用的工具。原生 OTLP 列表元素为 JSON 序列化的ToolCall字符串。confident.trace.test_case_idstring对某个测试用例test caseID 的引用。confident.trace.turn_idstring多轮对话中的轮次标识。confident.trace.metric_collectionstring一个 Confident AI 指标集合metric collection的名称用于对该追踪执行在线服务端评估。几点使用提示直接来自参考文档的语义confident.trace.input/confident.trace.output是透传passthrough它们不做解析所以如果你的输入输出是对象如消息列表请先json.dumps再写入否则会被序列化器拒绝或丢失结构confident.trace.tags用于在 Observatory 里对追踪做分组筛选user_id/thread_id则是用户维度与多轮会话维度分析的基础字段confident.trace.metric_collection是在线评估server-side evals的入口写上指标集合名后Confident AI 会在服务端对落地的追踪自动跑这套指标无需在应用侧实现评估逻辑test_case_id与turn_id用于把生产追踪与离线评估的测试用例、多轮会话的轮次对应起来属于把线上观测与离线评测打通的关键字段。Environment 解析Resource 优先默认productionconfident.trace.environment接受部署环境字符串常见取值为production、staging、development、testing缺省值为production。它可以在两个位置设置且Resource 属性优先于 Span 属性作为Span 属性confident.trace.environment直接写在某个 Span 上作为 OpenTelemetryResource 属性挂在TracerProvider的Resource上键名同样是confident.trace.environment。这是推荐做法——对整个进程一次性打上环境戳避免每个 Span / 每次埋点重复设置。当两处同时存在且取值冲突时以 Resource 上的值为准。这个优先级设计的意图很清晰环境是部署层面的事实应由进程级配置Resource表达Span 级设置只是细粒度覆盖的退路。用 Python 表达即from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.resources import Resource # 推荐进程级一次性打环境戳Resource 优先于 Span 属性 resource Resource.create({ service.name: my-ai-app, confident.trace.environment: staging, }) provider TracerProvider(resourceresource)OTLP 数据类型规则JSON 字符串 vs 原生数组参考文档明确声明对象用 JSON 字符串、列表用原生 OTLP 数组、ToolCall列表的特殊编码这三条规则对追踪级与 Span 级属性完全一致统一收录在 span-attributes.md 的Data-Type Rules一节。在编码tags、metadata、context、retrieval_context、tools_called或expected_tools之前必须先读那一节。其核心内容如下OpenTelemetry 属性值只允许原始类型或同质的原始类型列表不存在 map / object 属性类型对象 / dictconfident.span.metadata、confident.trace.metadata必须是JSON 编码字符串——即json.dumps(...)的结果而不是 dict 本身字符串列表tags、context、retrieval_context以及 Span 级的available_tools、agent_handoffs可以用原生 OTLP 字符串数组Python 里的list/tupleofstrJSON 数组字符串也可以被接受ToolCall列表tools_called、expected_tools必须是原生 OTLP 列表、每个元素是一个 JSON 序列化的ToolCall字符串——即一个列表装若干 JSON 字符串而不是一个 JSON 字符串装一个列表。这是最容易被写错的形态input/output是透传值若不是字符串先 JSON 编码再设置数字top_k、chunk_size、token 数、成本等以原生 int / float 设置不要写成字符串。对应的最小编码示例import json span.set_attribute(confident.trace.tags, [support, example]) # 原生数组 ✅ span.set_attribute( confident.trace.metadata, json.dumps({app_version: 1.0.0, route: order_status}), # dict 必须 dumps ✅ ) span.set_attribute( confident.trace.tools_called, [json.dumps({name: lookup_order, args: {order_id: 123}})], # 列表元素各自是 JSON 字符串 ✅ )源码级证据ConfidentAttr键注册表与update_current_trace参考文档定义的是原始 OTLP 契约而 DeepEval Python SDK 侧存在与之对应的规范键注册表可以拿来交叉印证键名的拼写与集合。ConfidentAttr位于 attributes.py集中定义了所有confident.*规范键其中追踪级字段第 54–87 行与参考文档的 15 个属性一一对应TRACE_NAME、TRACE_INPUT、TRACE_OUTPUT、TRACE_USER_ID、TRACE_THREAD_ID、TRACE_TAGS、TRACE_METADATA、TRACE_ENVIRONMENT、TRACE_RETRIEVAL_CONTEXT、TRACE_CONTEXT、TRACE_TOOLS_CALLED、TRACE_EXPECTED_TOOLS、TRACE_TEST_CASE_ID、TRACE_TURN_ID、TRACE_METRIC_COLLECTION。从源码结构看该注册表还额外包含了TRACE_TEST_RUN_ID以及一组confident.trace.llm_test_case.*前缀键input / context / expected_output / actual_output / retrieval_context / tools_called / expected_tools这些是 SDK 把LLMTestCase字段落到追踪上时使用的内部键不在原始 OTLP 参考文档的对外契约表里。该模块的文档字符串也解释了为什么键名必须精确集成方把键写到 OTel Span 上ConfidentSpanExporter再读回来因此拼写错误是隐性的——错误会落在一个没人查看的键上对应字段就会无声地从追踪中消失。这正是参考文档反复强调键名一字不差的原因。SDK 的编程接口侧update_current_trace位于 context.py暴露了与上述属性几乎同名的参数name、tags、metadata、thread_id、user_id、input、output、retrieval_context、context、expected_output、tools_called、expected_tools、test_case、test_case_id、turn_id、metric_collection等并支持直接传入一个test_case参数一次性把LLMTestCase的 input、actual_output、expected_output、retrieval_context、context、tools_called、expected_tools 全部写入当前追踪上下文。可以看到参考文档中的每个追踪级属性都在 SDK API 中有对应入口两者是同一契约的OTLP 原始形态与Python 便捷形态。实战用官方模板发出一条带confident.trace.*的示例 Traceconfident_otel_setup.py 模板提供了可直接运行的最小示例一个 agent 根 Span 包裹一个子 LLM Span并在根 Span 上设置追踪级属性。模板中追踪级属性的写法第 75–84、107 行恰好覆盖了前文所有编码规则的典型形态with tracer.start_as_current_span(support-agent) as root: # 追踪级属性confident.trace.*可写在任意 Span 上根 Span 最自然。 root.set_attribute(confident.trace.name, support-chat) root.set_attribute(confident.trace.input, Where is my order?) # 字符串列表 → 原生 OTLP 数组 root.set_attribute(confident.trace.tags, [support, example]) # dict / metadata → 必须 JSON 编码为字符串OTLP 没有 map 类型 root.set_attribute( confident.trace.metadata, json.dumps({app_version: 1.0.0, route: order_status}), ) # ...子 LLM Span 见模板第 87–104 行 root.set_attribute(confident.trace.output, answer)运行前需要安装依赖pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http导出CONFIDENT_API_KEY环境变量不要硬编码在源码里直接python confident_otel_setup.py——脚本会自动按 API key 的地区前缀选择端点confident_eu_...走https://eu.otel.confident-ai.com其余走https://otel.confident-ai.com以OTLPSpanExporter指向endpoint/v1/traces并携带x-confident-api-key头完成导出退出前调用trace.get_tracer_provider().shutdown()冲刷批处理器BatchSpanProcessor。端点、鉴权头与仅 OTLP/HTTP、拒绝 gRPC等网络侧细节完整说明见同目录的 endpoint-and-exporter.md整体接入流程与只导出 AI Span的隔离原则见 SKILL.md。关键要点回顾两级契约confident.trace.*描述整条追踪、confident.span.*描述单个组件追踪级属性写在任意 Span推荐根 Span上由 Confident AI 端聚合到 Trace。15 个属性全部可选name / input / output / user_id / thread_id / tags / metadata / environment / retrieval_context / context / tools_called / expected_tools / test_case_id / turn_id / metric_collection只设置有意义的字段。Environment 解析默认productionSpan 属性与 Resource 属性两处可设Resource 优先推荐进程级 Resource 一次性打戳。数据类型规则与 Span 级完全一致dict 一律json.dumps字符串列表用原生 OTLP 数组JSON 数组字符串亦可tools_called/expected_tools是元素各自为 JSON 字符串的列表数字用原生 int / float——详见 span-attributes.md。键名是硬契约拼写错误不会报错只会让字段静默消失对照 ConfidentAttr 注册表可校验键名用 confident_otel_setup.py 模板可端到端冒烟验证。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考