Cloud Trace 계측 개요

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 문서에서는 Cloud Trace용 애플리케이션 계측 방법을 간략하게 설명합니다. Cloud Trace 설정에 대한 자세한 안내는 언어별 설정 페이지를 참조하세요.

Cloud Trace에서는 애플리케이션의 분산 추적 데이터가 제공됩니다. 애플리케이션을 계측한 다음 단일 요청의 지연 시간 데이터를 검사하고 Cloud Trace 콘솔에서 전체 애플리케이션의 총 지연 시간을 볼 수 있습니다.

Cloud Trace에서는 OpenTelemetry를 사용하도록 권장합니다. OpenTelemetryOpenCensus와 OpenTracing 간에 병합된 오픈소스 제품입니다.

애플리케이션을 계측해야 하는 경우

애플리케이션이 trace를 Cloud Trace에 제출하도록 하려면 애플리케이션이 계측되어야 합니다. Google 클라이언트 라이브러리를 사용하여 코드를 계측할 수 있습니다. 그러나 OpenTelemetry 또는 OpenCensus를 사용하여 애플리케이션을 계측하는 것이 좋습니다. 이는 오픈소스 추적 패키지이며, OpenTelemetry는 활발하게 개발 중이고 선호하는 패키지입니다.

애플리케이션 계측 방법

애플리케이션에 추적을 구현하는 방법에는 여러 가지가 있습니다.

  • OpenTelemetry 및 관련된 Cloud Trace 클라이언트 라이브러리를 사용합니다. 이는 애플리케이션을 계측하는 데 권장되는 방법입니다.

  • 사용 중인 언어에서 OpenTelemetry 클라이언트 라이브러리를 사용할 수 없는 경우 OpenCensus를 사용합니다.

  • Cloud Trace API를 사용하고 커스텀 메서드를 작성하여 Cloud Trace에 추적 데이터를 보냅니다.

  • Zipkin 클라이언트에서 trace를 수신하고 분석을 위해 이 trace를 Cloud Trace로 전달하도록 Zipkin 서버를 구성하세요. 이 방법에 대한 자세한 내용은 Zipkin과 함께 Cloud Trace 사용을 참조하세요.

  • 수집하는 trace 데이터를 Cloud Trace로 전달하도록 Spring Boot 애플리케이션을 구성합니다. 이 절차에 대한 자세한 내용은 Google Cloud용 Spring Cloud: Cloud Trace를 참조하세요.

다음 표에는 각 프로그래밍 언어의 권장 계측이 나와 있습니다.

언어 권장 계측
C# .NET Cloud Trace API
Go OpenTelemetry
자바 OpenTelemetry
Node.js OpenTelemetry
PHP OpenCensus
Python OpenTelemetry
Ruby Cloud Trace API

스팬을 만들어야 하는 경우

Cloud Trace 클라이언트 라이브러리는 일반적으로 trace ID와 trace 샘플링 여부 등 현재 스팬에 대한 정보가 있는 전역 trace 컨텍스트를 유지합니다. 이러한 라이브러리는 일반적으로 RPC 경계에 스팬을 만듭니다. 하지만 기본 생성 알고리즘이 요구사항을 충족하지 않으면 스팬을 만들어야 할 수 있습니다.

현재 활성 스팬은 전역 trace 컨텍스트에서 액세스할 수 있으며, 경우에 따라 추적자 객체로 래핑됩니다. 커스텀 주석과 태그를 기존 스팬에 사용하여 애플리케이션과 관련된 정보를 추가하거나, 자체 주석과 태그로 새 하위 스팬을 만들어 세밀하게 세분화된 애플리케이션의 동작을 추적할 수 있습니다. 컨텍스트는 전역적이므로 컨텍스트를 업데이트하는 다중 스레드 애플리케이션은 적절한 격리를 사용해야 합니다.

사용자 인증 정보를 제공해야 하는 경우

Google Cloud에서 실행하는 경우 애플리케이션에 사용자 인증 정보를 제공하거나 애플리케이션에서 Google Cloud 프로젝트 ID를 지정할 필요가 없습니다. 일부 언어의 경우 Google Cloud에서 실행하여도 Google Cloud 프로젝트 ID를 지정해야 합니다.

Google Cloud 외부에서 실행하는 경우 애플리케이션에 사용자 인증 정보를 제공해야 합니다. 또한 애플리케이션에서 Google Cloud 프로젝트 ID를 지정해야 합니다.

자세한 내용은 언어별 설정 페이지를 참조하세요.

요청을 강제로 추적하는 방법

Cloud Trace에서는 모든 요청이 샘플링되지 않습니다. 예를 들어 자바 및 OpenCensus를 사용하는 경우 10,000개의 요청마다 하나의 요청만 추적됩니다. App Engine을 사용하는 경우 요청은 각 App Engine 인스턴스에 대해 초당 0.1개의 요청으로 샘플링됩니다. Cloud Trace API를 사용하는 경우 커스텀 레이트를 구성할 수 있습니다. 자바 OpenCensus 패키지와 같은 일부 패키지에서는 샘플링 레이트 구성을 지원합니다.

샘플링 레이트로 마이크로서비스를 구성하면 해당 속도는 해당 마이크로서비스에서 시작하는 요청에만 적용됩니다. 마이크로서비스의 샘플링 레이트를 구성하지 않으면 상위 컨텍스트의 샘플링 레이트가 마이크로서비스의 샘플링 레이트를 결정합니다.

특정 요청을 추적하려면 요청에 X-Cloud-Trace-Context 헤더를 추가합니다. 헤더 사양은 다음과 같습니다.

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

여기에서

  • TRACE_ID는 128비트 숫자를 나타내는 32자 16진수 값입니다. 의도적으로 요청을 번들로 묶으려는 경우가 아니면 각 요청별로 고유해야 합니다.

  • SPAN_ID는 부호 없는 스팬 ID의 십진수 표현입니다. 무작위로 생성되고 trace에서 고유해야 합니다. 후속 요청의 경우 SPAN_ID를 상위 요청의 스팬 ID로 설정합니다. 중첩된 trace에 대한 자세한 내용은 TraceSpan(REST, RPC) 설명을 참조하세요.

  • 이 요청을 추적하려면 TRACE_TRUE1이어야 합니다. 0으로 지정하면 요청이 추적되지 않습니다.

예를 들어 curl을 사용하여 추적을 실행하려면 다음을 사용합니다.

curl "http://www.example.com" --header "X-Cloud-Trace-Context:
  105445aa7843bc8bf206b12000100000/1;o=1"

Cloud Trace 예시를 만드는 방법

OpenCensus에서는 gRPC 서비스의 시계열 데이터를 작성할 때 Cloud Trace 예시를 만들 수 있습니다. 특히 분포 측정에 연결할 수 있는 예시가 있습니다. 예를 들어 URL 라벨을 포함하기 위해 지연 시간 측정항목이 필요할 수 있습니다. 측정항목의 카디널리티가 높아지기 때문에 URL 라벨을 추가할 수 없고, 그 결과 성능 이슈가 발생합니다. 하지만 URL을 기록하는 예시를 만들 수 있습니다. 자세한 내용은 Exemplar를 참조하세요.

예시를 보려면 다음을 수행합니다.

  1. 배포 값 측정항목을 차트로 작성하고 차트 유형을 히트맵 차트로 설정합니다. 대시보드에서 차트를 만들거나 측정항목 탐색기를 사용할 수 있습니다.
  2. 차트 툴바에서 Trace 예시 를 선택합니다. 예를 들어 차트 툴바를 참조하세요.

예시를 만들려면 자체 커스텀 측정항목을 작성하거나 OpenCensus와 같은 라이브러리를 사용할 수 있습니다. 커스텀 측정항목에 대한 일반 정보는 다음을 참조하세요.

다음 코드 샘플은 예시를 작성하는 방법을 보여줍니다.

  1. 버킷 수에 포함할 추가 정보를 만듭니다.

    • SpanContext 객체는 프로젝트 ID, trace ID, 스팬 ID를 저장합니다. 이러한 필드가 Cloud Trace로 전송된 trace의 값과 일치하는지 확인합니다. Cloud Monitoring은 이러한 필드를 사용하여 표시할 trace를 식별합니다.

    • DroppedLabels 객체는 추가 라벨을 정의합니다. 다음 코드 샘플은 하나의 라벨을 추가합니다. 키는 'Label'이고 값은 'Dropped'입니다. 앞에서 설명한 지연 시간 측정항목 예시에서는 키가 'URL'인 라벨이 추가될 수 있습니다.

  2. 시계열에 Point를 기록합니다.

    • TimeInterval 필드는 포인트의 시작 및 종료 시간을 정의합니다.
    • DistributionValue 필드는 데이터를 지정합니다. 데이터에는 Distribution 버킷과 버킷 값의 정의가 포함됩니다. 이 필드에는 데이터로 작성되는 예시도 포함됩니다. 이 예시에서는 두 개의 예시를 작성하며 각 항목에는 스팬 컨텍스트와 삭제된 라벨 객체가 포함됩니다.
import (
	"fmt"
	"time"

	"cloud.google.com/go/monitoring/apiv3/v2/monitoringpb"
	googlepb "github.com/golang/protobuf/ptypes/timestamp"
	distributionpb "google.golang.org/genproto/googleapis/api/distribution"
	"google.golang.org/protobuf/types/known/anypb"
)

// Generates metric TimeSeries points containing Exemplars with attached tracing span.
func createDataPointWithExemplar(projectID string) (*monitoringpb.Point, error) {
	// projectID := "my-cloud-project-id"
	end := time.Now().Unix()
	traceId := "0000000000000001"
	spanId := "00000001"
	spanCtx, err := anypb.New(&monitoringpb.SpanContext{
		SpanName: fmt.Sprintf("projects/%s/traces/%s/spans/%s", projectID, traceId, spanId),
	})
	if err != nil {
		return nil, err
	}
	droppedLabels, err := anypb.New(&monitoringpb.DroppedLabels{
		Label: map[string]string{"Label": "Dropped"},
	})
	if err != nil {
		return nil, err
	}
	dataPoint := &monitoringpb.Point{
		Interval: &monitoringpb.TimeInterval{
			StartTime: &googlepb.Timestamp{Seconds: end - 60},
			EndTime:   &googlepb.Timestamp{Seconds: end},
		},
		Value: &monitoringpb.TypedValue{Value: &monitoringpb.TypedValue_DistributionValue{
			DistributionValue: &distributionpb.Distribution{
				Count: 14,
				BucketOptions: &distributionpb.Distribution_BucketOptions{Options: &distributionpb.Distribution_BucketOptions_LinearBuckets{
					LinearBuckets: &distributionpb.Distribution_BucketOptions_Linear{NumFiniteBuckets: 2, Width: 3, Offset: 0},
				}},
				BucketCounts: []int64{5, 6, 3},
				Exemplars: []*distributionpb.Distribution_Exemplar{
					{Value: 1, Timestamp: &googlepb.Timestamp{Seconds: end - 30}, Attachments: []*anypb.Any{spanCtx, droppedLabels}},
					{Value: 4, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
				},
			},
		}},
	}
	return dataPoint, nil
}

Google Cloud 프로젝트 구성

Cloud Trace를 사용하려면 Google Cloud 프로젝트에 Cloud Trace API가 사용 설정되어 있어야 합니다. 이 설정을 사용하면 Google Cloud 프로젝트가 인증된 소스에서 trace 데이터를 수신할 수 있습니다.

기본적으로 Google Cloud 프로젝트에는 Cloud Trace API가 사용 설정되어 있으므로 별다른 조치를 취할 필요가 없습니다. Google Cloud 프로젝트의 액세스 범위를 수정하였고 설정을 확인하려면 다음 단계를 따르세요.

  1. Google Cloud Console에서 API 및 서비스로 이동합니다.

    API 및 서비스로 이동

  2. API 및 서비스 사용 설정을 클릭합니다.

  3. 검색창에 Trace API를 입력합니다.

  4. API 사용 설정됨이 표시된 경우는 이 API가 이미 사용 설정되어 있으므로 수행할 작업이 없습니다. 그렇지 않은 경우에는 사용 설정을 클릭합니다.

다음 단계

GitHub 및 기타 오픈소스 저장소에 대한 자세한 구성 정보, 샘플, 링크를 보려면 언어별 설정 페이지로 이동하세요.