Python と OpenTelemetry

このページは、OpenTelemetry を使用して Python アプリケーション用の Cloud Trace データを収集するアプリケーション開発者を対象としています。OpenTelemetry は、トレースデータと指標データを収集するために使用できる、ベンダーに依存しないインストルメンテーション フレームワークです。コードのインストルメンテーションの詳細については、インストルメンテーションとオブザーバビリティをご覧ください。

  • OpenTelemetry パッケージをインストールする。
  • Cloud Trace にスパンをエクスポートするようにアプリケーションを構成する。
  • プラットフォームを構成する。

リリース情報については、以下をご覧ください。

OpenTelemetry リファレンス コンテンツについては、以下をご覧ください。

追加のドキュメントとサンプルを含め、Python の OpenTelemetry に関する最新情報については、OpenTelemetry をご覧ください。

始める前に

  • Python 3.6 以降を使用する必要があります。

  • Google Cloud コンソールのナビゲーション パネルで [API とサービス] を選択し、[API とサービスを有効化] をクリックして、Cloud Trace API を有効にします。

    [Cloud Trace API の設定] に移動

  • [API が有効です] が表示されている場合、API はすでに有効になっています。そうでない場合は、[有効にする] ボタンをクリックします。

OpenTelemetry パッケージをインストールする

必要な OpenTelemetry パッケージをインストールするには、次の操作を行います。

  1. （省略可）pip を最新バージョンにアップグレードします。

    pip install --upgrade pip

  2. pip を使用して、次の OpenTelemetry パッケージをインストールします。

    pip install opentelemetry-api \
  opentelemetry-sdk \
  opentelemetry-exporter-gcp-trace

トレース パッケージをインポートする

アプリケーションを更新して、次のパッケージとクラスをインポートします。

  • trace
  • CloudTraceSpanExporter
  • TracerProvider

  • BatchSpanProcessor。バックグラウンド プロセスを使用してスパンを送信するエクスポート スパン プロセッサです。

  • （省略可）スパンをリンクする場合は、Link クラスをインポートします。

このインポート ステートメントを次の例に示します。


from opentelemetry import trace
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.trace import Link

Cloud Trace へのスパンのエクスポートを構成する

Cloud Trace にスパンを送信するには、CloudTraceSpanExporter エクスポータを使用するようにアプリケーションを変更します。次の例は、必須の手順を示しています。


tracer_provider = TracerProvider()
cloud_trace_exporter = CloudTraceSpanExporter()
tracer_provider.add_span_processor(
    # BatchSpanProcessor buffers spans and sends them in batches in a
    # background thread. The default parameters are sensible, but can be
    # tweaked to optimize your performance
    BatchSpanProcessor(cloud_trace_exporter)
)
trace.set_tracer_provider(tracer_provider)

tracer = trace.get_tracer(__name__)

スパンに属性を追加する

スパンに属性を追加するには、スパンの set_attribute メソッドを呼び出します。たとえば、次のコードは、foo_with_attribute という名前のスパンに複数の属性を追加します。


with tracer.start_span("foo_with_attribute") as current_span:
    do_work()

    # Add attributes to the spans of various types
    current_span.set_attribute("string_attribute", "str")
    current_span.set_attribute("bool_attribute", False)
    current_span.set_attribute("int_attribute", 3)
    current_span.set_attribute("float_attribute", 3.14)

スパンにイベントを追加する

スパンにイベントを追加するには、スパンの add_event メソッドを呼び出します。たとえば、次のコードでは、foo_with_event という名前のスパンにイベントが追加されます。


# Adding events to spans
with tracer.start_as_current_span("foo_with_event") as current_span:
    do_work()
    current_span.add_event(name="event_name")

2 つのスパンをリンクするには、Link クラスをインポートし、続いて、start_as_current_spanメソッドで links フィールドを使用します。2 つのスパンをリンクする際は、links フィールドに属性を含められます。

次のコードでは、スパンを link_target という名前のスパンにリンクする方法を示します。


# Adding links to spans
with tracer.start_as_current_span("link_target") as link_target:
    # Using start_as_current_span() instead of start_span() will make spans
    # created within this scope children of foo_with_attribute

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target"
    with tracer.start_as_current_span(
        "span_with_link", links=[Link(link_target.context)]
    ):
        do_work()

    # Creates a span "span_with_link" and a link from
    # "span_with_link" -> "link_target". This link also has the attribute
    # {"link_attr": "string"}
    with tracer.start_as_current_span(
        "span_with_link_and_link_attributes",
        links=[Link(link_target.context, attributes={"link_attr": "string"})],
    ):
        do_work()

Flask のサンプル アプリケーション

OpenTelemetry の Flask インストルメンテーションは、HTTP リクエストに関連するトレース コンテンツを簡単に取得できるよう設計されています。つまり、次のリクエストのルートに特定のインストルメンテーションを追加する必要はありません。

  • Flask では、構成されたプロパゲータを使用して、受信 HTTP リクエストからスパン コンテキストを抽出します。
  • Flask では、リクエストとレスポンスを記述する属性を持つスパンが自動的に作成されます。

Flask と OpenTelemetry を使用するエンドツーエンドの例については、flask_e2e をご覧ください。Git README には、サンプルをインストール、構成、実行する方法に関する情報が含まれています。

このセクションでは、サンプルの server.py ファイルに含まれる Flask 固有の構成のステップについて説明します。クライアント ファイル client.py は、Requests インストルメンテーションを使用して、requests ライブラリによる HTTP リクエストのトレースを有効にします。

インポートと構成

OpenTelemetry の Flask インストルメンテーションを使用するには、FlaskInstrumentor をインポートする必要があります。

さまざまな Google Cloud プロダクトによって作成されたスパンが同じトレースに関連付けられるようにするには、Cloud Trace プロパゲータを使用してプロパゲータを構成する必要があります。このプロパゲータでは、X-Cloud-Trace-Context ヘッダーの使用を指定します。プロパゲータを構成しない場合、OpenTelemetry は、デフォルトのプロパゲータを使用します。この場合、Cloud Run や App Engine などのさまざまな Google Cloud プロダクトによって作成されたスパンは、個別のトレースに格納されます。

次のサンプルでは、必要なインポートと構成のステートメントと、Cloud Trace プロパゲータの構成を示します。


import time

from flask import Flask
from opentelemetry import metrics, trace
from opentelemetry.exporter.cloud_monitoring import (
    CloudMonitoringMetricsExporter,
)
from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.propagate import set_global_textmap
from opentelemetry.propagators.cloud_trace_propagator import (
    CloudTraceFormatPropagator,
)
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor


set_global_textmap(CloudTraceFormatPropagator())

CloudTraceSpanExporter エクスポータを構成するときに、Flask 固有のステートメントを追加する必要はありません。スパンの Cloud Trace へのエクスポートを構成するに示した構成で十分です。

Flask を初期化する

FlaskInstrumentor を構成してアプリケーションをインストルメント化します。次のサンプルでは、この処置の実施方法を示します。


app = Flask(__name__)
FlaskInstrumentor().instrument_app(app)

@app.route("/")
def hello_world():
    # You can still use the OpenTelemetry API as usual to create custom spans
    # within your trace
    with tracer.start_as_current_span("do_work"):
        time.sleep(0.1)

    return "Hello, World!"

プラットフォームの構成

Cloud Trace は Google Cloud と他のプラットフォームで使用できます。

Google Cloud での実行

アプリケーションが Google Cloud で実行されている場合、認証情報をサービス アカウントの形式でクライアント ライブラリに提供する必要はありません。ただし、Google Cloud Platform で Cloud Trace API のアクセス スコープが有効になっている必要があります。

サポートされている Google Cloud 環境の一覧については、環境サポートをご覧ください。

次の構成では、デフォルトのアクセス スコープ設定により Cloud Trace API が有効化されます。

カスタム アクセス スコープを使用する場合は、Cloud Trace API のアクセス スコープを有効にする必要があります。

  • Google Cloud Console を使用して環境のアクセス スコープを構成する方法については、Google Cloud プロジェクトの構成をご覧ください。

  • gcloud ユーザーの場合は、--scopes フラグを使用してアクセス スコープを指定し、trace.append Cloud Trace API アクセス スコープを含めます。たとえば、Cloud Trace API のみを有効にして GKE クラスタを作成するには、次のようにします。

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

ローカルやその他の場所での実行

アプリケーションが Google Cloud の外部で実行されている場合は、認証情報をサービス アカウントの形式でクライアント ライブラリに提供する必要があります。サービス アカウントには Cloud Trace エージェント ロールが含まれている必要があります。手順については、サービス アカウントの作成をご覧ください。

Google Cloud クライアント ライブラリは、アプリケーションのデフォルト認証情報（ADC）を使用してアプリケーションの認証情報を検索します。

これらの認証情報を指定するには、次の 3 つの方法があります。

  • 実行 gcloud auth application-default login

  • オペレーティング システムのデフォルトパスにサービス アカウントを配置します。以下に、Windows と Linux のデフォルトのパスを一覧表示します。

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • GOOGLE_APPLICATION_CREDENTIALS 環境変数をサービス アカウントのパスに設定します。

Linux / macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

トレースを表示

Google Cloud コンソールのナビゲーション パネルで [Trace] を選択し、次に [ Trace エクスプローラ] を選択します。

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

トラブルシューティング

Cloud Trace に関する問題のトラブルシューティングについては、トラブルシューティング ページをご覧ください。

リソース