クライアントサイドのトレースを使用する

このページでは、Cloud Storage クライアント ライブラリを使用して Cloud Storage とやり取りするときに、OpenTelemetry でクライアントサイド トレースを有効にする方法について説明します。トレースデータを収集して表示するには、次のサポートされている Cloud Storage クライアント ライブラリを使用します。

概要

Cloud Storage クライアント ライブラリでトレースを有効にすると、パフォーマンスをモニタリングし、レイテンシの問題を特定し、Cloud Storage リクエストのデバッグをすばやく実行できます。トレースを使用すると、完了したリクエストのシーケンスを確認できます。これにより、リクエストが Cloud Storage によってどのように受信、管理、応答されたかを詳細に把握できます。1 つのトレースは複数のスパンで構成されます。スパンは、アプリケーションが Cloud Storage リクエスト全体で実行した各関数またはオペレーションの詳細なタイムスタンプ付きレコードです。

利点

トレースデータの収集と伝播には、アプリケーションに次の利点があります。

  • パフォーマンスの可視性の向上: トレースデータは、Cloud Storage が各リクエストを完了するときにほぼリアルタイムで生成されるため、パフォーマンスのボトルネックを迅速に特定し、レイテンシの問題を検出できます。

  • エラー処理: トレース内に提供される各 Cloud Storage リクエストに関する情報を使用して、問題が発生した場所を特定し、根本原因の分析を迅速化し、ダウンタイムを短縮できます。

クライアントサイド トレースの仕組み

以降のセクションでは、トレース収集の仕組みについて詳しく説明します。

OpenTelemetry でのトレース収集の仕組み

Cloud Storage クライアント ライブラリは、OpenTelemetry SDK を使用してトレースデータの収集をサポートし、トレースデータの収集と伝播に必要な次のコンポーネントを設定します。

  • トレース プロバイダ: Cloud Storage クライアント ライブラリで使用されるトレース プロバイダは、アプリケーション内のトレースやスパンの生成と管理など、トレース システムの作成と管理を担当します。

  • トレース エクスポータ: OpenTelemetry SDK で使用されるトレース エクスポータは、トレースデータを Cloud Trace などのバックエンド オブザーバビリティ プラットフォームに送信します。ここで、トレースデータを分析して可視化できます。トレース エクスポータの詳細については、トレース エクスポータの仕組みをご覧ください。

トレース エクスポータの仕組み

OpenTelemetry SDK を使用してトレースを構成するには、分析、保存、可視化を行う場所にデータをエクスポートするオブザーバビリティ バックエンドを選択します。トレースデータを任意の監視バックエンドにエクスポートできますが、Cloud Trace を使用することをおすすめします。これは、Google Cloud コンソールからアクセスでき、他の Google Cloud サービスと統合できます。

トレース プロバイダとトレース エクスポータを構成して有効にすると、各 Cloud Storage リクエストに対してトレースとスパンが生成されるため、トレースデータをほぼリアルタイムで表示できます。

Google Cloud コンソールの Cloud Trace エクスプローラを使用すると、次を含む各トレースを表示できます。

  • Cloud Storage リクエストのエンドツーエンドの概要。

  • 複数のスパン。各スパンは、実行された Cloud Storage リクエスト内のタイムスタンプ付きの単一オペレーションをキャプチャします。

トレースとスパンの詳細については、トレースとスパンの OpenTelemetry ドキュメントをご覧ください。

料金

トレースデータは有料です。料金は、Cloud 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 エージェントのロールの詳細については、Identity and Access Management（IAM）のドキュメントをご覧ください。

アプリケーションのトレースを構成する

次の手順でトレースを構成し、Cloud Storage クライアント ライブラリを使用してトレースデータの収集を開始します。

Java

  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. トレース エクスポータとトレース プロバイダを構成します。 

    
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 エクスプローラを使用して、Google Cloud コンソールでトレースデータを表示します。

  1. Google Cloud コンソールで、[Trace エクスプローラ] ページに移動します。

    [Trace エクスプローラ] に移動

    このページは、検索バーを使用して見つけることもできます。

  2. [Trace エクスプローラ] ページで、散布図の特定のトレースをタップして、トレースの詳細を表示します。

    [トレースの詳細] ペインには、トレーススパンの表が表示されます。

  3. 省略可: スパンの行をクリックすると、特定のスパンに関する詳細情報（次の情報など）が表示されます。

    • 属性: スパンの追加情報を提供する Key-Value ペア。

    • ログとイベント: スパンに関連付けられているログエントリ。

    • スタック トレース: スパンに関連付けられているスタック トレース。

    • メタデータとリンク: スパンに関連付けられている他のサービスへのリンク。 Google Cloud

Cloud Trace エクスプローラの使用方法について詳しくは、トレースを検索して調査するをご覧ください。

次のステップ