클라우드 에이전트 서버 환경 변수

클라우드 에이전트 서버 환경 변수

클라우드에 배포 시 LangSmith 에이전트 서버가 지원하는 환경 변수 목록이에요. 셀프 호스팅 전용 변수는 셀프 호스팅 에이전트 서버 환경 변수를 참고해요.

출처: 문서

본문

BG_JOB_ISOLATED_LOOPS

BG_JOB_ISOLATED_LOOPS를 True로 설정하면 서빙 API 이벤트 루프와 분리된 고립된 이벤트 루프에서 백그라운드 런을 실행해요.

경고: 이 플래그를 켜도 근본적인 문제가 해결되지는 않아요. 동기 블로킹 작업을 서빙 API의 이벤트 루프 밖으로 옮겨 헬스 체크가 실패하지 않게 할 뿐이에요. 하지만 블로킹 코드는 여전히 백그라운드 루프에서 실행되며, 프로덕션에서 처리량 저하, 꼬리 지연 스파이크, 워커 기아, 커넥션 풀 고갈(아래 풀 크기 주의사항 참조), 부하 시 확장성 저하 같은 문제를 계속 일으킬 거예요.

이러한 문제를 제대로 해결하려면 에이전트 전체에 네이티브 비동기 드라이버와 비동기 코드를 사용하세요. 즉 httpx나 aiohttp 같은 비동기 HTTP 클라이언트(SSL 컨텍스트 로딩의 CPU 오버헤드를 피하려면 클라이언트를 캐시하는 걸 권장해요), asyncpg나 psycopg[async] 같은 비동기 DB 드라이버, 비동기 모델 SDK를 사용하는 겁니다. 피할 수 없는 동기 라이브러리는 전체 배포에 이 플래그를 켜는 대신 해당 호출을 asyncio.to_thread(...)나 loop.run_in_executor(...)로 감싸세요.

그래프/노드 구현에 동기 코드가 포함되어 있다면 이 환경 변수를 True로 설정해야 해요. 이 경우 동기 코드가 서빙 API 이벤트 루프를 블로킹해 API를 사용할 수 없게 만들 수 있거든요. API를 사용할 수 없을 때 나타나는 증상은 헬스 체크 실패로 인한 지속적인 애플리케이션 재시작이에요.

경고: BG_JOB_ISOLATED_LOOPS가 켜지면 각 백그라운드 워커가 자체 스레드에서 별도의 Postgres 커넥션 풀로 실행돼요. 워커별 풀 크기는 LANGGRAPH_POSTGRES_POOL_MAX_SIZE // N_JOBS_PER_WORKER예요. 예를 들어 LANGGRAPH_POSTGRES_POOL_MAX_SIZE=20이고 N_JOBS_PER_WORKER=15라면 각 워커는 단 1개의 커넥션 풀만 받아요. 작은 풀은 낡은 커넥션 하나가 풀의 큰 비중을 차지하므로 커넥션 실패에 더 취약해요. 고립 루프를 켠다면 LANGGRAPH_POSTGRES_POOL_MAX_SIZE가 워커당 최소 몇 개의 커넥션을 제공할 만큼 큰지 확인하세요.

기본값은 False예요.

BG_JOB_MAX_RETRIES

백그라운드 런이 재시도 가능한 실패(예: 일시적 DB 오류, 서버 종료 취소) 후에 재시도되는 최대 횟수예요. 런이 재시도 가능한 오류로 실패하면 큐에 다시 넣고 마지막 체크포인트된 단계부터 재개해요. 최대 재시도 횟수를 초과하면 실패로 표시돼요.

기본값은 3이에요.

BG_JOB_SHUTDOWN_GRACE_PERIOD_SECS

큐가 종료 신호를 받은 후 서버가 백그라운드 작업이 끝나기를 기다리는 시간(초)이에요. 이 시간이 지나면 서버가 강제 종료해요. 기본값은 180초, 최대값은 3600초예요. 종료 중 작업이 깨끗하게 완료될 시간을 확보하도록 설정하세요. langgraph-api==0.2.16에서 추가됐어요.

BG_JOB_TIMEOUT_SECS

백그라운드 런의 타임아웃을 늘릴 수 있어요. 다만 클라우드 배포 인프라는 API 요청에 대해 1시간 타임아웃 한도를 강제해요. 즉 클라이언트-서버 연결은 1시간 후에 타임아웃 돼요. 이것은 설정할 수 없어요.

백그라운드 런은 1시간 넘게 실행될 수 있지만, 런이 1시간 넘게 걸린다면 클라이언트는 출력을 가져오기 위해 서버에 다시 연결해야 해요(예: POST /threads/{thread_id}/runs/{run_id}/stream을 통한 조인 스트림).

기본값은 86400이에요.

CORS_ALLOW_ORIGINS

허용된 오리진을 지정하려면 CORS_ALLOW_ORIGINS를 설정해요.

  • 단일 오리진 허용 예시: CORS_ALLOW_ORIGINS=https://example.com
  • 여러 오리진 허용 예시: CORS_ALLOW_ORIGINS=https://example.com,https://app.example.com

고급 CORS 구성은 커스텀 CORS 구성 추가 방법을 참고해요.

기본값은 *(모든 오리진)이에요.

지원되는 Datadog 환경 변수

배포에 이러한 환경 변수 또는 시크릿을 설정해 에이전트 서버 트레이스와 로그를 Datadog으로 보내요. 모든 변수는 DD_API_KEY가 설정된 경우에만 적용되며, 애플리케이션 프로세스를 Datadog의 ddtrace-run 트레이서와 로그 수집 에이전트로 감싸요.

  • DD_API_KEY: Datadog API 키. 필수예요. 어떤 트레이스나 로그든 Datadog으로 보내려면 이 값이 필요해요.
  • DD_LOGS_ENABLED: true로 설정하면 에이전트 서버 로그를 Datadog으로 전달해요. 생략하거나 false로 설정하면 로그 전달을 비활성화해요.
  • DD_LOGS_INJECTION: true로 설정하면 로그에 트레이스/스팬 식별자를 추가해 로그가 트레이스와 상관관계를 갖게 해요.
  • DD_TRACE_ENABLED: Datadog 트레이스 수집을 제어해요. true로 설정하면 트레이스를 수집하고 false로 설정하면 비활성화해요.
  • DD_SITE: 데이터를 보낼 Datadog 사이트(예: datadoghq.com 또는 datadoghq.eu). 기본값은 datadoghq.com이에요.
  • DD_ENV: 트레이스와 로그에 적용되는 환경 이름(예: production).
  • DD_SERVICE: 트레이스와 로그에 적용되는 서비스 이름.
  • DD_TRACE_DEBUG: 문제 해결 시 ddtrace 트레이서의 디버그 로깅을 켜려면 true로 설정해요.
  • DD_LOG_LEVEL: 문제 해결 시 Datadog 에이전트 로그 레벨(예: debug).

전체 트레이싱 옵션은 DD_* 환경 변수 참조를 확인해요.

참고: DD_API_KEY(따라서 ddtrace-run)를 켜면 애플리케이션 코드에 계측했을 수 있는 다른 자동 계측 솔루션(예: OpenTelemetry)을 덮어쓰거나 간섭할 수 있어요.

LANGGRAPH_POSTGRES_POOL_MAX_SIZE

langgraph-api 버전 0.2.12부터 Postgres 커넥션 풀의 최대 크기(레플리카당)를 LANGGRAPH_POSTGRES_POOL_MAX_SIZE 환경 변수로 제어할 수 있어요. 이 변수를 설정하면 서버가 Postgres 데이터베이스와 맺는 동시 연결 수의 상한을 정할 수 있어요.

예를 들어 배포가 10개 레플리카로 확장되고 LANGGRAPH_POSTGRES_POOL_MAX_SIZE가 150으로 구성되면 Postgres에 최대 1500개의 연결이 설정될 수 있어요. 이는 데이터베이스 리소스가 제한되거나(또는 더 여유가 있는) 성능·확장 이유로 연결 동작을 튜닝해야 하는 배포에 특히 유용해요.

BG_JOB_ISOLATED_LOOPS가 켜져 있으면 풀이 공유되지 않아요. 대신 각 백그라운드 워커 스레드가 LANGGRAPH_POSTGRES_POOL_MAX_SIZE / N_JOBS_PER_WORKER 크기의 자체 풀을 만들어요. 풀 크기를 줄일 때 이 점을 유의하세요. 공유 풀에서 잘 작동하는 값이 고립 루프에서는 워커당 아주 작은 풀을 만들 수 있어요.

기본값은 150개 연결이에요.

LS_CHECKPOINT_DELETE

지연된 체크포인트 삭제를 위한 JSON 값 구성이에요. 켜면 스레드 삭제/정리 작업이 동기적으로 삭제하는 대신 체크포인트를 백그라운드 삭제용 큐에 넣어 I/O를 요청 핫 패스 밖으로 옮겨요. langgraph-api>=0.8.1에서 사용할 수 있어요.

참고: 기본 PostgreSQ L 체크포인터 백엔드에서만 지원돼요. 지연 삭제는 향후 릴리스에서 기본값이 될 예정이에요.

허용되는 필드:

  • enabled (boolean, 기본 false): true면 스레드 삭제/정리 작업이 체크포인트를 checkpoint_delete_queue에 넣고 즉시 반환하며, 백그라운드 워커가 큐를 비워요.
  • enabledWorkerOnly (boolean, 기본 false): 새 항목을 넣지 않고 백그라운드 드레인 워커만 실행해요. enabled를 다시 false로 되돌린 후 큐 드레이닝을 끝내려면 이 옵션을 사용해요.
  • pollIntervalMs (integer, 기본 5000): 워커가 큐를 폴링하는 주기(밀리초).
  • batchSize (integer, 기본 25): 워커가 트랜잭션당 큐에서 빼내는 체크포인트 항목 수. 값이 작을수록 I/O가 시간에 걸쳐 분산되지만 드레인 지연 시간이 길어져요.
  • batchSleepMs (integer, 기본 500): 큐가 비어 있지 않을 때 워커가 배치 사이에 자는 시간(밀리초).

예시: LS_CHECKPOINT_DELETE='{"enabled":true,"batchSize":10,"pollIntervalMs":1000}'.

기본값은 비활성화(동기 체크포인트 삭제)예요.

LS_DEFAULT_CHECKPOINTER_BACKEND

langgraph.json에 지정하지 않은 에이전트 서버의 기본 체크포인터 백엔드를 설정해요. 허용 값: "default"(PostgreSQL), "mongo", "custom".

애플리케이션의 langgraph.json에 checkpointer.backend 값이 있으면 이 변수보다 우선해요.

"mongo"로 설정하면 LS_MONGODB_URI를 통해 MongoDB 연결 URI도 제공해야 해요.

LANGSMITH_TRACING

LangSmith로의 트레이싱을 비활성화하려면 LANGSMITH_TRACING을 false로 설정해요.

참고: 런타임 조건(예: 클라이언트별 요구사항이나 데이터 민감도)에 따른 선택적 트레이싱 제어는 조건부 트레이싱을 참고해요.

기본값은 true예요.

LOG_COLOR

주로 langgraph dev 명령으로 dev 서버를 사용할 때 관련돼요. 기본 콘솔 렌더러를 사용할 때 ANSI 색상 콘솔 출력을 켜려면 LOG_COLOR을 true로 설정해요. false로 설정하면 색상 출력이 꺼져 단색 로그가 생성돼요. 기본값은 true예요.

LOG_LEVEL

로그 레벨을 구성해요. 기본값은 INFO예요.

LOG_JSON

구성된 JSONRenderer를 사용해 모든 로그 메시지를 JSON 객체로 렌더링하려면 LOG_JSON을 true로 설정해요. 이는 로그 관리 시스템이 쉽게 파싱하거나 수집할 수 있는 구조화된 로그를 생성해요. 기본값은 false예요.

N_JOBS_PER_WORKER

단일 큐 워커가 에이전트 서버 작업 큐에서 동시에 실행하는 최대 런 수예요. 기본값은 10이에요.

이 값은 동시 런 실행을 제한하지, 배포가 처리할 수 있는 API 요청 수를 제한하지는 않아요. 요청 서빙 용량은 API 서버가 처리하며 이 값과 무관하게 확장돼요. 튜닝 지침은 확장을 위한 에이전트 서버 구성을 참고해요.

LS_APM_OTEL_ENABLED

배포에 OpenTelemetry APM 트레이싱을 구성하려면 LS_APM_OTEL_ENABLED를 true로, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 또는 OTEL_EXPORTER_OTLP_ENDPOINT를 대상 트레이스 수집 엔드포인트로 설정해요. 0.7.17 이후 서버 버전에서 OpenTelemetry APM 트레이싱을 활성화하려면 LS_APM_OTEL_ENABLED와 나머지 두 내보내기 엔드포인트 중 하나가 모두 필요해요.

트레이싱, 로깅 및 기타 계측을 구성하려면 다른 OTEL_* 환경 변수를 지정해요.

# If you set LS_APM_OTEL_ENABLED AND (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT),
# the server starts with OpenTelemetry instrumentation enabled.
LS_APM_OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<target trace ingestion endpoint>
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net
OTEL_SERVICE_NAME=MY_LANGSMITH_DEPLOYMENT
OTEL_EXPORTER_OTLP_HEADERS=api-key=<YOUR_INGEST_LICENSE_KEY>
LANGSMITH_OTEL_ENABLED=true
# Common OTEL settings
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT=4095
OTEL_EXPORTER_OTLP_COMPRESSION=gzip
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta
OTEL_PYTHON_EXCLUDED_URLS=/metrics,/ok,/info
# Optional: OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true

예를 들어 OpenTelemetry 트레이스를 New Relic US 리전에 제출하려면 다음과 같이 설정해요:

LS_APM_OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.nr-data.net/v1/traces
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.nr-data.net
OTEL_EXPORTER_OTLP_HEADERS=api-key=<YOUR_INGEST_LICENSE_KEY>

참고: OTel APM 트레이싱은 에이전트 서버 버전 0.5.32에서 추가됐으며 현재 Alpha 상태예요.

LS_MONGODB_URI

MongoDB 체크포인터 백엔드용 MongoDB 연결 URI예요.

URI는 레플리카 세트 멤버 또는 mongos 라우터를 가리켜야 하며 경로에 데이터베이스 이름을 포함해야 해요.

자세한 내용은 체크포인터 백엔드 구성을 참고해요.

REDIS_KEY_PREFIX

참고: API 서버 버전 0.1.9+에서 사용 가능 — 이 환경 변수는 API 서버 0.1.9 이상에서 지원돼요.

Redis 키의 접두어를 지정해요. 이렇게 하면 여러 에이전트 서버 인스턴스가 서로 다른 키 접두어로 같은 Redis 인스턴스를 공유할 수 있어요.

기본값은 ''이에요.

REDIS_URI_CUSTOM

참고: 하이브리드 및 셀프 호스팅 전용 — 커스텀 Redis 인스턴스는 하이브리드 및 셀프 호스팅 배포에서만 사용할 수 있어요.

커스텀 Redis 인스턴스를 사용하려면 REDIS_URI_CUSTOM을 지정해요. REDIS_URI_CUSTOM의 값은 유효한 Redis 연결 URI여야 해요.

REDIS_MAX_CONNECTIONS

Redis 커넥션 풀의 최대 크기(레플리카당)를 REDIS_MAX_CONNECTIONS 환경 변수로 제어할 수 있어요. 이 변수를 설정하면 서버가 Redis 인스턴스와 맺는 동시 연결 수의 상한을 정할 수 있어요.

예를 들어 배포가 10개 레플리카로 확장되고 REDIS_MAX_CONNECTIONS가 150으로 구성되면 Redis에 최대 1500개의 연결이 설정될 수 있어요.

기본값은 2000이에요.

RESUMABLE_STREAM_TTL_SECONDS

Redis에서 재개 가능한 스트림 데이터의 수명(TTL)을 초 단위로 지정해요.

런이 생성되고 출력이 스트리밍될 때 스트림을 재개 가능하게(예: stream_resumable=True) 구성할 수 있어요. 스트림이 재개 가능하면 스트림의 출력이 Redis에 일시적으로 저장돼요. 이 데이터의 TTL은 RESUMABLE_STREAM_TTL_SECONDS를 설정해 구성할 수 있어요.

재개 가능한 스트림 구현 방법에 대한 자세한 내용은 Python 및 JS/TS SDK를 참고해요.

기본값은 120초예요.

참고: RESUMABLE_STREAM_TTL_SECONDS를 아주 높게 설정하면 크거나 빈번한 스트리밍 출력이 있는 동시 런이 많을 때 상당한 Redis 메모리 사용이 발생할 수 있어요. 네트워크 중단 중 복구를 활성화하는 최소값으로 설정하고, 장기 내구성과 실행 스냅샷팅에는 체크포인팅을 선호하세요.

더 알아보기 (Learn more)