Trace 컨텍스트

Trace 컨텍스트 및 컨텍스트 전파 는 Cloud Trace가 개별 스팬을 완전한 엔드 투 엔드 분산 trace로 연결할 수 있도록 작업과 서비스 간에 메타데이터를 전달하는 데 사용되는 메커니즘입니다.

애플리케이션이 요청을 처리하고 다운스트림 서비스를 호출할 때 요청 헤더 또는 메타데이터를 사용하여 trace ID, 상위 스팬 ID, 샘플링 상태와 같은 식별자를 전달합니다. 하위 작업은 이 컨텍스트를 사용하여 새 스팬에서 다음 필드를 채웁니다.

  • 스팬 ID: 하위 작업의 고유 식별자입니다. 작업이 여러 번 실행되면 각 호출은 고유한 스팬 ID로 스팬을 생성합니다.
  • 추적 ID: 상위 요소에서 제공하는 전체 엔드 투 엔드 요청의 고유 식별자입니다.
  • 상위 스팬 ID: 호출하는 상위 스팬의 고유 식별자입니다. 이 필드는 루트 스팬의 경우 null입니다.

Cloud Trace는 이러한 공유 식별자를 사용하여 실행 계층 구조를 재구성하고 참여하는 모든 서비스에서 지연 시간을 측정합니다. 컨텍스트 에는 요청이 샘플링되었는지 여부와 같은 추가 상태 정보도 포함될 수 있습니다.

컨텍스트 전파 프로토콜

다음 섹션에서는 특정 요청 프로토콜이 컨텍스트를 전파하는 방법을 설명합니다.

HTTP 요청

HTTP 요청의 경우 컨텍스트 전파는 일반적으로 traceparent 및 tracestate 헤더와 같은 HTTP 헤더를 통해 수행됩니다. 이는 W3C에서 표준화되었습니다. traceparent 헤더에는 요청을 고유하게 식별하는 식별자가 포함되어 있습니다. 반면 tracestate 헤더는 선택사항이며 벤더별 메타데이터가 포함되어 있습니다.

traceparent 헤더의 형식은 다음과 같습니다.

traceparent: VERSION-TRACE_ID-PARENT_SPAN_ID-TRACE_FLAGS

traceparent 헤더의 필드는 다음과 같이 정의됩니다.

  • VERSION은 헤더 버전입니다. 00이어야 합니다.
  • TRACE_ID는 128비트 숫자를 나타내는 32자 16진수 값입니다.
  • PARENT_SPAN_ID 는 상위 스팬을 식별하는 16자 16진수 값입니다.
  • TRACE_FLAGS 는 상위 요소의 샘플링 결정을 식별하는 2자 16진수 값입니다. 상위 요소가 스팬을 샘플링한 경우 값은 01입니다.

Google Cloud trace 컨텍스트 전파를 지원하는 서비스는 일반적으로 traceparent 및 기존 X-Cloud-Trace-Context 헤더를 모두 지원합니다.

가능하면 애플리케이션에서 traceparent 헤더를 사용하세요. 애플리케이션이 X-Cloud-Trace-Context 헤더만 지원하는 경우 traceparent 헤더를 지원하고 우선순위를 지정하도록 애플리케이션을 업데이트하는 것이 좋습니다. 애플리케이션은 X-Cloud-Trace-Context 헤더를 대체 솔루션으로 계속 사용할 수 있습니다.

다음 표에서는 두 헤더 간의 몇 가지 중요한 차이점을 요약합니다.

속성 traceparent
헤더		 X-Cloud-Trace-Context
헤더
구분자 하이픈 (-) 포워드 슬래시 (/) 및 세미콜론 (;)
스팬 ID
표현		 16진수 십진수

기존 X-Cloud-Trace-Context 헤더

에서 사용하는 X-Cloud-Trace-Context 헤더는 Google Cloud W3C 사양보다 먼저 사용되었습니다. 하위 호환성을 위해 일부 Google Cloud 서비스는 계속 허용하고, 생성하며 X-Cloud-Trace-Context 헤더를 전파합니다. 하지만 이러한 시스템은 traceparent 헤더도 지원할 가능성이 높습니다.

X-Cloud-Trace-Context 헤더의 형식은 다음과 같습니다.

X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS

헤더의 필드는 다음과 같이 정의됩니다.

  • TRACE_ID는 128비트 숫자를 나타내는 32자 16진수 값입니다.
  • SPAN_ID는 부호 없는 스팬 ID의 64비트 십진수 표현입니다.
  • OPTIONS은 0(샘플링되지 않은 상위 요소) 및 1(상위 요소가 샘플링됨)을 지원합니다.

gRPC 요청

gRPC 요청의 경우 컨텍스트 전파는 HTTP 헤더 위에 구현되는 gRPC 메타데이터를 사용하여 수행됩니다. gRPC 애플리케이션은 traceparent 헤더 또는 grpc-trace-bin라는 메타데이터 컨텍스트 키를 사용할 수 있습니다.

소유한 구성요소의 경우 traceparent 헤더를 사용하는 것이 좋습니다.

서비스의 컨텍스트 전파 Google Cloud

Google Cloud 서비스는 요청 처리에서 개시자 또는 중개자 역할을 할 수 있습니다. 예를 들어 다음 서비스는 요청 처리에 참여하는 것으로 알려져 있습니다.

trace 컨텍스트 시작 및 전파 지원은 특정 Google Cloud 서비스에 따라 다릅니다. 서비스에서 컨텍스트 전파 지원을 추가하도록 요청하려면 Google Issue Tracker를 사용하세요. Google Cloud

애플리케이션의 컨텍스트 전파

OpenTelemetry와 같은 일부 계측 라이브러리는 추적에 필요한 데이터가 포함된 context 객체를 전파할 수 있습니다. 추적을 지원하는 OpenTelemetry 라이브러리의 목록은 언어 API 및 SDK를 참조하세요.

오픈소스 라이브러리를 사용하는 경우 컨텍스트 전파를 사용할 수 있는지, 구성이 필요한지 확인합니다. 예를 들어 OpenTelemetry를 사용하여 Go 앱을 계측하는 경우 앱은 W3C traceparent 형식을 사용하도록 컨텍스트를 구성하는 SetTextMapPropagator를 호출해야 합니다. 예시는 Go 계측 샘플을 참조하세요.

적합한 계측 라이브러리가 없는 경우 애플리케이션이 trace 컨텍스트를 하위 작업에 전파해야 합니다.

다음 단계