추적 데이터의 스토리지 스키마

이 문서에서는 트레이스 스팬이 저장되는 형식을 설명합니다. 데이터 형식은 일반적으로 OpenTelemetry OTLP 프로토콜에서 정의한 proto 파일과 일치합니다. 하지만 필드는 저장 전에 OpenTelemetry 전용 데이터 유형에서 JSON 데이터 유형으로 변환될 수 있습니다.

원격 분석 API는 OpenTelemetry OTLP 프로토콜을 사용합니다. 이 프로토콜은 trace_service.proto 및 trace.proto 파일을 사용합니다. 필드 한도에 관한 자세한 내용은 원격 분석 API 한도를 참고하세요.

Cloud Trace API는 OpenTelemetry OTLP 프로토콜을 사용하지 않으며 독점 데이터 형식을 정의합니다. 이 API를 통해 Google Cloud 프로젝트로 전송된 추적 데이터는 이 문서에 설명된 형식으로 변환됩니다. 하지만 Cloud Trace API의 한도는 적용됩니다.

범위 스토리지 형식

필드	설명
trace_id	string 트레이스의 전역 고유 식별자입니다. 이 식별자는 16바이트 16진수 문자열로 형식이 지정된 128비트 숫자 값입니다. 예를 들면 382d4f4c6b7bb2f4a972559d9085001d입니다. 이 식별자에 대해 자세히 알아보려면 W3C trace-id을 참고하세요. 숫자 값 0은 유효하지 않습니다. trace_id는 시각화 및 분석 도구에서 트레이스와 연결된 스팬을 식별하는 데 사용됩니다. 따라서 모든 엔드 투 엔드 작업에는 고유 식별자가 있어야 합니다. 트레이스 식별자를 재사용하지 마세요.
span_id	string 필수 항목입니다. 스팬의 식별자입니다. 트레이스 내에서 고유해야 합니다. 이 식별자는 8바이트 16진수 문자열로 형식이 지정된 64비트 숫자 값입니다. 예를 들면 9046a5b9f7c12500입니다. 숫자 값 0은 유효하지 않습니다.
trace_state	string 이 필드는 W3C 추적 컨텍스트에 정의된 대로 tracestate 헤더에 해당합니다. 이 헤더에는 애플리케이션이 트레이스 데이터를 수집하도록 계측될 때 요청에 포함되는 구성 정보가 포함되어 있습니다. 예를 들어 애플리케이션은 확률 샘플링 설정을 지정하거나 공급업체별 콘텐츠를 포함할 수 있습니다. OpenTelemetry 라이브러리는 스팬을 생성할 때 tracestate 헤더의 값을 자동으로 기록합니다.
parent_span_id	string 선택사항입니다. 이 스팬을 호출한 작업을 식별합니다. '루트' 스팬의 상위 스팬 ID는 null로 설정됩니다. 스팬 간의 상위-하위 관계는 시각화 도구에서 트리 구조를 구성하는 데 사용됩니다.
name	string 필수 항목입니다. 실행된 작업의 이름입니다. 이름은 메서드 이름 또는 기타 호출별 사이트 이름일 수 있습니다. 동일한 실행 파일과 동일한 엔드포인트의 경우 일관된 이름을 사용하면 교차 추적 스팬을 더 쉽게 상호 연관시킬 수 있습니다. 권장사항은 스팬 이름 지정 방법을 참고하세요. 스팬 이름은 정리되어 Google Cloud 콘솔에 표시됩니다.
kind	integer 작업이 시스템의 어디에서 발생했는지 지정합니다. 값은 OpenTelemetry: Span Kind 열거형에 해당합니다. 값 OpenTelemetry 열거 0 SPAN_KIND_UNSPECIFIED 1 SPAN_KIND_INTERNAL 2 SPAN_KIND_SERVER 3 SPAN_KIND_CLIENT 4 SPAN_KIND_PRODUCER 5 SPAN_KIND_CONSUMER
start_time	Timestamp 필수 항목입니다. 스팬의 시작 시간(가장 가까운 나노초)입니다.
start_time_unix_nano	integer 시작 시간(나노초 단위, UNIX 에포크 기준)입니다.
end_time	Timestamp 필수 항목입니다. 스팬의 종료 시간입니다(가장 가까운 나노초).
end_time_unix_nano	integer UNIX epoch에 따른 종료 시간(나노초)입니다.
receive_time	Timestamp 필수 항목입니다. 스팬의 수신 시간(가장 가까운 나노초)입니다.
receive_time_unix_nano	integer UNIX epoch에 따른 종료 시간(나노초)입니다.
duration_unix_nano	integer 지속 시간(나노초)입니다.
attributes	JSON type 각 속성은 키-값 쌍입니다. 사용 가능한 속성은 추적 데이터에 따라 다릅니다. 속성 구조는 OpenTelemetry 표준을 따릅니다. 자세한 내용은 OpenTelemetry: 속성을 참고하세요. OpenTelemetry는 속성의 시맨틱 규칙을 지정합니다. 이러한 규칙에 대해 자세히 알아보려면 트레이스 시맨틱 규칙을 참고하세요. 다음은 속성의 예입니다. "yourcompany.your.own.key": "your own value" "network.protocol.name": "http" "network.protocol.version": "1.1" "http.response.status_code": "200" "network.peer.address": "REDACTED"
dropped_attributes_count	integer 삭제된 속성 수입니다. 키가 너무 길거나 속성이 너무 많으면 속성이 삭제될 수 있습니다. 이 값이 0이면 삭제된 속성이 없습니다. 이 값은 클라이언트 측 계측 또는 애플리케이션에 의해 설정될 수 있습니다. 이 값은 서버에서 증가시킬 수 있습니다.
events	반복되는 필드가 있는 record 특정 시점 이벤트입니다. 각 이벤트에는 다음 필드가 포함됩니다. 필드 설명 time Timestamp time_unix_nano integer name string 필수 항목입니다. 이벤트 이름입니다. attributes JSON type 각 속성은 키-값 쌍입니다. 사용 가능한 속성은 추적 데이터에 따라 다릅니다. 속성 구조는 OpenTelemetry 표준을 따릅니다. 자세한 내용은 OpenTelemetry: 속성을 참고하세요. dropped_attributes_count integer 삭제된 속성 수입니다. 키가 너무 길거나 속성이 너무 많으면 속성이 삭제될 수 있습니다. 이 값이 0이면 삭제된 속성이 없습니다. 이 값은 클라이언트 측 계측 또는 애플리케이션에 의해 설정될 수 있습니다. 이 값은 서버에서 증가시킬 수 있습니다.
dropped_events_count	integer 삭제된 이벤트 수입니다. 이벤트가 너무 많아 이벤트가 삭제될 수 있습니다. 이 값이 0이면 삭제된 이벤트가 없습니다.
links	반복되는 필드가 있는 record 스팬과 연결된 링크입니다. 링크는 이 스팬에서 동일하거나 다른 트레이스의 다른 스팬으로의 참조입니다. 링크는 한 트레이스의 스팬을 다른 트레이스의 스팬과 연관시키는 메커니즘을 제공합니다. 예를 들어 한 작업으로 인해 비동기 작업이 발생한다고 가정해 보겠습니다. 이 시나리오에서는 원래 작업과 비동기 작업에 대한 두 개의 트레이스가 있습니다. 링크를 사용하여 이러한 트레이스의 스팬을 상호 연관시킬 수 있습니다. 각 링크에는 다음 필드가 포함됩니다. 필드 설명 trace_id string 필수 항목입니다. span_id string 필수 항목입니다. trace_state string attributes JSON type 각 속성은 키-값 쌍입니다. 사용 가능한 속성은 추적 데이터에 따라 다릅니다. 속성 구조는 OpenTelemetry 표준을 따릅니다. 자세한 내용은 OpenTelemetry: 속성을 참고하세요. dropped_attributes_count integer 삭제된 속성 수입니다. 키가 너무 길거나 속성이 너무 많으면 속성이 삭제될 수 있습니다. 이 값이 0이면 삭제된 속성이 없습니다. 이 값은 클라이언트 측 계측 또는 애플리케이션에 의해 설정될 수 있습니다. 이 값은 서버에서 증가시킬 수 있습니다.
dropped_links_count	integer 삭제된 링크 수입니다. 링크가 너무 많아 링크가 삭제될 수 있습니다. 이 값이 0이면 삭제된 링크가 없습니다.
status	반복 필드가 없는 record 이 필드는 스팬의 완료 상태를 기록합니다. code 하위 필드의 값은 OpenTelemetry: Span Status 열거형에 해당합니다. 값 OpenTelemetry 열거형 설명 0 UNSET 작업이 완료되었습니다. 1 OK 작업이 사람이 오류가 없는 것으로 표시했습니다. 2 ERROR 작업이 완료되었으나 오류가 발생했습니다. 예를 들어 클라이언트 스팬의 상태가 400 (잘못된 요청)인 경우 이 필드는 ERROR로 설정됩니다. 문자열로 형식이 지정된 message 하위 필드에는 오류 정보가 포함됩니다.
resource	반복 필드가 없는 record 이 필드는 원격 분석이 수집되었거나 원격 분석과 관련된 인프라 또는 호스팅 시스템을 식별합니다. 예를 들어 Google Kubernetes Engine에서 실행되는 애플리케이션을 생각해 보겠습니다. 이 리소스의 속성에는 프로세스 이름과 네임스페이스가 포함될 수 있습니다. 이 필드에는 다음 하위 필드가 포함됩니다. 필드 설명 attributes JSON type 각 속성은 키-값 쌍입니다. 사용 가능한 속성은 추적 데이터에 따라 다릅니다. 속성 구조는 OpenTelemetry 표준을 따릅니다. 자세한 내용은 OpenTelemetry: 속성을 참고하세요. 다음은 리소스 속성의 예시입니다. cloud.account.id: "my-project" cloud.platform: "gcp_kubernetes_engine" cloud.provider: "gcp" cloud.region: "us-central1" gcp.project_id: "my-project" host.id: "REDACTED" host.name: "gke-otel-demo" k8s.cluster.name: "otel-demo" k8s.deployment.name: "otel-demo-frontendproxy" dropped_attributes_count integer 삭제된 속성 수입니다. 키가 너무 길거나 속성이 너무 많으면 속성이 삭제될 수 있습니다. 이 값이 0이면 삭제된 속성이 없습니다. 이 값은 클라이언트 측 계측 또는 애플리케이션에 의해 설정될 수 있습니다. 이 값은 서버에서 증가시킬 수 있습니다. 자세한 내용은 OpenTelemetry: 리소스를 참고하세요.
instrumentation_scope	반복 필드가 없는 record 이 필드는 원격 분석을 수집하는 지정된 resource의 라이브러리 또는 애플리케이션 구성요소를 식별합니다. 스팬은 리소스 내에서 해당 범위, 즉 라이브러리 또는 구성요소를 통과하는 특정 작업을 나타냅니다. 예를 들어 'checkout-service' 애플리케이션이 Cloud Run에 배포되었다고 가정해 보겠습니다. 즉, resource가 특정 Cloud Run 인스턴스입니다. 또한 리소스에 'request-authorization-library' 및 'payment-processor-library'와 같은 여러 계측 범위가 있다고 가정합니다. 'WritePaymentInfoToStripe'와 같은 클라이언트 스팬은 'checkout-service'라는 Cloud Run 서비스 내에 있는 'payment-processor-library'에서 보고하는 스팬일 수 있습니다. 이 필드에는 다음 하위 필드가 포함됩니다. 필드 설명 name string version string attributes JSON type 각 속성은 키-값 쌍입니다. 사용 가능한 속성은 추적 데이터에 따라 다릅니다. 속성 구조는 OpenTelemetry 표준을 따릅니다. 자세한 내용은 OpenTelemetry: 속성을 참고하세요. dropped_attributes_count integer 삭제된 속성 수입니다. 키가 너무 길거나 속성이 너무 많으면 속성이 삭제될 수 있습니다. 이 값이 0이면 삭제된 속성이 없습니다. 이 값은 클라이언트 측 계측 또는 애플리케이션에 의해 설정될 수 있습니다. 이 값은 서버에서 증가시킬 수 있습니다. 자세한 내용은 OpenTelemetry: 계측 범위를 참고하세요.
resource_schema_link	string 이러한 필드는 문자열 형식의 URL이어야 합니다. 이러한 필드에는 리소스의 스키마 파일을 반환하는 URL이 포함됩니다. 스키마 파일 및 데이터 형식은 OpenTelemetry에 의해 정의됩니다. 자세한 내용은 OpenTelemetry: 스키마를 참고하세요. 이 필드는 Telemetry API를 사용하는 경우에만 설정할 수 있습니다. 이 API는 데이터가 선언된 스키마를 준수하는지 검사하지 않습니다.
scope_schema_link	string 이러한 필드는 문자열 형식의 URL이어야 합니다. 이러한 필드에는 범위의 스키마 파일을 반환하는 URL이 포함되어 있습니다. 스키마 파일 및 데이터 형식은 OpenTelemetry에 의해 정의됩니다. 자세한 내용은 OpenTelemetry: 스키마를 참고하세요. 이 필드는 Telemetry API를 사용하는 경우에만 설정할 수 있습니다. 이 API는 데이터가 선언된 스키마를 준수하는지 검사하지 않습니다.
apphub	반복 필드가 없는 record 애플리케이션별 라벨은 App Hub 애플리케이션에서 트레이스 스팬을 생성하고 해당 애플리케이션이 지원되는 인프라에서 실행되거나 계측된 경우에 사용할 수 있습니다. 애플리케이션 모니터링 및 이러한 라벨을 사용할 수 있는 시기에 대한 자세한 내용은 애플리케이션 모니터링 개요를 참고하세요. 이 필드에는 application, service, workload 하위 필드가 포함됩니다. 애플리케이션 하위 필드 설명 container string location string id string 서비스/워크로드 하위 필드 설명 id string environment_type string criticality_type string