Python と OpenTelemetry

このページは、OpenTelemetry を使用して Python アプリケーション用の Cloud Trace データを収集するアプリケーション開発者を対象としています。OpenTelemetry は、トレースデータと指標データを収集するための一連のインストルメンテーション ライブラリです。これらのライブラリは複数のバックエンドで動作します。このページで説明するように、OpenTelemetry と Python を使用してトレースを収集するには、次のことを実施します。

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

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

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

始める前に

  • Python 3.6 以降を使用する必要があります。
  • Google Cloud プロジェクトで Cloud Trace API が有効になっていることを確認します。

    1. 次のボタンをクリックするか、Google Cloud Console で [API とサービス]、[Cloud Trace API] の順に選択します。

      Trace API に移動

    2. [Cloud Trace API] のページで、[有効にする] というボタンが表示されている場合は、それをクリックします。このボタンが表示されない場合、Cloud Trace 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 プロセッサを使用します。Cloud Run を使用している場合を除き、このプロセッサを使用することをおすすめします。Cloud Run はバックグラウンド プロセスをサポートしていません。

    • フォアグラウンド プロセスを使用してスパンを送信するには、SimpleSpanProcessor プロセッサを使用します。Cloud Run を使用している場合は、このプロセッサを使用する必要があります。このプロセッサでは、アプリケーションの動作が遅くなることがあります。

  • (省略可)スパンをリンクする場合は、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 trace
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.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 が有効化されます。

  • App Engine フレキシブル環境
  • App Engine スタンダード環境

  • Google Kubernetes Engine(GKE)

  • Compute Engine

  • Cloud Run

カスタム アクセス スコープを使用する場合は、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)を使用してアプリケーションの認証情報を検索します。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"

トレースの表示

デプロイ後は、Cloud Console Trace Viewer でトレースを表示できます。

Trace Viewer のページに移動

トラブルシューティング

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

リソース