> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-update-1770920925-e15dbde.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Beta LangSmith Collector-Proxy

<Note>
  This is a beta feature. The API may change in future releases.
</Note>

The LangSmith Collector-Proxy is a lightweight, high-performance proxy server that sits between your application and the LangSmith backend. It batches and compresses trace data before sending it to LangSmith, reducing network overhead and improving performance.

## When to use the Collector-Proxy

The Collector-Proxy is particularly valuable when:

* You're running multiple instances of your application in parallel and need to efficiently aggregate traces
* You want more efficient tracing than direct OTEL API calls to LangSmith (the collector optimizes batching and compression)
* You're using a language that doesn't have a native LangSmith SDK

## Key features

* **Efficient Data Transfer** Batches multiple spans into fewer, larger uploads.
* **Compression** Uses zstd to minimize payload size.
* **OTLP Support** Accepts OTLP JSON and Protobuf over HTTP POST.
* **Semantic Translation** Maps GenAI semantic conventions to the LangSmith Run model.
* **Flexible Batching** Flush by span count or time interval.

## Configuration

Configure via environment variables:

| Variable             | Description                       | Default                           |
| -------------------- | --------------------------------- | --------------------------------- |
| `HTTP_PORT`          | Port to run the proxy server      | `4318`                            |
| `LANGSMITH_ENDPOINT` | LangSmith backend URL             | `https://api.smith.langchain.com` |
| `LANGSMITH_API_KEY`  | API key for LangSmith             | **Required** (env var or header)  |
| `LANGSMITH_PROJECT`  | Default tracing project           | Default project if not specified  |
| `BATCH_SIZE`         | Spans per upload batch            | `100`                             |
| `FLUSH_INTERVAL_MS`  | Flush interval in milliseconds    | `1000`                            |
| `MAX_BUFFER_BYTES`   | Max uncompressed buffer size      | `10485760` (10 MB)                |
| `MAX_BODY_BYTES`     | Max incoming request body size    | `209715200` (200 MB)              |
| `MAX_RETRIES`        | Retry attempts for failed uploads | `3`                               |
| `RETRY_BACKOFF_MS`   | Initial backoff in milliseconds   | `100`                             |

### Project configuration

The Collector-Proxy supports LangSmith project configuration with the following priority:

1. If a project is specified in the request headers (`Langsmith-Project`), that project will be used
2. If no project is specified in headers, it will use the project set in the `LANGSMITH_PROJECT` environment variable
3. If neither is set, it will trace to the `default` project.

### Authentication

The API key can be provided either:

* As an environment variable (`LANGSMITH_API_KEY`)
* In the request headers (`X-API-Key`)

## Deployment (Docker)

You can deploy the Collector-Proxy with Docker:

1. **Build the image**

   ```bash theme={null}
   docker build \
     -t langsmith-collector-proxy:beta .
   ```

2. **Run the container**

   ```bash theme={null}
   docker run -d \
     -p 4318:4318 \
     -e LANGSMITH_API_KEY=<your_api_key> \
     -e LANGSMITH_PROJECT=<your_project> \
     langsmith-collector-proxy:beta
   ```

## Usage

Point any OTLP-compatible client or the OpenTelemetry Collector exporter at:

```bash theme={null}
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>"
```

Send a test trace:

```bash theme={null}
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": {}
              }
            ]
          }
        ]
      }
    ]
  }'
```

## Health & scaling

* **Liveness**: `GET /live` → 200
* **Readiness**: `GET /ready` → 200

## Horizontal scaling

To ensure full traces are batched correctly, route spans with the same trace ID to the same instance (e.g., via consistent hashing).

## Fork & extend

Fork the [Collector-Proxy repo on GitHub](https://github.com/langchain-ai/langsmith-collector-proxy) and implement your own converter:

* Create a custom `GenAiConverter` or modify the existing one in `internal/translator/otel_converter.go`
* Register the custom converter in `internal/translator/translator.go`

***

<Callout icon="pen-to-square" iconType="regular">
  [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/collector-proxy.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
</Callout>

<Tip icon="terminal" iconType="regular">
  [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
</Tip>