트레이스 데이터 대량 내보내기
트레이스 데이터 대량 내보내기
LangSmith 트레이스 데이터를 S3 호환 버킷에 Parquet 형식으로 내보내요.
요금제 제한 적용
2026년 8월 3일 이후에 가입한 고객에게는 대량 내보내기가 LangSmith Enterprise 요금제에서만 제공돼요. 2026년 8월 3일 이전에 가입한 고객은 2027년 2월 1일까지 Plus 또는 Enterprise 요금제에서 대량 내보내기를 사용할 수 있어요.
LangSmith의 대량 데이터 내보내기를 사용하면 특정 프로젝트와 날짜 범위의 트레이스 데이터를 Parquet 형식으로 S3 호환 버킷에 내보내는데, 런 데이터 형식의 필드와 일치해요. 이는 BigQuery, Snowflake, Redshift 또는 Jupyter Notebook 같은 도구에서 오프라인 분석하는 데 유용해요.
이 페이지에서는 다음을 다뤄요:
- 내보내기 대상(destination) 만들기
- 스케줄 내보내기와 필드 필터링을 포함한 내보내기 작업 만들기 및 구성
- 내보내기 진행 상황 모니터링
시작하기 전에: 데이터 볼륨에 따라 내보내기에는 시간이 걸릴 수 있으며, LangSmith는 동시에 실행할 수 있는 내보내기 수를 제한해요. 대량 내보내기에는 72시간 런타임 타임아웃이 있어요—자세한 내용은 자동 재시도 동작을 참고하세요. 시작되면 LangSmith가 내보내기 프로세스의 오케스트레이션과 복원력을 자동으로 처리해요.
출처: 문서
본문
1. 대상(destination) 만들기
대상은 내보낸 데이터를 어디에 쓸지 LangSmith에 알려줘요. 이 요청을 하기 전에 다음이 필요해요:
- LangSmith API 키와 워크스페이스 ID.
- LangSmith에 쓰기 접근이 부여된 S3 또는 S3 호환 버킷 (필요한 권한 참고).
- 버킷 이름, 접두사, 그리고 (AWS S3의 경우) AWS 리전 또는 (GCS, MinIO 또는 기타 S3 호환 프로바이더의 경우) 엔드포인트 URL.
- 버킷의 액세스 키와 시크릿 키.
curl --request POST \
--url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: ***' \
--header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
--data '{
"destination_type": "s3",
"display_name": "My S3 Destination",
"config": {
"bucket_name": "your-s3-bucket-name",
"prefix": "root_folder_prefix",
"region": "your aws s3 region",
"endpoint_url": "your endpoint url for s3 compatible buckets"
},
"credentials": {
"access_key_id": "YOUR_S3_ACCESS_KEY_ID",
"secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
}
}'
자격 증명은 암호화된 형태로 안전하게 저장돼요. API는 저장 전에 대상과 자격 증명이 유효한지 검증해요. 요청이 실패하면 대상 오류 디버깅을 참고하세요.
응답의 id는 내보내기 작업을 만들 때 필요하므로 저장하세요.
권한 설정, 프로바이더별 구성(AWS S3, GCS, MinIO) 및 자격 증명 옵션은 대량 내보내기 대상 관리를 참고하세요.
2. 내보내기 작업 만들기
내보내기 작업은 프로젝트(또는 워크스페이스의 모든 실험)와 날짜 범위를 대상으로 해요. 다음이 필요해요:
- 이전 단계의 대상
id. - 프로젝트 ID(
session_id) 또는"all_experiments": true중 하나—프로젝트 ID는 Tracing Projects 목록의 개별 프로젝트 보기에서 복사하세요. - UTC ISO 8601 형식의
start_time및end_time.
curl --request POST \
--url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: ***' \
--header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
--data '{
"bulk_export_destination_id": "your_destination_id",
"session_id": "project_uuid",
"start_time": "2024-01-01T00:00:00Z",
"end_time": "2024-01-03T00:00:00Z",
"format_version": "v2_beta"
}'
start_time은 포함이고 end_time은 제외돼요. run.start_time >= start_time 및 run.start_time < end_time을 만족하는 모든 런이 내보내기에 포함돼요.
응답의 id를 저장해서 내보내기 진행 상황을 모니터링하세요.
선택적으로 filter 표현식을 추가해 내보낼 런 집합을 좁힐 수 있어요. 구문은 필터 쿼리 언어와 예시를 참고하세요. filter 필드를 설정하지 않으면 모든 런이 내보내져요.
LangSmith Cloud 제한: 워크스페이스당 시간당 대량 내보내기 생성 250건
LangSmith 클라우드에서 각 워크스페이스는 시간당 최대 250개의 대량 내보내기를 만들 수 있어요. 이 예산에는 일회성 내보내기와 스케줄 대량 내보내기로 생성된 내보내기가 포함되므로, 활성 스케줄이 많은 워크스페이스는 시간당 예산의 일부를 자동으로 소비해요.
워크스페이스가 제한에 도달하면 이전 생성이 60분 이동 창을 지날 때까지 새 생성 요청이 429로 거부돼요. 제한을 올리려면 support.langchain.com을 통해 지원팀에 문의하세요.
셀프 호스팅 LangSmith는 기본적으로 이 제한을 적용하지 않아요.
모든 실험 내보내기
셀프 호스팅: 현재
v0.16.1rc1프리뷰 릴리스에서만 사용 가능해요. 프로덕션에서 실행하기 전에v0.16.1안정 릴리스를 기다리세요.
session_id로 단일 프로젝트를 대상으로 하는 대신 워크스페이스의 모든 실험을 내보내려면 all_experiments: true를 설정하세요. LangSmith는 데이터셋에 대해 평가를 실행할 때마다 실험을 만들므로, reference_dataset_id가 설정된 모든 추적 프로젝트가 해당돼요.
all_experiments와 session_id는 상호 배타적이에요—정확히 하나만 설정하세요.
curl --request POST \
--url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: ***' \
--header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
--data '{
"bulk_export_destination_id": "your_destination_id",
"all_experiments": true,
"start_time": "2024-01-01T00:00:00Z",
"end_time": "2024-02-01T00:00:00Z",
"format_version": "v2_beta"
}'
LangSmith는 런타임에 실험 세션 집합을 결정하므로, 내보내기는 작업 제출 후 오케스트레이터가 처리를 시작하기 전에 만든 실험도 모두 포함해요.
동일한 all_experiments 플래그는 스케줄 내보내기에서도 작동해요—end_time을 제공하는 대신 interval_hours를 포함하고 end_time을 생략하세요.
Cloud 제한: 내보내기당 실험 250개
LangSmith 클라우드에서 각
all_experiments내보내기는 최대 250개의 실험을 포함해요. 더 내보내려면:
- 완료된
all_experiments내보내기를 조회해 어떤 추적 프로젝트가 포함되었는지 확인한 다음, 남은 실험에 대해session_id로 표준 대량 내보내기를 만드세요.- 또는 support.langchain.com을 통해 지원팀에 문의해 워크스페이스의 상한을 높이도록 요청하세요.
셀프 호스팅 LangSmith에는 내보내기당 제한이 없어요.
반복 내보내기 스케줄링
LangSmith Helm 버전
0.10.42이상(애플리케이션 버전0.10.109이상) 필요
스케줄 내보내기는 런을 주기적으로 수집해 구성된 대상으로 내보내요. 스케줄 내보내기를 만들려면 interval_hours를 포함하고 end_time을 생략하세요:
curl --request POST \
--url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: ***' \
--header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
--data '{
"bulk_export_destination_id": "your_destination_id",
"session_id": "project_uuid",
"start_time": "2024-01-01T00:00:00Z",
"interval_hours": 1,
"format_version": "v2_beta"
}'
interval_hours는 1과 168(1주) 사이의 값을 포함해야 해요.- 스케줄 내보내기에는
end_time을 생략해야 해요. 일회성 내보내기에는 여전히 필요해요. - 각 생성된 내보내기는
start_time부터start_time + interval_hours까지를 다루고, 이후 실행마다interval_hours만큼 진행돼요.end_time은 제외이므로 연속 내보내기는 겹치지 않아요. - 생성된 내보내기는 최근 과거의
end_time으로 제출된 런을 처리하기 위해end_time + 10 minutes에 실행돼요. - 생성된 내보내기에는
source_bulk_export_id속성이 채워져 있어요. 원한다면 별도로 취소해야 해요—소스 내보내기를 취소해도 이미 생성된 내보내기는 취소되지 않아요. - 스케줄 내보내기를 중지하려면 취소하세요.
LangSmith Cloud 제한: 워크스페이스당 스케줄 대량 내보내기 200개
LangSmith 클라우드에서 각 워크스페이스는 한 번에 최대 200개의 활성 스케줄(반복) 대량 내보내기를 가질 수 있어요. 즉
interval_hours값으로 구성된 내보내기를 말해요. 이 제한은 스케줄 수를 상한으로 제한하지 그들이 실행된 횟수를 제한하는 것은 아니에요. 수천 개의 과거 내보내기 실행을 생성한 스케줄도 여전히 하나로 계산돼요.일회성(비반복) 대량 내보내기는 이 제한의 적용을 받지 않아요.
워크스페이스가 제한에 도달하면 기존 스케줄을 취소할 때까지 새 스케줄 내보내기 요청이
429로 거부돼요. 제한을 올리려면 support.langchain.com을 통해 지원팀에 문의하세요.셀프 호스팅 LangSmith는 기본적으로 이 제한을 적용하지 않아요.
예시
start_time=2025-07-16T00:00:00Z와 interval_hours=6으로 스케줄 대량 내보내기를 만들었다면:
| 내보내기 | 시작 시간 | 종료 시간 | 실행 시각 |
|---|---|---|---|
| 1 | 2025-07-16T00:00:00Z | 2025-07-16T06:00:00Z | 2025-07-16T06:10:00Z |
| 2 | 2025-07-16T06:00:00Z | 2025-07-16T12:00:00Z | 2025-07-16T12:10:00Z |
| 3 | 2025-07-16T12:00:00Z | 2025-07-16T18:00:00Z | 2025-07-16T18:10:00Z |
내보낼 필드 제한하기
LangSmith Helm 버전
0.12.11이상(애플리케이션 버전0.12.42이상) 필요. 일회성 및 스케줄 내보내기 모두에서 지원돼요.
export_fields 파라미터로 포함할 필드를 제한해서 내보내기 속도를 높이고 파일 크기를 줄일 수 있어요. export_fields를 생략하면 feedbacks를 제외한 모든 필드가 포함돼요.
피드백 댓글은 선택 사항(opt-in)이에요. 포함하려면 다른 관련 필드와 함께 export_fields에 feedbacks를 명시적으로 추가하세요.
curl --request POST \
--url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: ***' \
--header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
--data '{
"bulk_export_destination_id": "your_destination_id",
"session_id": "project_uuid",
"start_time": "2024-01-01T00:00:00Z",
"end_time": "2024-01-03T00:00:00Z",
"export_fields": ["id", "name", "run_type", "start_time", "end_time", "status", "total_tokens", "total_cost"],
"format_version": "v2_beta"
}'
inputs와outputs를 제외하면 특히 큰 런에서 내보내기 성능을 크게 개선하고 파일 크기를 줄일 수 있어요. 분석에 필요할 때만 이 필드를 포함하세요.
압축
compression 필드를 설정해 내보낸 Parquet 파일이 어떻게 압축되는지 제어하세요. 생략하면 LangSmith는 zstandard를 사용해요.
허용 값: zstandard, gzip, snappy, none. BigQuery에 로드할 때는 snappy를 사용하세요. BigQuery로 트레이스 데이터 내보내기를 참고하세요.
LangSmith 0.16.0부터 셀프 호스팅 LangSmith도
compression이 생략되면 기본값으로zstandard를 사용해요. 이는 이전 버전의 기본값인gzip에서 달라진 호환되지 않는 변경이에요. 기본값을 재정의하려면FF_BULK_EXPORT_DEFAULT_COMPRESSION환경 변수를 설정하세요.
내보낼 수 있는 필드
기본적으로 대량 내보내기는 각 런에 대해 다음 필드를 포함해요:
식별자 및 계층:
| 필드 | 설명 |
|---|---|
id |
런 ID |
tenant_id |
워크스페이스/테넌트 ID |
session_id |
프로젝트/세션 ID |
trace_id |
트레이스 ID |
parent_run_id |
상위 런 ID |
parent_run_ids |
모든 상위 런 ID 목록 |
reference_example_id |
데이터셋의 일부라면 예시에 대한 참조 |
기본 메타데이터:
| 필드 | 설명 |
|---|---|
name |
런 이름 |
run_type |
런 유형 (예: "chain", "llm", "tool") |
start_time |
시작 타임스탬프 (UTC) |
end_time |
종료 타임스탬프 (UTC) |
status |
런 상태 (예: "success", "error") |
is_root |
루트 수준 런인지 여부 |
dotted_order |
계층적 순서 문자열 |
trace_tier |
트레이스 계층/보존 수준 |
런 데이터:
| 필드 | 설명 |
|---|---|
inputs |
런 입력 (JSON) |
outputs |
런 출력 (JSON) |
error |
실패 시 오류 메시지 |
extra |
추가 메타데이터 (JSON) |
events |
런 이벤트 (JSON) |
태그 및 피드백:
| 필드 | 설명 |
|---|---|
tags |
태그 목록 |
feedback_stats |
피드백 통계 (JSON). 집계 제한은 다음 참고 사항을 참고하세요. |
feedbacks |
피드백 댓글 및 키 (JSON) |
feedback_stats집계 제한
feedback_stats필드는 문자열 유형 피드백에 대한 값 세분화만 포함해요. 비문자열 값(숫자, 부울, 복합 유형)이 있는 피드백은 이 세분화에서 제외돼요. 비문자열 피드백 값을 분석하려면 원시 피드백 데이터를 별도로 내보내세요.
토큰 사용량 및 비용:
| 필드 | 설명 |
|---|---|
total_tokens |
총 토큰 수 |
prompt_tokens |
프롬프트 토큰 수 |
completion_tokens |
완료 토큰 수 |
total_cost |
총 비용 |
prompt_cost |
프롬프트 비용 |
completion_cost |
완료 비용 |
first_token_time |
첫 토큰까지의 시간 |
파티셔닝 체계
데이터는 다음 Hive 파티셔닝 구조로 버킷에 내보내져요:
<bucket>/<prefix>/export_id=<export_id>/tenant_id=<tenant_id>/session_id=<session_id>/runs/year=<year>/month=<month>/day=<day>
3. 내보내기 모니터링
이전 단계의 id를 사용해 내보내기 상태를 폴링하세요:
curl --request GET \
--url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: ***' \
--header 'X-Tenant-Id: YOUR_WORKSPACE_ID'
응답의 status 필드는 CREATED, RUNNING, COMPLETED, FAILED, CANCELLED 또는 TIMEDOUT 중 하나가 돼요. 데이터 볼륨에 따라 내보내기가 시간이 걸릴 수 있어요. 상태가 COMPLETED가 되면 Parquet 파일이 버킷에서 사용 가능해요.
런 나열, 내보내기 중지, 실패 진단 방법은 대량 내보내기 모니터링 및 문제 해결을 참고하세요.