这是一个测试功能。API 可能会在未来版本中发生变化。
LangSmith Collector-Proxy 是一个轻量级、高性能的代理服务器，位于应用程序和 LangSmith 后端之间。它在将跟踪数据发送到 LangSmith 之前对其进行批处理和压缩，从而减少网络开销并提高性能。

​
何时使用 Collector-Proxy

Collector-Proxy 在以下情况下特别有价值：
  • 您并行运行应用程序的多个实例并需要高效聚合跟踪
  • 您希望比直接 OTEL API 调用 LangSmith 更高效的跟踪（收集器优化批处理和压缩）
  • 您使用的语言没有原生 LangSmith SDK

​
主要功能

  • 高效数据传输 将多个跨度批处理为更少、更大的上传。
  • 压缩 使用 zstd 最小化有效负载大小。
  • OTLP 支持 通过 HTTP POST 接受 OTLP JSON 和 Protobuf。
  • 语义转换 将 GenAI/OpenInference 约定映射到 LangSmith Run 模型。
  • 灵活批处理 按跨度计数或时间间隔刷新。

​
配置

通过环境变量配置：
变量描述默认值
HTTP_PORT运行代理服务器的端口4318
LANGSMITH_ENDPOINTLangSmith 后端 URLhttps://api.smith.langchain.com
LANGSMITH_API_KEYLangSmith 的 API 密钥必需（环境变量或请求头）
LANGSMITH_PROJECT默认跟踪项目如果未指定则为默认项目
BATCH_SIZE每批上传的跨度数100
FLUSH_INTERVAL_MS刷新间隔（毫秒）1000
MAX_BUFFER_BYTES最大未压缩缓冲区大小10485760（10 MB）
MAX_BODY_BYTES最大传入请求主体大小209715200（200 MB）
MAX_RETRIES失败上传的重试次数3
RETRY_BACKOFF_MS初始退避（毫秒）100

​
项目配置

Collector-Proxy 支持 LangSmith 项目配置，优先级如下：
  1. 如果在请求头中指定了项目（Langsmith-Project），将使用该项目
  2. 如果头中未指定项目，它将使用 LANGSMITH_PROJECT 环境变量中设置的项目
  3. 如果都未设置，它将跟踪到 default 项目。

​
身份验证

API 密钥可以通过以下任一方式提供：
  • 作为环境变量（LANGSMITH_API_KEY）
  • 在请求头中（X-API-Key）

​
部署（Docker）

您可以使用 Docker 部署 Collector-Proxy：
  1. 构建镜像 
    docker build \
  -t langsmith-collector-proxy:beta .
  2. 运行容器 
    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 的跨度路由到同一实例（例如，通过一致性哈希）。

​
Fork 和扩展

Fork GitHub 上的 Collector-Proxy 仓库并实现您自己的转换器：
  • 创建自定义 GenAiConverter 或修改 internal/translator/otel_converter.go 中的现有转换器
  • 在 internal/translator/translator.go 中注册自定义转换器
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.