트레이스 데이터 대량 내보내기

플랜 제한 사항데이터 내보내기 기능은 LangSmith Plus 또는 Enterprise 티어에서만 지원됩니다.

LangSmith의 대량 데이터 내보내기 기능을 사용하면 트레이스를 외부 목적지로 내보낼 수 있습니다. BigQuery, Snowflake, RedShift, Jupyter Notebooks 등의 도구에서 데이터를 오프라인으로 분석하고자 할 때 유용합니다. 내보내기는 특정 LangSmith 프로젝트와 날짜 범위를 대상으로 시작할 수 있습니다. 배치 내보내기가 시작되면 시스템이 내보내기 프로세스의 오케스트레이션과 복원력을 처리합니다. 데이터 내보내기는 데이터 크기에 따라 시간이 걸릴 수 있습니다. 또한 동시에 실행할 수 있는 내보내기 수에도 제한이 있습니다. 대량 내보내기는 24시간의 런타임 타임아웃이 있습니다.

목적지

현재 사용자가 제공하는 S3 버킷 또는 S3 API 호환 버킷으로의 내보내기를 지원합니다. 데이터는 Parquet 컬럼 형식으로 내보내집니다. 이 형식을 사용하면 다른 시스템으로 데이터를 쉽게 가져올 수 있습니다. 데이터 내보내기에는 Run 데이터 형식과 동일한 데이터 필드가 포함됩니다.

데이터 내보내기

목적지 - S3 버킷 제공

LangSmith 데이터를 내보내려면 데이터를 내보낼 S3 버킷을 제공해야 합니다. 내보내기에는 다음 정보가 필요합니다:

Bucket Name: 데이터를 내보낼 S3 버킷의 이름입니다.
Prefix: 버킷 내에서 데이터를 내보낼 루트 접두사입니다.
S3 Region: 버킷의 리전입니다 - AWS S3 버킷에 필요합니다.
Endpoint URL: S3 버킷의 엔드포인트 URL입니다 - S3 API 호환 버킷에 필요합니다.
Access Key: S3 버킷의 액세스 키입니다.
Secret Key: S3 버킷의 시크릿 키입니다.

GCS 또는 MinIO와 같은 AWS가 아닌 버킷을 포함한 모든 S3 호환 버킷을 지원하며, 이 경우 엔드포인트 URL을 제공해야 합니다.

목적지 준비

자체 호스팅 및 EU 리전 배포의 경우아래 요청에서 자체 호스팅 설치 또는 EU 리전 조직에 맞게 LangSmith URL을 적절히 업데이트하세요. EU 리전의 경우 eu.api.smith.langchain.com을 사용하세요.

필요한 권한backend 및 queue 서비스 모두 목적지 버킷에 대한 쓰기 액세스 권한이 필요합니다:

backend 서비스는 내보내기 목적지가 생성될 때 목적지 버킷에 테스트 파일을 쓰려고 시도합니다. 권한이 있는 경우 테스트 파일을 삭제합니다(삭제 액세스는 선택 사항입니다).
queue 서비스는 대량 내보내기 실행을 담당하며 파일을 버킷에 업로드합니다.

다음 예제는 cURL을 사용하여 목적지를 생성하는 방법을 보여줍니다. 플레이스홀더 값을 실제 구성 세부 정보로 바꾸세요. 자격 증명은 시스템에 암호화된 형태로 안전하게 저장됩니다.

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_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"
    }
  }'

반환된 id를 사용하여 후속 대량 내보내기 작업에서 이 목적지를 참조하세요. 목적지 생성 중 오류가 발생하면 목적지 오류 디버깅에서 디버깅 방법을 확인하세요.

자격 증명 구성

LangSmith Helm 버전 >= 0.10.34 (애플리케이션 버전 >= 0.10.91) 필요

정적 access_key_id 및 secret_access_key 외에도 다음과 같은 추가 자격 증명 형식을 지원합니다:

AWS 세션 토큰을 포함하는 임시 자격 증명을 사용하려면 대량 내보내기 목적지를 생성할 때 credentials.session_token 키를 추가로 제공하세요.
(자체 호스팅 전용): AWS IAM Roles for Service Accounts (IRSA)와 같은 환경 기반 자격 증명을 사용하려면 대량 내보내기 목적지를 생성할 때 요청에서 credentials 키를 생략하세요. 이 경우 라이브러리에서 정의한 순서대로 표준 Boto3 자격 증명 위치를 확인합니다.

AWS S3 버킷

AWS S3의 경우 endpoint_url을 생략하고 버킷의 리전과 일치하는 리전을 제공할 수 있습니다.

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My AWS S3 Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "region": "us-east-1"
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

Google GCS XML S3 호환 버킷

Google의 GCS 버킷을 사용할 때는 XML S3 호환 API를 사용해야 하며, 일반적으로 https://storage.googleapis.com인 endpoint_url을 제공해야 합니다. 다음은 S3와 호환되는 GCS XML API를 사용할 때의 API 요청 예시입니다:

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "destination_type": "s3",
    "display_name": "My GCS Destination",
    "config": {
      "bucket_name": "my_bucket",
      "prefix": "data_exports",
      "endpoint_url": "https://storage.googleapis.com"
    },
    "credentials": {
      "access_key_id": "YOUR_S3_ACCESS_KEY_ID",
      "secret_access_key": "YOUR_S3_SECRET_ACCESS_KEY"
    }
  }'

자세한 내용은 Google 문서를 참조하세요.

내보내기 작업 생성

데이터를 내보내려면 내보내기 작업을 생성해야 합니다. 이 작업은 목적지, 프로젝트, 날짜 범위 및 내보낼 데이터의 필터 표현식을 지정합니다. 필터 표현식은 내보낼 실행 세트를 좁히는 데 사용되며 선택 사항입니다. 필터 필드를 설정하지 않으면 모든 실행을 내보냅니다. 내보내기에 적합한 필터 표현식을 결정하려면 필터 쿼리 언어 및 예제를 참조하세요. 다음 cURL 명령을 사용하여 작업을 생성할 수 있습니다:

curl --request POST \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_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-02T23:59:59Z",
    "filter": "and(eq(run_type, \"llm\"), eq(name, \"ChatOpenAI\"), eq(input_key, \"messages.content\"), like(input_value, \"%messages.content%\"))"
  }'

session_id는 트레이싱 프로젝트 ID라고도 하며, 트레이싱 프로젝트 목록에서 프로젝트를 클릭하여 개별 프로젝트 보기에서 복사할 수 있습니다.

반환된 id를 사용하여 후속 대량 내보내기 작업에서 이 내보내기를 참조하세요.

예약된 내보내기

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: YOUR_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",
    "filter": "and(eq(run_type, \"llm\"), eq(name, \"ChatOpenAI\"), eq(input_key, \"messages.content\"), like(input_value, \"%messages.content%\"))",
    "interval_hours": 1
  }'

세부 정보

interval_hours는 1시간에서 168시간(1주) 사이여야 합니다.
생성된 내보내기의 경우 처음 내보내는 시간 범위는 start_time=(scheduled_export_start_time), end_time=(start_time + interval_hours)입니다. 그 다음은 start_time=(previous_export_end_time), end_time=(this_export_start_time + interval_hours) 등으로 진행됩니다.
예약된 내보내기에는 end_time을 생략해야 합니다. 예약되지 않은 내보내기에는 여전히 end_time이 필요합니다.
예약된 내보내기는 내보내기 중지를 통해 중지할 수 있습니다.
- 예약된 내보내기에 의해 생성된 내보내기는 source_bulk_export_id 속성이 채워져 있습니다.
- 필요한 경우 이러한 생성된 대량 내보내기는 소스 예약 대량 내보내기와 별도로 취소해야 합니다 - 소스 대량 내보내기를 취소해도 생성된 대량 내보내기는 취소되지 않습니다.
생성된 내보내기는 최근 과거의 end_time으로 제출된 실행을 고려하기 위해 end_time + 10분에 실행됩니다.

예시 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

내보내기 작업 모니터링

내보내기 상태 모니터링

내보내기 작업의 상태를 모니터링하려면 다음 cURL 명령을 사용하세요:

curl --request GET \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID'

{export_id}를 모니터링하려는 내보내기의 ID로 바꾸세요. 이 명령은 지정된 내보내기 작업의 현재 상태를 검색합니다.

내보내기에 대한 실행 목록 조회

내보내기는 일반적으로 내보낼 특정 날짜 파티션에 해당하는 여러 실행으로 나뉩니다. 특정 내보내기와 관련된 모든 실행을 나열하려면 다음 cURL 명령을 사용하세요:

curl --request GET \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}/runs' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID'

이 명령은 지정된 내보내기와 관련된 모든 실행을 가져와서 실행 ID, 상태, 생성 시간, 내보낸 행 수 등의 세부 정보를 제공합니다.

모든 내보내기 목록 조회

모든 내보내기 작업 목록을 검색하려면 다음 cURL 명령을 사용하세요:

curl --request GET \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID'

이 명령은 현재 상태 및 생성 타임스탬프와 함께 모든 내보내기 작업 목록을 반환합니다.

내보내기 중지

기존 내보내기를 중지하려면 다음 cURL 명령을 사용하세요:

curl --request PATCH \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/{export_id}' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "status": "Cancelled"
}'

{export_id}를 취소하려는 내보내기의 ID로 바꾸세요. 작업이 취소되면 다시 시작할 수 없으므로 대신 새 내보내기 작업을 생성해야 합니다.

파티셔닝 체계

데이터는 다음 Hive 파티션 형식으로 버킷에 내보내집니다:

<bucket>/<prefix>/export_id=<export_id>/tenant_id=<tenant_id>/session_id=<session_id>/runs/year=<year>/month=<month>/day=<day>

다른 시스템으로 데이터 가져오기

S3 및 Parquet 형식에서 데이터를 가져오는 것은 대부분의 분석 시스템에서 일반적으로 지원됩니다. 문서 링크는 아래를 참조하세요:

BigQuery

데이터를 BigQuery로 가져오려면 Parquet에서 데이터 로드 및 Hive 파티션 로드를 참조하세요.

Snowflake

클라우드에서 로드 문서를 따라 S3에서 Snowflake로 데이터를 로드할 수 있습니다.

RedShift

AWS COPY 명령 문서를 따라 S3 또는 Parquet에서 Amazon Redshift로 데이터를 COPY할 수 있습니다.

Clickhouse

Clickhouse에서 S3 / Parquet 형식의 데이터를 직접 쿼리할 수 있습니다. 예를 들어 GCS를 사용하는 경우 다음과 같이 데이터를 쿼리할 수 있습니다:

SELECT count(distinct id) FROM s3('https://storage.googleapis.com/<bucket>/<prefix>/export_id=<export_id>/**',
 'access_key_id', 'access_secret', 'Parquet')

자세한 내용은 Clickhouse S3 통합 문서를 참조하세요.

DuckDB

DuckDB를 사용하여 S3의 데이터를 SQL로 메모리 내에서 쿼리할 수 있습니다. S3 가져오기 문서를 참조하세요.

오류 처리

목적지 오류 디버깅

목적지 API 엔드포인트는 목적지와 자격 증명이 유효하고 버킷에 대한 쓰기 액세스 권한이 있는지 확인합니다. 오류가 발생하여 이 오류를 디버깅하려면 AWS CLI를 사용하여 버킷에 대한 연결을 테스트할 수 있습니다. 위의 목적지 API에 제공한 것과 동일한 데이터를 사용하여 CLI로 파일을 작성할 수 있어야 합니다. AWS S3:

aws configure

# 목적지에 사용한 것과 동일한 액세스 키 자격 증명 및 리전 설정
> AWS Access Key ID: <access_key_id>
> AWS Secret Access Key: <secret_access_key>
> Default region name [us-east-1]: <region>

# 버킷 나열
aws s3 ls /

# 쓰기 권한 테스트
touch ./test.txt
aws s3 cp ./test.txt s3://<bucket-name>/tmp/test.txt

GCS 호환 버킷: --endpoint-url 옵션으로 endpoint_url을 제공해야 합니다. GCS의 경우 endpoint_url은 일반적으로 https://storage.googleapis.com입니다:

aws configure

# 목적지에 사용한 것과 동일한 액세스 키 자격 증명 및 리전 설정
> AWS Access Key ID: <access_key_id>
> AWS Secret Access Key: <secret_access_key>
> Default region name [us-east-1]: <region>

# 버킷 나열
aws s3 --endpoint-url=<endpoint_url> ls /

# 쓰기 권한 테스트
touch ./test.txt
aws s3 --endpoint-url=<endpoint_url> cp ./test.txt s3://<bucket-name>/tmp/test.txt

실행 모니터링

실행 목록 API를 사용하여 실행을 모니터링할 수 있습니다. 알려진 오류인 경우 실행의 errors 필드에 추가됩니다.

일반적인 오류

다음은 일반적인 오류입니다:

오류	설명
Access denied	Blob 저장소 자격 증명 또는 버킷이 유효하지 않습니다. 이 오류는 제공된 액세스 키와 시크릿 키 조합이 지정된 버킷에 액세스하거나 필요한 작업을 수행하는 데 필요한 권한이 없을 때 발생합니다.
Bucket is not valid	지정된 Blob 저장소 버킷이 유효하지 않습니다. 이 오류는 버킷이 존재하지 않거나 버킷에 대한 쓰기를 수행할 수 있는 충분한 액세스 권한이 없을 때 발생합니다.
Key ID you provided does not exist	제공된 Blob 저장소 자격 증명이 유효하지 않습니다. 이 오류는 인증에 사용된 액세스 키 ID가 유효한 키가 아닐 때 발생합니다.
Invalid endpoint	제공된 endpoint_url이 유효하지 않습니다. 이 오류는 지정된 엔드포인트가 유효하지 않은 엔드포인트일 때 발생합니다. S3 호환 엔드포인트만 지원됩니다. 예를 들어 GCS의 경우 `https://storage.googleapis.com`, MinIO의 경우 `https://play.min.io` 등입니다. AWS를 사용하는 경우 endpoint_url을 생략해야 합니다.

Edit the source of this page on GitHub.

Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.

Tracing setup

Configuration & troubleshooting

Viewing & managing traces

Automations

Feedback & evaluation

Monitoring & alerting

Data type reference

트레이스 데이터 대량 내보내기

목적지

데이터 내보내기

목적지 - S3 버킷 제공

목적지 준비

자격 증명 구성

AWS S3 버킷

Google GCS XML S3 호환 버킷

내보내기 작업 생성

예약된 내보내기

내보내기 작업 모니터링

내보내기 상태 모니터링

내보내기에 대한 실행 목록 조회

모든 내보내기 목록 조회

내보내기 중지

파티셔닝 체계

다른 시스템으로 데이터 가져오기

BigQuery

Snowflake

RedShift

Clickhouse

DuckDB

오류 처리

목적지 오류 디버깅

실행 모니터링

일반적인 오류

Tracing setup

Configuration & troubleshooting

Viewing & managing traces

Automations

Feedback & evaluation

Monitoring & alerting

Data type reference

​목적지

​데이터 내보내기

​목적지 - S3 버킷 제공

​목적지 준비

​자격 증명 구성

​AWS S3 버킷

​Google GCS XML S3 호환 버킷

​내보내기 작업 생성

​예약된 내보내기

​내보내기 작업 모니터링

​내보내기 상태 모니터링

​내보내기에 대한 실행 목록 조회

​모든 내보내기 목록 조회

​내보내기 중지

​파티셔닝 체계

​다른 시스템으로 데이터 가져오기

​BigQuery

​Snowflake

​RedShift

​Clickhouse

​DuckDB

​오류 처리

​목적지 오류 디버깅

​실행 모니터링

​일반적인 오류

목적지

데이터 내보내기

목적지 - S3 버킷 제공

목적지 준비

자격 증명 구성

AWS S3 버킷

Google GCS XML S3 호환 버킷

내보내기 작업 생성

예약된 내보내기

내보내기 작업 모니터링

내보내기 상태 모니터링

내보내기에 대한 실행 목록 조회

모든 내보내기 목록 조회

내보내기 중지

파티셔닝 체계

다른 시스템으로 데이터 가져오기

BigQuery

Snowflake

RedShift

Clickhouse

DuckDB

오류 처리

목적지 오류 디버깅

실행 모니터링

일반적인 오류