---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
- langchain
- langsmith
- opentelemetry
- sdk
topic: LangSmith OpenTelemetry、采集器、SDK 与参考边界
sources:
- https://docs.langchain.com/langsmith/langsmith-collector
- https://docs.langchain.com/langsmith/observability-stack
- https://docs.langchain.com/langsmith/smith-api-ref
- https://docs.langchain.com/langsmith/smith-go-sdk
- https://docs.langchain.com/langsmith/smith-java-sdk
- https://docs.langchain.com/langsmith/smith-js-ts-sdk
- https://docs.langchain.com/langsmith/smith-python-sdk
- https://docs.langchain.com/langsmith/trace-with-opentelemetry
last_verified: 2026-08-11
---
# OpenTelemetry、采集器、SDK 与参考边界
> [!summary]
> OTel 适合统一跨语言链路，但 LangSmith 不是被动保存任意 span：它会把属性映射成 run，并等待父节点完成树结构。接收端返回 200 只表示已接收，不保证 trace 已完成物化。
## 一、三种 tracing mode
| 模式 | 行为 | 适用 |
|---|---|---|
| 默认 LangSmith | SDK 直接批量发送 runs | 单体/常规 LangChain 应用 |
| OTel only | SDK runs 转 OTel，通过 exporter/collector | 企业统一 OTel 管道 |
| Hybrid | 同时走 LangSmith 与 OTel | 迁移/对照；文档当前仅 Python |
版本节点：
- LangSmith OTel ingestion 支持从 Python 0.3.18 起。
- 文档推荐 Python 0.4.25+。
- hybrid 要求 0.4.1+。
- 这些是文档快照，依赖落地时仍应查 package release。
## 二、属性映射
LangSmith 能识别：
- langsmith.* 专用属性。
- 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 会进入 otel.resource.* metadata。
- 同一信息不要同时在多个 convention 重复上报，否则 token/messages 可能重复。
- 自定义高基数 resource 字段会放大存储和查询成本。
## 三、父子到达顺序
OTel 异步批量可能让 child 先于 parent 到达。LangSmith 会缓冲孤儿：
- parent 后到时正确嵌套。
- parent 永远不到时，child 在缓冲过期后静默丢弃。
- 自托管相关配置 REDIS_RUNS_EXPIRY_SECONDS 默认约 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 权威来源，认证头通常为 X-Api-Key；一个 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 两端都有队列、丢弃和物化延迟指标。