이것은 베타 기능입니다. API는 향후 릴리스에서 변경될 수 있습니다.
LangSmith Collector-Proxy는 애플리케이션과 LangSmith 백엔드 사이에 위치하는 경량의 고성능 proxy 서버입니다. LangSmith로 전송하기 전에 trace 데이터를 일괄 처리하고 압축하여 네트워크 오버헤드를 줄이고 성능을 향상시킵니다.

​
Collector-Proxy를 사용해야 하는 경우

Collector-Proxy는 다음과 같은 경우에 특히 유용합니다:
  • 애플리케이션의 여러 인스턴스를 병렬로 실행하고 trace를 효율적으로 집계해야 하는 경우
  • LangSmith에 대한 직접적인 OTEL API 호출보다 더 효율적인 tracing을 원하는 경우 (collector가 일괄 처리 및 압축을 최적화합니다)
  • 네이티브 LangSmith SDK가 없는 언어를 사용하는 경우

​
주요 기능

  • 효율적인 데이터 전송 여러 span을 더 적은 수의 대용량 업로드로 일괄 처리합니다.
  • 압축 zstd를 사용하여 payload 크기를 최소화합니다.
  • OTLP 지원 HTTP POST를 통한 OTLP JSON 및 Protobuf를 수용합니다.
  • 의미론적 변환 GenAI/OpenInference 규칙을 LangSmith Run 모델로 매핑합니다.
  • 유연한 일괄 처리 span 수 또는 시간 간격으로 flush합니다.

​
Configuration

환경 변수를 통해 구성합니다:
VariableDescriptionDefault
HTTP_PORTproxy 서버를 실행할 포트4318
LANGSMITH_ENDPOINTLangSmith 백엔드 URLhttps://api.smith.langchain.com
LANGSMITH_API_KEYLangSmith용 API key필수 (환경 변수 또는 헤더)
LANGSMITH_PROJECT기본 tracing project지정되지 않은 경우 기본 project
BATCH_SIZE업로드 배치당 span 수100
FLUSH_INTERVAL_MSFlush 간격(밀리초)1000
MAX_BUFFER_BYTES최대 압축되지 않은 버퍼 크기10485760 (10 MB)
MAX_BODY_BYTES최대 수신 요청 본문 크기209715200 (200 MB)
MAX_RETRIES실패한 업로드에 대한 재시도 횟수3
RETRY_BACKOFF_MS초기 backoff(밀리초)100

​
Project Configuration

Collector-Proxy는 다음 우선순위로 LangSmith project 구성을 지원합니다:
  1. 요청 헤더(Langsmith-Project)에 project가 지정된 경우 해당 project가 사용됩니다
  2. 헤더에 project가 지정되지 않은 경우 LANGSMITH_PROJECT 환경 변수에 설정된 project를 사용합니다
  3. 둘 다 설정되지 않은 경우 default project로 trace합니다.

​
Authentication

API key는 다음 중 하나로 제공할 수 있습니다:
  • 환경 변수로 (LANGSMITH_API_KEY)
  • 요청 헤더에 (X-API-Key)

​
Deployment (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

​
Usage

OTLP 호환 클라이언트 또는 OpenTelemetry Collector exporter를 다음 주소로 지정합니다: 
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>"
테스트 trace 전송: 
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

전체 trace가 올바르게 일괄 처리되도록 하려면 동일한 trace ID를 가진 span을 동일한 인스턴스로 라우팅하세요 (예: consistent hashing을 통해).

​
Fork & Extend

GitHub의 Collector-Proxy repo를 fork하고 자체 converter를 구현하세요:
  • internal/translator/otel_converter.go에서 사용자 정의 GenAiConverter를 생성하거나 기존 converter를 수정합니다
  • internal/translator/translator.go에 사용자 정의 converter를 등록합니다
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I