OpenTelemetry、采集器、SDK 与参考边界

OTel 适合统一跨语言链路，但 LangSmith 不是被动保存任意 span：它会把属性映射成 run，并等待父节点完成树结构。接收端返回 200 只表示已接收，不保证 trace 已完成物化。

一、三种 tracing mode

版本节点：

• LangSmith OTel ingestion 支持从 Python 0.3.18 起。
• 文档推荐 Python 0.4.25+。
• hybrid 要求 0.4.1+。
• 这些是文档快照，依赖落地时仍应查 package release。

二、属性映射

LangSmith 能识别：

• <code>langsmith.*</code> 专用属性。
• OpenTelemetry GenAI semantic conventions。
• TraceLoop、OpenInference、LLM、retriever/tool 等常见 convention。
• span events 中的消息/内容。

映射目标包括 run name/type、inputs/outputs、model/provider、usage、metadata、tags、parent 和 project。

最佳实践：

• 优先标准 GenAI 字段，LangSmith 专用字段只补标准无法表达的语义。
• 自定义 resource attributes 会进入 <code>otel.resource.*</code> metadata。
• 同一信息不要同时在多个 convention 重复上报，否则 token/messages 可能重复。
• 自定义高基数 resource 字段会放大存储和查询成本。

三、父子到达顺序

OTel 异步批量可能让 child 先于 parent 到达。LangSmith 会缓冲孤儿：

• parent 后到时正确嵌套。
• parent 永远不到时，child 在缓冲过期后静默丢弃。
• 自托管相关配置 <code>REDIS_RUNS_EXPIRY_SECONDS</code> 默认约 12 小时。

因此：

• exporter 200 不代表 UI 已出现。
• 同时监控 accepted、materialized、orphan expired。
• 所有服务的 trace ID/parent span ID 和采样决策必须一致。
• parent 被 head sampling 丢弃而 child 保留，是典型孤儿来源。

四、连接已有 LangSmith trace

可把原生 OTel span 接到已存在的 LangSmith SDK run：

• 传播完整 UUID 形式的 LangSmith trace/run 标识和 dotted order。
• OTel 原生 16/8-byte trace/span ID 与 LangSmith UUID 不是同一表示，不能简单字符串替换。
• 跨进程要同时传播业务认证和 trace context，但两者凭据必须隔离。

如果无法可靠关联，创建新 trace 并写 correlation metadata 比伪造 parent 更安全。

五、Collector 拓扑

典型：

application → OTel Collector ├─ LangSmith OTLP ├─ Tempo └─ 其他 APM

Collector 应配置：

• memory limiter、batch、retry、queued retry。
• resource/attribute processor。
• TLS、API key secret 注入。
• 多 exporter fan-out 的独立失败策略。
• 自身 metrics/logs 与 dead-letter 观测。

不要在 debug exporter 打印生产 prompt。

六、LangSmith Collector 的边界

“LangSmith Collector”页面主要讲 LangSmith 平台基础设施 telemetry：

• Kubernetes 部署。
• sidecar/平台日志。
• Gateway metrics/traces。
• Prometheus RBAC。
• batch、memory limiter、k8s attributes。

它不是“所有应用 tracing 的唯一安装说明”。应用侧仍应按 OTel integration 配置 exporter 和 GenAI attributes。

七、Observability Stack

自托管观测栈示例基于 LGTM：

• Loki：日志。
• Grafana：可视化。
• Tempo：trace。
• Mimir/Prometheus：metrics。
• OTel Collector：接收/处理/转发。

文档明确该简化栈适合非生产、每天几十 GB 量级的起步环境。旧 Helm chart 已 deprecated。生产应独立评估：

• 多副本、持久化、备份恢复。
• retention 与对象存储。
• tenant 隔离、认证、TLS。
• 容量、compaction、查询并发。
• 升级与灾备。

八、SDK 与 API Reference

Smith API Reference 是 REST/OpenAPI 的字段和 endpoint 权威来源，认证头通常为 <code>X-Api-Key</code>；一个 key 多 workspace 时还要 workspace/tenant header。

Python/JS SDK 页面是巨大的自动生成符号索引，适合：

• 查类、方法、参数和返回类型。
• 确认当前包导出路径。
• 从 symbol 跳到具体 reference。

不适合：

• 学 tracing 心智模型。
• 推断生产默认值长期稳定。
• 替代 package changelog/release notes。

九、生成文档错误

当前快照中：

• Java SDK 页面标题/描述误称 JavaScript/TypeScript package，并链接到 JavaScript reference。
• Go SDK 页面也误称 JavaScript/TypeScript，reference 链接与 Go 符号不一致。

这是生成器/页面拼装错误，不代表 Java/Go SDK 不存在。采用顺序：

1. 对应语言官方 package/repository。
2. 该版本生成的 API docs。
3. docs.langchain.com 的概念/集成指南。
4. 错配聚合页仅作为发现入口。

十、上线清单

• ○ 确认唯一主 exporter，避免 direct + OTel 双写。
• ○ 验证父先/子先、parent 永不来、批次重试。
• ○ exporter 关停可 flush 且有超时。
• ○ attributes、events、resource 都经过脱敏。
• ○ 采样在跨服务链路上统一。
• ○ 使用已锁定 SDK 版本的 reference，而非聚合页示例。
• ○ OTel/LangSmith 两端都有队列、丢弃和物化延迟指标。