Trace 컨텍스트

이 문서에서는 상태를 나타내는 컨텍스트의 개념과, 하위 작업에 상태 정보를 전달하는 것을 나타내는 컨텍스트 전파의 개념에 대해 간략하게 설명합니다. 분산 추적의 경우 trace ID와 처리 중인 스팬의 ID를 하위 작업에 전달해야 합니다.

하위 작업은 스팬을 만들고 다음 필드를 설정합니다.

  • 스팬 ID: 하위 작업의 고유 식별자입니다. 동일한 작업이 여러 번 실행되면 해당 작업에 대한 여러 스팬이 생성되며, 각 스팬에는 고유 식별자가 포함됩니다.
  • Trace ID: 이 특정 전체 작업이 발생한 엔드 투 엔드 작업의 고유 식별자입니다. 이 필드의 값은 상위 요소에서 제공합니다.
  • 상위 스팬 ID: 상위 스팬의 고유 식별자입니다. 이 필드의 값은 상위 요소에서 제공합니다. 루트 스팬의 경우 이 ID는 null입니다.

분산 추적 시스템은 trace ID, 스팬 ID, 상위 스팬 ID 필드의 값을 통해 스팬을 올바르게 연결하여 trace를 형성할 수 있습니다. 예를 들어 Cloud Trace는 저장소에 스팬을 저장하고 이러한 ID 필드를 사용하여 trace를 구성하는 스팬을 식별합니다.

컨텍스트에는 분산 추적에 유용한 다른 상태 정보가 포함될 수 있습니다. 예를 들어 W3C(World Wide Web Consortium) 표준에는 상위 스팬이 샘플링되었는지 여부에 대한 정보가 포함되어 있습니다.

컨텍스트 전파 프로토콜

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

HTTP 요청

HTTP 요청의 경우 컨텍스트 전파는 일반적으로 W3C에서 표준화한 traceparent 및 tracestate 헤더와 같은 HTTP 헤더를 통해 이루어집니다. trace 컨텍스트 전파를 지원하는 Google Cloud 서비스는 일반적으로 traceparent 및 기존 X-Cloud-Trace-Context 헤더를 모두 지원합니다.

가능하면 애플리케이션에서 traceparent 헤더를 사용하는 것이 좋습니다. 애플리케이션이 기존 X-Cloud-Trace-Context 헤더를 사용해야 하거나 다른 형식의 trace 컨텍스트 수신을 지원해야 할 수 있습니다.

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

다음 표는 두 헤더의 주요 차이점을 요약하여 보여줍니다.

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

기존 X-Cloud-Trace-Context 헤더

Google Cloud에서 사용하는 X-Cloud-Trace-Context 헤더는 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 Cloud 서비스에서 컨텍스트 전파 지원을 추가하도록 요청하려면 Google Issue Tracker를 사용하세요.

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

OpenTelemetry와 같은 일부 계측 라이브러리는 추적에 필요한 데이터가 포함된 context 객체를 자동으로 전파합니다. 이러한 유형의 라이브러리를 사용하면 애플리케이션에서 생성된 스팬이 올바르게 구성됩니다. 추적을 지원하는 OpenTelemetry 라이브러리의 목록은 언어 API 및 SDK를 참조하세요. 계측 예시는 Go로 trace 및 측정항목 생성을 참조하세요.

오픈소스 라이브러리를 사용하는 경우 컨텍스트 전파를 사용할 수 있는지, 구성이 필요한지 여부를 확인합니다.

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

다음 단계