confident-otel

用途\nconfident-otel 用于给 AI 应用（LLM 应用、智能体、RAG 流水线、聊天机器人）接入原始 OpenTelemetry，使其追踪数据上报到 Confident AI。技能不需要 confident-trace 包，核心工作只有两步：将 OTLP/HTTP 追踪导出器指向正确的 Confident AI OTLP 端点，并设置 Confident AI 从每个 span 读取的 confident.* 属性。\n\n适用范围\n仅对 AI 组件埋点与导出：智能体循环与规划、LLM 调用、检索/向量搜索、工具调用。不要给 Web 服务器、CRUD 后端、数据库层、基础设施或非 AI span 添加 confident.* 属性。如果目标应用没有 LLM、智能体、检索或工具调用组件，此技能不适用。\n\n与其他技能的区别\nconfident-otel 提供厂商中立的 OTLP 导出与原始 confident.* 属性，不使用 confident-trace 包。confident-tracing 技能则提供 Python 或 TypeScript 的自动集成与自定义 SDK span。\n\n前提条件\n需要项目级 CONFIDENT_API_KEY；需要应用所用语言的 OpenTelemetry SDK；Python 场景需要 opentelemetry-sdk 与 opentelemetry-exporter-otlp-proto-http。直连 Confident AI Cloud 使用 OTLP/HTTP，不使用 gRPC。\n\n工作方式\n将 OTLP/HTTP 追踪导出器指向 Confident AI，并携带 x-confident-api-key 请求头。Confident AI 从 span 中读取 confident.* 属性。父子嵌套、trace ID、采样、状态、链接与上下文传播仍由原生 OpenTelemetry 负责。\n\n使用流程\n1. 确认目标是 AI 应用，然后检查是否已有 TracerProvider、导出器、Collector 或 APM 流水线。\n2. 根据 API key 的区域前缀选择直连 Cloud 端点（参见 references/endpoint-and-exporter.md）。\n3. 配置或重定向一个带 x-confident-api-key 头的 OTLP/HTTP 导出器；Python 可从 templates/confident_otel_setup.py 起步。\n4. 如果进程还会产生无关的 OpenTelemetry span，隔离 Confident AI 导出，仅让 AI span 到达 Confident AI。\n5. 在 span 上设置 confident.span.* 字段，在整个 trace 上设置 confident.trace.* 字段（参见 references/span-attributes.md 与 references/trace-attributes.md）。\n6. 对象和元数据用 JSON 编码；字符串列表使用原生的同质基本类型数组。\n7. 如果应用已产生 gen_ai.* 语义约定属性，先阅读 references/gen-ai-fallbacks.md 再添加冗余字段。\n8. 在活动工作完成后执行 flush，并在 Confident AI 中验证追踪层级。\n\n核心原则\n只对 AI 组件埋点与导出；优先重定向既有导出器而非新增重复流水线；confident.* 键与语言无关；直连 Confident AI Cloud 始终使用 OTLP/HTTP，Collector 在其面向应用的一侧可使用其他协议；已知时显式设置 confident.span.type，仅在回退时使用 gen_ai.* 推断；绝不硬编码 API key 或记录密钥及未经批准的敏感内容；保留原生 OpenTelemetry 的 trace ID、父子关系、采样、状态、资源、链接与传播。\n\n参考文件\nreferences/endpoint-and-exporter.md：端点、区域选择、认证、导出器接线与过滤。references/trace-attributes.md：trace 级 confident.trace.* 属性。references/span-attributes.md：span 级 confident.span.* 属性与数据类型规则。references/gen-ai-fallbacks.md：标准 OpenTelemetry gen_ai.* 回退行为。\n\n模板\ntemplates/confident_otel_setup.py：最小 Python OTLP 导出器配置与示例 trace。