클라이언트 측 trace 사용

이 페이지에서는 Cloud Storage 클라이언트 라이브러리를 사용하여 Cloud Storage와 상호작용할 때 OpenTelemetry로 클라이언트 측 트레이스를 사용 설정하는 방법을 설명합니다. 지원되는 다음 Cloud Storage 클라이언트 라이브러리를 사용하여 트레이스 데이터를 수집하고 볼 수 있습니다.

• Python 클라이언트 라이브러리

• Java 클라이언트 라이브러리

개요

Cloud Storage 클라이언트 라이브러리에서 트레이스를 사용 설정하면 성능을 모니터링하고, 지연 시간 문제를 파악하고, Cloud Storage 요청을 신속하게 디버그할 수 있습니다. 트레이스를 사용하면 완료된 요청의 시퀀스를 확인하여 Cloud Storage에서 요청을 수신, 관리, 응답하는 방식을 자세히 볼 수 있습니다. 단일 트레이스는 여러 스팬으로 구성되며, 스팬은 Cloud Storage 요청 중에 애플리케이션에서 실행한 각 함수 또는 작업의 세부적인 타임스탬프 기록입니다.

이점

추적 데이터를 수집하고 전파하면 애플리케이션에 다음과 같은 이점이 있습니다.

• 향상된 성능 가시성: Cloud Storage에서 각 요청을 완료할 때 트레이스 데이터가 거의 실시간으로 생성되므로 성능의 병목 현상을 신속하게 파악하고 지연 시간 문제를 감지할 수 있습니다.

• 오류 처리: 트레이스에 제공된 각 Cloud Storage 요청에 관한 정보를 사용하여 문제가 발생한 위치를 정확하게 파악하여 근본 원인 분석을 가속화하고 다운타임을 줄일 수 있습니다.

클라이언트 측 트레이스의 작동 방식

다음 섹션에서는 트레이스 수집의 작동 방식을 자세히 설명합니다.

OpenTelemetry에서의 trace 수집 작동 방식

Cloud Storage 클라이언트 라이브러리는 OpenTelemetry SDK를 사용하여 트레이스 데이터 수집을 지원하여 트레이스 데이터를 수집하고 전파하는 데 필요한 다음 구성요소를 설정합니다.

• 트레이스 제공업체: Cloud Storage 클라이언트 라이브러리에서 사용하는 트레이스 제공업체는 애플리케이션에서 트레이스 및 스팬을 생성하고 관리하는 등 추적 시스템을 만들고 관리합니다.

• 트레이스 내보내기 도구: OpenTelemetry SDK에서 사용하는 트레이스 내보내기 도구는 트레이스 데이터를 분석하고 시각화할 수 있는 Cloud Trace와 같은 백엔드 관측 가능성 플랫폼으로 트레이스 데이터를 전송합니다. 트레이스 내보내기에 관해 자세히 알아보려면 트레이스 내보내기 작동 방식을 참고하세요.

트레이스 내보내기 도구 작동 방식

OpenTelemetry SDK를 사용하여 트레이스를 구성하는 작업에는 관측성 백엔드를 선택하여 데이터가 분석, 저장, 시각화되는 위치로 내보내는 작업이 포함됩니다. 원하는 관측성 백엔드로 trace 데이터를 내보낼 수 있지만 Google Cloud 콘솔을 사용하여 액세스할 수 있고 다른 Google Cloud 서비스와 통합되는 Cloud Trace를 사용하는 것이 좋습니다.

trace 제공자와 trace 내보내기 도구가 구성되고 사용 설정되면 각 Cloud Storage 요청에 대해 trace 및 스팬이 생성될 때 거의 실시간으로 trace 데이터를 볼 수 있습니다.

Google Cloud 콘솔의 Cloud Trace 탐색기를 사용하면 다음이 포함된 각 트레이스를 볼 수 있습니다.

• Cloud Storage 요청의 전체 과정을 보여주는 개요입니다.

• 여러 스팬. 각 스팬은 실행된 Cloud Storage 요청 내에서 타임스탬프가 지정된 단일 작업을 캡처합니다.

트레이스 및 스팬에 관한 자세한 내용은 트레이스 및 스팬에 관한 OpenTelemetry 문서를 참고하세요.

가격 책정

트레이스 데이터에는 요금이 청구됩니다. 요금은 Cloud Trace에서 수집 및 스캔한 Trace 스팬 수를 기준으로 부과됩니다. 요금이 청구되는 트레이스 스팬 및 가격 책정 예시에 대한 자세한 내용은 Cloud Trace 비용을 참고하세요.

시작하기 전에

Cloud Storage API 사용량에 관한 트레이스를 수집하려면 먼저 다음 단계를 완료해야 합니다.

1. Cloud Storage 클라이언트 라이브러리를 설치합니다.

2. 인증 설정

3. Enable the Cloud Trace API.

   Enable the API

4. Cloud Storage API를 사용 설정합니다.

   API 사용 설정하기

필요한 역할

Cloud Trace에 트레이스를 작성하는 데 필요한 권한을 얻으려면 관리자에게 클라이언트가 사용하는 프로젝트에 대한 Cloud Trace 에이전트 (roles/coudtrace.agent) IAM 역할을 부여해 달라고 요청하세요.

이 사전 정의된 역할에는 Cloud Trace에 트레이스를 작성하는 데 필요한 cloudtrace.traces.patch 권한이 포함되어 있습니다.

사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있고, 커스텀 역할을 만들어 특정 권한을 부여할 수도 있습니다. 프로젝트에 역할을 부여하는 방법은 역할 부여 또는 취소를 참고하세요. Cloud Trace Agent 역할에 관한 자세한 내용은 Identity and Access Management (IAM) 문서를 참고하세요.

애플리케이션의 추적 구성

다음 안내에 따라 추적을 구성하고 Cloud Storage 클라이언트 라이브러리를 사용하여 트레이스 데이터 수집을 시작합니다.

자바

1. 다음 Cloud Storage Java 클라이언트 라이브러리 버전을 설치합니다.

   • com.google.cloud:google-cloud-storage:2.47.0 이상

   • com.google.cloud:libraries-bom:26.53.0 이상

2. OpenTelemetry용 Cloud Trace 내보내기 도구를 설치합니다. 원하는 내보내기 도구를 사용할 수도 있습니다.

3. Cloud Trace 전파자를 설치합니다.

4. OpenTelemetry 트레이스가 사용 설정된 Cloud Storage 클라이언트의 인스턴스를 만듭니다.

   public class QuickstartOpenTelemetrySample {
     public static void main(String... args) throws Exception {
       SpanExporter spanExporter = TraceExporter.createWithDefaultConfiguration();
       TextMapPropagator propagators =
           TextMapPropagator.composite(
               W3CTraceContextPropagator.getInstance(),
               new XCloudTraceContextPropagator(/*oneway=*/ true));
   
       OpenTelemetrySdk openTelemetry =
           OpenTelemetrySdk.builder()
               .setPropagators(ContextPropagators.create(propagators))
               .setTracerProvider(
                   SdkTracerProvider.builder()
                       // Sample Rate is set to alwaysOn
                       // It is recommended to sample based on a ratio for standard use ie.
                       // .setSampler(Sampler.traceIdRatioBased(0.2)) // sample only 20% of trace ids
                       .setSampler(Sampler.alwaysOn())
                       .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
                       .build())
               .build();
       StorageOptions options = StorageOptions.newBuilder().setOpenTelemetry(openTelemetry).build();
       Storage storage = options.getService();
       System.out.println("Created an instance of storage with OpenTelemetry configured");
     }
   }

Python

1. Cloud Storage Python 클라이언트 라이브러리를 설치합니다.

   pip install google-cloud-storage[tracing]>=2.18.0

2. Cloud Trace 내보내기 도구 및 전파 도구를 설치합니다. 원하는 내보내기 도구를 사용할 수도 있습니다.

   pip install opentelemetry-exporter-gcp-trace opentelemetry-propagator-gcp

3. OpenTelemetry 요청 계측을 설치하여 기본 HTTP 요청을 추적합니다.

   pip install opentelemetry-instrumentation-requests

4. Python 스토리지 클라이언트의 추적을 선택적으로 선택하도록 환경 변수를 설정합니다.

   export ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True

5. trace 내보내기 도구와 trace 공급자를 구성합니다.

   
   from opentelemetry import trace
   from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
   from opentelemetry.resourcedetector.gcp_resource_detector import (
       GoogleCloudResourceDetector,
   )
   from opentelemetry.sdk.trace import TracerProvider
   from opentelemetry.sdk.trace.export import BatchSpanProcessor
   from opentelemetry.sdk.trace.sampling import ALWAYS_ON
   # Optional: Enable traces emitted from the requests HTTP library.
   from opentelemetry.instrumentation.requests import RequestsInstrumentor
   
   from google.cloud import storage
   
   # The ID of your GCS bucket
   # bucket_name = "your-bucket-name"
   # The ID of your GCS object
   # blob_name = "your-object-name"
   # The contents to upload to the file
   # data = "The quick brown fox jumps over the lazy dog."
   
   # In this sample, we use Google Cloud Trace to export the OpenTelemetry
   # traces: https://cloud.google.com/trace/docs/setup/python-ot
   # Choose and configure the exporter for your environment.
   
   tracer_provider = TracerProvider(
       # Sampling is set to ALWAYS_ON.
       # It is recommended to sample based on a ratio to control trace ingestion volume,
       # for instance, sampler=TraceIdRatioBased(0.2)
       sampler=ALWAYS_ON,
       resource=GoogleCloudResourceDetector().detect(),
   )
   
   # Export to Google Cloud Trace.
   tracer_provider.add_span_processor(BatchSpanProcessor(CloudTraceSpanExporter()))
   trace.set_tracer_provider(tracer_provider)
   
   # Optional: Enable traces emitted from the requests HTTP library.
   RequestsInstrumentor().instrument(tracer_provider=tracer_provider)
   
   # Get the tracer and create a new root span.
   tracer = tracer_provider.get_tracer("My App")
   with tracer.start_as_current_span("trace-quickstart"):
       # Instantiate a storage client and perform a write and read workload.
       storage_client = storage.Client()
       bucket = storage_client.bucket(bucket_name)
       blob = bucket.blob(blob_name)
       blob.upload_from_string(data)
       print(f"{blob_name} uploaded to {bucket_name}.")
   
       blob.download_as_bytes()
       print("Downloaded storage object {} from bucket {}.".format(blob_name, bucket_name))
   

   참고: 다음 샘플에서는 트레이스 결과가 Cloud Trace로 내보내집니다. 트레이스 내보내기 옵션에 관한 자세한 내용은 OpenTelemetry의 사용 가능한 내보내기 도구 목록을 참고하세요.

trace 보기

Cloud Trace 탐색기를 사용하여 Google Cloud 콘솔에서 트레이스 데이터를 확인합니다.

1. Google Cloud 콘솔에서 Trace 탐색기 페이지로 이동합니다.

   Trace 탐색기로 이동

   검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

2. Trace Explorer 페이지에서 산점표에서 특정 trace를 클릭하여 trace 세부정보를 확인합니다.

   trace 세부정보 창에 trace 스팬 표가 표시됩니다.

3. 선택사항: 스팬 행을 클릭하여 다음과 같은 특정 스팬에 관한 자세한 정보를 확인합니다.

   • 속성: 스팬에 관한 추가 정보를 제공하는 키-값 쌍입니다.

   • 로그 및 이벤트: 스팬과 연결된 로그 항목입니다.

   • 스택 트레이스: 스팬과 연결된 스택 트레이스입니다.

   • 메타데이터 및 링크: 스팬과 연결된 다른 Google Cloud 서비스에 대한 링크입니다.

Cloud Trace 탐색기 사용에 대한 자세한 내용은 trace 찾기 및 탐색을 참조하세요.

다음 단계

• trace 찾기 및 탐색

• 최근 trace를 표시합니다.

• ID로 트레이스를 찾습니다.