Python と OpenTelemetry

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

このページでは、次のステップについて説明します。

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

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

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

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

始める前に

Python 3.6 以降を使用する必要があります。
Enable the required API.
Enable the API

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

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

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

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

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

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

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

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

注: Cloud Run を使用する場合は、Cloud Run が常に CPU を割り当てるように構成します。詳細については、CPU 割り当てをご覧ください。
（省略可）スパンをリンクする場合は、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 が有効化されます。

App Engine フレキシブル環境
App Engine スタンダード環境
Google Kubernetes Engine（GKE）

注: Autopilot を使用している場合、または GKE クラスタで Workload Identity を有効にする場合は、Workload Identity を使用するようにアプリケーションを構成します。
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）を使用してアプリケーションの認証情報を検索します。

これらの認証情報を指定するには、次の 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 エクスプローラ] に移動

このページは、検索バーを使用しても確認できます。

トラブルシューティング

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

リソース

https://opentelemetry.io/
OpenTelemetry/opentelemetry-python GitHub リポジトリ
Google Cloud opentelemetry-operations-python GitHub リポジトリ。