트레이스 데이터를 BigQuery로 내보내기

GCS로의 벌크 내보내기를 사용해 LangSmith 트레이스 데이터를 BigQuery로 로드할 수 있어요. LangSmith는 트레이스 데이터를 Parquet 형식으로 Google Cloud Storage(GCS) 버킷에 내보낼 수 있습니다. 그런 다음 이를 BigQuery에서 외부 테이블(GCS에서 직접 쿼리) 또는 네이티브 테이블(BigQuery 저장소로 복사)로 로드할 수 있답니다.

출처: 문서

본문

참고: 요금제 제한 적용

2026년 8월 3일 이후 가입한 고객은 LangSmith Enterprise 요금제에서만 벌크 내보내기를 사용할 수 있습니다. 2026년 8월 3일 또는 그 이전에 가입한 고객은 2027년 2월 1일까지 Plus 또는 Enterprise 요금제에서 벌크 내보내기를 사용할 수 있습니다.

LangSmith는 트레이스 데이터를 Parquet 형식으로 Google Cloud Storage(GCS) 버킷에 내보낼 수 있습니다. 그런 다음 GCS에서 그대로 쿼리하는 외부 테이블 또는 BigQuery 저장소로 복사하는 네이티브 테이블로 BigQuery에 로드할 수 있습니다.

이 가이드는 다음을 다룹니다:

LangSmith용 GCS 버킷과 HMAC 자격 증명 설정.
벌크 내보내기 목적지와 내보내기 작업 생성.
내보낸 데이터를 BigQuery로 로드.

벌크 내보내기 구성 옵션에 대한 전체 내용은 트레이스 데이터 벌크 내보내기 및 벌크 내보내기 목적지 관리를 참고하세요.

사전 준비 사항

LangSmith 트레이싱 프로젝트의 데이터.
gcloud CLI 설치. (Google Cloud 콘솔을 사용해 설정할 수도 있습니다.)

1. GCS 버킷 만들기

LangSmith 내보내기를 위한 전용 GCS 버킷을 만듭니다. 전용 버킷을 사용하면 다른 데이터에 영향을 주지 않고 범위가 지정된 권한을 부여하기 쉽습니다:

gcloud storage buckets create gs://YOUR_BUCKET_NAME \
  --location=US \
  --uniform-bucket-level-access

BigQuery 데이터셋과 가까운 지역을 선택해 지연 시간을 최소화하고 지역 간 이그레스 요금을 피하세요.

2. 서비스 계정 생성 및 접근 권한 부여

LangSmith가 GCS에 데이터를 쓰는 데 사용할 GCP 서비스 계정을 만듭니다:

gcloud iam service-accounts create langsmith-bulk-export \
  --display-name="LangSmith Bulk Export"

서비스 계정에 버킷 쓰기 접근 권한을 부여합니다. 최소 필수 권한은 storage.objects.create입니다. storage.objects.delete를 부여하는 것은 선택 사항이지만 권장됩니다. LangSmith는 목적지 검증 중 생성된 임시 테스트 파일을 정리하는 데 이를 사용합니다. 이 권한이 없으면 버킷에 tmp/ 폴더가 남을 수 있습니다.

"Storage Object Admin" 사전 정의 역할이 필수 및 권장 권한을 모두 포함합니다:

gcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET_NAME \
  --member="serviceAccount:langsmith-bulk-export@YOUR_PROJECT.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

대신 최소한의 커스텀 역할을 사용하려면 다음만 부여하세요:

storage.objects.create (필수)
storage.objects.delete (선택, 테스트 파일 정리용)
storage.objects.get (선택이지만 권장, 파일 크기 검증용)
storage.multipartUploads.create (선택이지만 권장, 대용량 파일 업로드용)

3. HMAC 키 생성

LangSmith는 S3 호환 XML API를 사용해 GCS에 연결하므로, 서비스 계정 JSON 키가 아닌 HMAC 키가 필요합니다.

서비스 계정에 대한 HMAC 키를 생성합니다:

gcloud storage hmac create \
  langsmith-bulk-export@YOUR_PROJECT.iam.gserviceaccount.com

출력에서 accessId와 secret을 저장하세요. GCP 콘솔의 Cloud Storage > Settings > Interoperability > Create a key for a service account에서도 HMAC 키를 생성할 수 있습니다.

4. 벌크 내보내기 목적지 만들기

GCS 버킷을 가리키는 목적지를 LangSmith에 만듭니다. GCS S3 호환 API를 사용하려면 endpoint_url을 https://storage.googleapis.com으로 설정하세요.

LangSmith API 키와 워크스페이스 ID가 필요합니다.

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": "GCS for BigQuery",
    "config": {
      "bucket_name": "YOUR_BUCKET_NAME",
      "prefix": "YOUR_PREFIX",
      "endpoint_url": "https://storage.googleapis.com"
    },
    "credentials": {
      "access_key_id": "YOUR_HMAC_ACCESS_ID",
      "secret_access_key": "YOUR_HMAC_SECRET"
    }
  }'

prefix는 LangSmith가 내보낸 파일을 쓸 버킷 내 경로입니다. 예를 들어 langsmith-exports 또는 data/traces입니다. 버킷 레이아웃에 맞는 값을 선택하세요.

LangSmith는 목적지를 저장하기 전에 테스트 쓰기를 수행해 자격 증명을 검증합니다. 요청이 400 오류를 반환하면 목적지 오류 디버깅을 참고하세요.

다음 단계에서 필요하므로 응답에서 id를 저장하세요.

임시 검증 파일

목적지 생성(및 자격 증명 회전) 중 LangSmith는 쓰기 접근을 검증하기 위해 YOUR_PREFIX/tmp/에 임시 .txt 파일을 쓴 다음 삭제를 시도합니다. 삭제는 최선 노력(best-effort)입니다: 서비스 계정에 storage.objects.delete가 없으면 파일이 삭제되지 않고 tmp/ 폴더가 버킷에 남습니다.

tmp/ 폴더는 내보내기에 영향을 주지 않지만, 광범위한 GCS URI glob(예: gs://YOUR_BUCKET_NAME/YOUR_PREFIX/*)에 포함됩니다.

5. 벌크 내보내기 작업 만들기

특정 프로젝트를 대상으로 내보내기를 만듭니다. BigQuery 호환성을 위해 format_version: v2_beta를 사용하세요 — 이는 BigQuery가 올바르게 처리하는 UTC 시간대 인식 타임스탬프를 생성합니다.

Tracing Projects 목록의 프로젝트 뷰에서 복사할 수 있는 프로젝트 ID(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",
    "session_id": "YOUR_PROJECT_ID",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-02-01T00:00:00Z",
    "format_version": "v2_beta",
    "compression": "snappy"
  }'

예약(반복) 내보내기:

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": "YOUR_PROJECT_ID",
    "start_time": "2024-01-01T00:00:00Z",
    "interval_hours": 24,
    "format_version": "v2_beta",
    "compression": "snappy"
  }'

벌크 내보내기는 기본적으로 zstandard 압축을 사용합니다. 이 예시는 Snappy가 빠르고 BigQuery에서 널리 지원되므로 snappy를 설정합니다. 필드 필터링과 필터 표현식을 포함한 모든 옵션은 트레이스 데이터 벌크 내보내기를 참고하세요.

참고: 자체 호스팅 LangSmith에서는 기본값이 gzip입니다. 기본값을 변경하려면 FF_BULK_EXPORT_DEFAULT_COMPRESSION 환경 변수를 설정하세요.

출력 파일 구조

내보낸 파일은 Hive 파티셔닝된 경로 구조를 사용해 GCS에 배치됩니다:

gs://YOUR_BUCKET_NAME/YOUR_PREFIX/export_id=<uuid>/tenant_id=<uuid>/session_id=<uuid>/resource=runs/year=<year>/month=<month>/day=<day>/<filename>.parquet

경로의 파티션 열(export_id, tenant_id, session_id, resource, year, month, day)은 Hive 파티션 감지가 활성화되면 BigQuery에서 쿼리 가능한 열로 사용할 수 있습니다.

6. 데이터를 BigQuery로 로드

BigQuery는 내보낸 데이터에 접근하는 두 가지 방법을 제공합니다. 둘 다 먼저 BigQuery 서비스 계정에 GCS 버킷 읽기 접근 권한을 부여해야 합니다. 필요에 따라 선택하세요:

외부 테이블: 데이터는 GCS에 유지되고 BigQuery가 제자리에서 쿼리합니다. BigQuery 저장 비용은 없지만, 쿼리 성능이 네이티브 저장소보다 느립니다. 필요한 역할 참고.
네이티브 테이블: 데이터를 BigQuery 저장소로 복사합니다. 더 빠른 쿼리와 BigQuery 기능의 전체 지원을 제공하지만 BigQuery 저장 비용이 발생합니다. 필요한 권한 참고.

테이블 만들기

외부 테이블

외부 테이블은 GCS에서 직접 데이터를 쿼리하며 BigQuery로 복사하지 않습니다.

BigQuery 콘솔의 Explorer 창에서 프로젝트와 데이터셋을 펼칩니다.
데이터셋의 Actions 메뉴(점 3개)를 클릭하고 Create table을 선택합니다.
Source 아래:
- Create table from을 Google Cloud Storage로 설정합니다.
- 파일 경로를 gs://YOUR_BUCKET_NAME/YOUR_PREFIX/export_id=*로 설정합니다. export_id=*를 사용하면 BigQuery를 Hive 파티셔닝된 내보내기 디렉터리로 범위를 한정하고, LangSmith가 목적지 검증 중 쓰는 tmp/ 폴더를 제외합니다 (임시 검증 파일 참고).
- File format을 Parquet로 설정합니다.
Source data partitioning을 체크한 다음:
- Source URI prefix를 gs://YOUR_BUCKET_NAME/YOUR_PREFIX로 설정합니다.
- Partition inference mode를 Automatically infer types로 설정합니다.
Destination 아래:
- 프로젝트와 데이터셋을 선택합니다.
- langsmith_runs 같은 테이블 이름을 입력합니다.
- Table type을 External table로 설정합니다.
Schema 아래에서 Auto-detect를 활성화합니다.
Create table을 클릭합니다.

파티션 경로 열(export_id, tenant_id, session_id, resource, year, month, day)은 쿼리 가능한 열로 사용할 수 있습니다. 쿼리에서 year, month 또는 day로 필터링해 파티션 프루닝을 활성화하세요.

네이티브 테이블

네이티브 테이블은 전체 쿼리 성능을 위해 Parquet 데이터를 BigQuery 저장소로 전송합니다.

Google Cloud 콘솔의 Data Transfer 페이지로 이동해 + Create transfer를 선택합니다.
Source type에서 Google Cloud Storage를 선택합니다.
Transfer name을 입력합니다. 필요하면 언제든지 전송을 편집할 수 있습니다.
Schedule option을 선택합니다. 내보내기를 반복하지 않으려면 On demand를 선택하고 수동으로 트리거할 수 있습니다.
BigQuery 콘솔의 Explorer 창에서 프로젝트와 데이터셋을 펼칩니다.
데이터셋의 Actions 메뉴(점 3개)를 클릭하고 Create table을 선택합니다.
Source 아래:
- Create table from을 Google Cloud Storage로 설정합니다.
- 파일 경로를 gs://YOUR_BUCKET_NAME/YOUR_PREFIX/export_id=*로 설정합니다. export_id=*를 사용하면 LangSmith가 목적지 검증 중 쓰는 tmp/ 폴더를 제외합니다 (임시 검증 파일 참고).
- File format을 Parquet로 설정합니다.
Source data partitioning을 체크한 다음:
- Source URI prefix를 gs://YOUR_BUCKET_NAME/YOUR_PREFIX로 설정합니다.
- Partition inference mode를 Automatically infer types로 설정합니다.
Destination 아래:
- 프로젝트와 데이터셋을 선택합니다.
- langsmith_runs 같은 테이블 이름을 입력합니다.
- Table type을 Native table로 설정합니다.
Advanced options 아래에서 새 테이블이면 Write preference를 Write if empty로 설정합니다.
Create table을 클릭합니다.

BigQuery는 데이터를 복사하기 위해 로드 작업을 실행합니다. Hive 파티션 열은 테이블에서 일반 열로 나타납니다. 사용 가능한 전체 데이터 열 목록은 내보내기 가능한 필드를 참고하세요.

자격 증명 회전

활성 내보내기를 중단하지 않고 HMAC 키를 회전하려면:

GCP에서 같은 서비스 계정에 대한 새 HMAC 키를 생성합니다.

새 자격 증명으로 PATCH 엔드포인트를 호출합니다:

curl --request PATCH \
  --url 'https://api.smith.langchain.com/api/v1/bulk-exports/destinations/YOUR_DESTINATION_ID' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: *** \
  --header 'X-Tenant-Id: YOUR_WORKSPACE_ID' \
  --data '{
    "credentials": {
      "access_key_id": "NEW_HMAC_ACCESS_ID",
      "secret_access_key": "NEW_HMAC_SECRET"
    }
  }'

LangSmith는 저장 전에 테스트 쓰기로 새 자격 증명을 검증합니다. 이 검증 중에 버킷에 새 tmp/ 파일이 나타날 수 있습니다 (임시 검증 파일 참고).

진행 중인 모든 내보내기 런이 완료될 때까지 이전 HMAC 키를 활성 상태로 유지합니다. 전환 기간 동안 두 자격 증명 세트가 동시에 유효합니다.
진행 중인 런이 이를 사용하지 않음을 확인한 후 GCP에서 이전 HMAC 키를 삭제합니다.

자세한 내용은 목적지 자격 증명 회전을 참고하세요.

문제 해결

증상	예상 원인	해결책
목적지 생성 시 `400 Access denied`	HMAC 자격 증명에 쓰기 권한 없음	서비스 계정이 버킷에 `storage.objects.create`가 있는지 확인
`400 Key ID you provided does not exist`	HMAC 접근 ID가 유효하지 않음	GCP에서 HMAC 키 재생성
`400 Invalid endpoint`	엔드포인트 URL이 잘못됨	정확히 `https://storage.googleapis.com` 사용
BigQuery 테이블에 행이 없음	내보내기가 아직 완료되지 않음	`GET /api/v1/bulk-exports/{export_id}`로 내보내기 상태 확인
BigQuery 파티션 프루닝이 작동하지 않음	잘못된 소스 URI prefix	소스 URI prefix가 첫 번째 파티션 키 앞에서 끝나는지 확인 (예: `gs://BUCKET/PREFIX`)
BigQuery가 `tmp/` 파일을 감지함	광범위한 파일 경로 glob	파일 경로에 `` 대신 `export_id=` 사용

추가 오류 코드와 내보내기 상태 세부 정보는 벌크 내보내기 모니터링 및 문제 해결을 참고하세요.

더 알아보기

벌크 내보내기 옵션 전체는 Bulk export trace data 문서를 참고하세요.
목적지 관리 및 자격 증명 회전은 Manage bulk export destinations 문서를 확인해 보세요.