본문으로 건너뛰기
버전: Next

Traces API

Traces API는 파이프라인 실행 이력을 조회하는 API입니다. 분산 트레이싱으로 수집된 데이터를 검색하여 파이프라인의 실행 상태, 소요 시간, 개별 스텝 결과를 확인할 수 있습니다.

트레이스 검색 엔진

Traces API는 내부 트레이스 검색 엔진을 백엔드로 사용합니다. 검색 엔진이 설정되지 않은 환경에서는 503 Service Unavailable 응답이 반환됩니다.

엔드포인트​

MethodPathDescription
GET/traces/pipelines/{pipeline_id}파이프라인 최신 트레이스 조회
GET/traces/pipelines/{pipeline_id}/파이프라인 트레이스 이력 목록
GET/traces/pipelines/{pipeline_id}/{batch_id}특정 배치의 트레이스 조회
GET/traces/steps/{batch_id}배치 내 스텝별 트레이스 조회

GET /traces/pipelines/{pipeline_id}​

해당 파이프라인의 가장 최근 실행 트레이스를 조회합니다.

Path Parameters​

ParameterTypeDescription
pipeline_idstring파이프라인 ID

Response​

200 OK

{
  "id": "batch-20240615-001",
  "name": "daily-etl",
  "deployment": "daily-etl/run-20240615",
  "state": {
    "state": "completed",
    "steps": {
      "extract": {
        "state": "completed",
        "offsets": {"records": 1000},
        "comment": null,
        "stacktrace": null,
        "start_time": 1718448000000,
        "end_time": 1718448060000
      },
      "transform": {
        "state": "completed",
        "offsets": {"records": 950},
        "comment": null,
        "stacktrace": null,
        "start_time": 1718448060000,
        "end_time": 1718448120000
      }
    }
  },
  "start_time": 1718448000000,
  "end_time": 1718448120000
}

404 Not Found — 해당 파이프라인의 트레이스가 없는 경우

GET /traces/pipelines/{pipeline_id}/​

파이프라인의 전체 실행 이력을 조회합니다. 시작 시간 내림차순으로 정렬됩니다.

Query Parameters​

ParameterTypeDefaultDescription
limitinteger100최대 조회 개수 (최대 1000)

Response​

200 OK

{
  "items": {
    "batch-20240615-001": {
      "id": "batch-20240615-001",
      "name": "daily-etl",
      "deployment": "daily-etl/run-20240615",
      "state": { ... },
      "start_time": 1718448000000,
      "end_time": 1718448120000
    },
    "batch-20240614-001": {
      "id": "batch-20240614-001",
      "name": "daily-etl",
      "deployment": "daily-etl/run-20240614",
      "state": { ... },
      "start_time": 1718361600000,
      "end_time": 1718361720000
    }
  },
  "token": null
}

GET /traces/pipelines/{pipeline_id}/{batch_id}​

특정 배치 ID로 파이프라인 실행 트레이스를 조회합니다.

Path Parameters​

ParameterTypeDescription
pipeline_idstring파이프라인 ID
batch_idstring배치 ID

Response​

응답 형식은 최신 트레이스 조회와 동일합니다.

GET /traces/steps/{batch_id}​

특정 배치의 개별 스텝 실행 트레이스를 조회합니다. 스텝별 세부 정보를 확인할 때 사용합니다.

Path Parameters​

ParameterTypeDescription
batch_idstring배치 ID

Query Parameters​

ParameterTypeRequiredDescription
step_namestringNo특정 스텝만 필터링

Response​

200 OK

[
  {
    "span_id": "abc123",
    "span_name": "pipeline.step",
    "span_attributes": {
      "pipeline.step.name": "extract",
      "pipeline.batch.id": "batch-20240615-001"
    },
    "span_start_timestamp_nanos": 1718448000000000000,
    "span_end_timestamp_nanos": 1718448060000000000,
    "span_status": "OK"
  }
]

사용 예시​

# 파이프라인 최신 실행 결과 조회
curl https://api.dhub.io/api/v1/traces/pipelines/pipeline-abc123 \
  -H "Authorization: Bearer <access_token>"

# 실행 이력 목록 (최근 10건)
curl "https://api.dhub.io/api/v1/traces/pipelines/pipeline-abc123/?limit=10" \
  -H "Authorization: Bearer <access_token>"

# 특정 배치의 스텝별 상세 조회
curl https://api.dhub.io/api/v1/traces/steps/batch-20240615-001 \
  -H "Authorization: Bearer <access_token>"
파이프라인 디버깅

트레이스에서 state가 failed인 스텝을 찾아 stacktrace 필드를 확인하면 에러 원인을 빠르게 파악할 수 있습니다. 자세한 디버깅 방법은 파이프라인 디버깅 가이드를 참조하세요.