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

​
Collector-Proxy 사용 시기

다음과 같은 경우에 Collector-Proxy가 특히 유용합니다:
  • 애플리케이션의 여러 인스턴스를 병렬로 실행하고 있으며 추적 데이터를 효율적으로 집계해야 하는 경우
  • LangSmith에 직접 OTEL API를 호출하는 것보다 더 효율적인 추적이 필요한 경우 (collector가 일괄 처리 및 압축을 최적화함)
  • 네이티브 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": {}
              }
            ]
          }
        ]
      }
    ]
  }'

​
상태 확인 및 스케일링

  • Liveness: GET /live → 200
  • Readiness: GET /ready → 200

​
수평 스케일링

전체 추적이 올바르게 일괄 처리되도록 하려면, 동일한 trace ID를 가진 스팬을 동일한 인스턴스로 라우팅하십시오 (예: 일관된 해싱을 통해).

​
Fork 및 확장

GitHub의 Collector-Proxy 저장소를 포크하고 자체 컨버터를 구현하십시오:
  • internal/translator/otel_converter.go에서 사용자 정의 GenAiConverter를 생성하거나 기존 컨버터를 수정합니다
  • 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.
⌘I