[测试版] LangSmith 收集器-代理
注意
LangSmith 收集器-代理功能目前处于测试阶段，可能会有变动。 在 GitHub 上查看源代码。
LangSmith 收集器-代理是一个中间件服务，旨在高效地聚合、压缩并批量上传来自您应用程序的 OTEL 追踪数据到 LangSmith。它针对大规模、并行且生成高容量 span 的环境进行了优化。
何时使用收集器-代理
在以下情况下，收集器-代理尤其有价值：
- 您正在并行运行应用程序的多个实例，并且需要高效地聚合追踪
- 您希望追踪效率高于直接对 LangSmith 进行 OTEL API 调用（收集器优化了批量处理和压缩）
- 您正在使用没有原生 LangSmith SDK 的语言
主要功能
- 高效数据传输 将多个 span 批量处理为更少、更大的上传。
- 压缩 使用 zstd 最大限度地减小负载大小。
- OTLP 支持 通过 HTTP POST 接受 OTLP JSON 和 Protobuf。
- 语义转换 将 GenAI/OpenInference 约定映射到 LangSmith 运行模型。
- 灵活批量处理 按 span 数量或时间间隔刷新。
配置
通过环境变量配置
| 变量 | 描述 | 默认值 |
|---|---|---|
HTTP_PORT | 代理服务器运行端口 | 4318 |
LANGSMITH_ENDPOINT | LangSmith 后端 URL | https://api.smith.langchain.com |
LANGSMITH_API_KEY | LangSmith 的 API 密钥 | 必需（环境变量或请求头） |
LANGSMITH_PROJECT | 默认追踪项目 | 如果未指定，则为默认项目 |
BATCH_SIZE | 每个上传批次的 span 数量 | 100 |
FLUSH_INTERVAL_MS | 刷新间隔（毫秒） | 1000 |
MAX_BUFFER_BYTES | 最大未压缩缓冲区大小 | 10485760 (10 MB) |
MAX_BODY_BYTES | 最大传入请求体大小 | 209715200 (200 MB) |
MAX_RETRIES | 失败上传的重试次数 | 3 |
RETRY_BACKOFF_MS | 初始退避时间（毫秒） | 100 |
项目配置
收集器-代理支持 LangSmith 项目配置，优先级如下：
- 如果在请求头中指定了项目 (
Langsmith-Project)，将使用该项目 - 如果在请求头中未指定项目，将使用
LANGSMITH_PROJECT环境变量中设置的项目 - 如果两者均未设置，将追踪到
default项目。
认证
API 密钥可以通过以下方式提供：
- 作为环境变量 (
LANGSMITH_API_KEY) - 在请求头中 (
X-API-Key)
部署 (Docker)
您可以使用 Docker 部署收集器-代理
-
构建镜像
docker build \
-t langsmith-collector-proxy:beta . -
运行容器
docker run -d \
-p 4318:4318 \
-e LANGSMITH_API_KEY=<your_api_key> \
-e LANGSMITH_PROJECT=<your_project> \
langsmith-collector-proxy:beta
使用
将任何 OTLP 兼容的客户端或 OpenTelemetry Collector 导出器指向
export OTEL_EXPORTER_OTLP_ENDPOINT=http://<host>:4318/v1/traces
export OTEL_EXPORTER_OTLP_HEADERS="X-API-Key=<your_api_key>,Langsmith-Project=<your_project>"
发送测试追踪
curl -X POST http://localhost:4318/v1/traces \
-H "Content-Type: application/json" \
--data '{
"resourceSpans": [
{
"resource": {
"attributes": [
{
"key": "service.name",
"value": { "stringValue": "test-service" }
}
]
},
"scopeSpans": [
{
"scope": {
"name": "example/instrumentation",
"version": "1.0.0"
},
"spans": [
{
"traceId": "T6nh/mMkIONaoHewS9UWIw==",
"spanId": "0tEqJwCpvU0=",
"name": "parent-span",
"kind": "SPAN_KIND_INTERNAL",
"startTimeUnixNano": 1747675155185223936,
"endTimeUnixNano": 1747675156185223936,
"attributes": [
{
"key": "gen_ai.prompt",
"value": {
"stringValue": "{\"text\":\"Hello, world!\"}"
}
},
{
"key": "gen_ai.usage.input_tokens",
"value": {
"intValue": "5"
}
},
{
"key": "gen_ai.completion",
"value": {
"stringValue": "{\"text\":\"Hi there!\"}"
}
},
{
"key": "gen_ai.usage.output_tokens",
"value": {
"intValue": "3"
}
}
],
"droppedAttributesCount": 0,
"events": [],
"links": [],
"status": {}
}
]
}
]
}
]
}'
健康与扩展
- 存活度:
GET /live→ 200 - 就绪度:
GET /ready→ 200
水平扩展
为确保完整追踪被正确批量处理，请将具有相同追踪 ID 的 span 路由到同一实例（例如，通过一致性哈希）。
分叉与扩展
在 GitHub 上分叉 Collector-Proxy 仓库并实现您自己的转换器
- 在
internal/translator/otel_converter.go中创建自定义GenAiConverter或修改现有转换器 - 在
internal/translator/translator.go中注册自定义转换器