Python インストルメンテーション サンプル

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

このドキュメントでは、オープンソースの OpenTelemetry フレームワークを使用してトレースと指標データを収集するように Python アプリを変更する方法と、構造化 JSON ログを標準出力に出力する方法について説明します。このドキュメントでは、インストールして実行できる Python サンプルアプリについても説明します。このアプリは Flask ウェブ フレームワークを使用し、指標、トレース、ログを生成するように構成されています。

計測について詳しくは、次のドキュメントをご覧ください。

• 計測とオブザーバビリティ
• 計測方法を選択する

手動インストルメンテーションとゼロコード インストルメンテーションについて

この言語について、OpenTelemetry はゼロコード インストルメンテーションを、コードを変更せずにライブラリとフレームワークからテレメトリーを収集する手法と定義しています。ただし、モジュールをインストールし、環境変数を設定する必要があります。

このドキュメントでは、ゼロコード インストルメンテーションについては説明しません。このトピックについては、Python zero-code instrumentation をご覧ください。

一般的な情報については、OpenTelemetry Instrumentation for Python をご覧ください。

始める前に

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

アプリを計測してトレース、指標、ログを収集する

アプリを計測して、トレースと指標データを収集し、構造化 JSON を標準出力に出力するには、このドキュメントの以降のセクションで説明する手順を実施します。

1. OpenTelemetry を構成する
2. 構造化ロギングを構成する

OpenTelemetry を構成する

このサンプルアプリは、OpenTelemetry Python SDK を使用して OTLP プロトコルでトレースと指標をエクスポートするように構成されています。デフォルトでは、OpenTelemetry Python SDK はトレース コンテキストの伝播に W3C トレース コンテキスト形式を使用します。これにより、トレース内でスパンが正しい親子関係を持つことが保証されます。

次のコードサンプルでは、OpenTelemetry を設定するための Python モジュールを示します。サンプル全体を表示するには、more_vert（その他アイコン）をクリックして、[GitHub で表示] を選択します。

resource = Resource.create(attributes={
    # Use the PID as the service.instance.id to avoid duplicate timeseries
    # from different Gunicorn worker processes.
    SERVICE_INSTANCE_ID: f"worker-{os.getpid()}",
})

traceProvider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter())
traceProvider.add_span_processor(processor)
trace.set_tracer_provider(traceProvider)

reader = PeriodicExportingMetricReader(
    OTLPMetricExporter()
)
meterProvider = MeterProvider(metric_readers=[reader], resource=resource)
metrics.set_meter_provider(meterProvider)

Flask アプリは、Flask の本番環境へのデプロイガイドの推奨事項に従い、Gunicorn を使用して HTTP リクエストを処理します。Gunicorn は、独立したワーカー プロセスで実行されるアプリの複数のコピーを起動して、スループットを向上させます。ワーカー プロセスの指標が互いに競合しないようにするには、各ワーカー プロセスで service.instance.id リソース属性に一意の値を設定することをおすすめします。これを行う一つの方法は、service.instance.id にプロセス ID を含めることです。詳細については、時系列の衝突をご覧ください。

詳細と構成オプションについては、OpenTelemetry Python 計測をご覧ください。

構造化ロギングを構成する

トレースにリンクされた構造化ログを書き込むには、トレース情報を含むキーを使用して JSON 形式のログを標準出力に出力するようにアプリを構成します。次のコードサンプルは、python-json-logger ライブラリを使用して JSON 構造化ログを出力するように標準の logging ライブラリを構成する方法と、opentelemetry-instrumentation-logging パッケージを使用してトレース情報を含める方法を示しています。

LoggingInstrumentor().instrument()

logHandler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter(
    "%(asctime)s %(levelname)s %(message)s %(otelTraceID)s %(otelSpanID)s %(otelTraceSampled)s",
    rename_fields={
        "levelname": "severity",
        "asctime": "timestamp",
        "otelTraceID": "logging.googleapis.com/trace",
        "otelSpanID": "logging.googleapis.com/spanId",
        "otelTraceSampled": "logging.googleapis.com/trace_sampled",
        },
    datefmt="%Y-%m-%dT%H:%M:%SZ",
)
logHandler.setFormatter(formatter)
logging.basicConfig(
    level=logging.INFO,
    handlers=[logHandler],
)

前の構成では、アクティブなスパンに関する情報がログ メッセージから抽出され、抽出された情報が JSON 構造化ログに属性として追加されます。これらの属性を使用して、ログをトレースに関連付けることができます。

• logging.googleapis.com/trace: ログエントリに関連付けられているトレースのリソース名。
• logging.googleapis.com/spanId: ログエントリに関連付けられているトレースのスパン ID。
• logging.googleapis.com/trace_sampled: このフィールドの値は true または false にする必要があります。

これらのフィールドの詳細については、LogEntry 構造体をご覧ください。

テレメトリーを収集するように構成されたサンプルアプリを実行する

サンプルアプリでは、ログに JSON、指標とトレースに OTLP を使用するなど、ベンダーに依存しない形式を使用しています。アプリからのテレメトリーは、Google エクスポータで構成された OpenTelemetry Collector を使用して Google Cloud に転送されます。Flask を使用して HTTP リクエストを処理し、requests ライブラリを使用して HTTP リクエストを送信します。HTTP クライアントとサーバーの指標とトレースを生成するため、サンプルアプリは opentelemetry-instrumentation-flask インストルメンテーション ライブラリと opentelemetry-instrumentation-requests インストルメンテーション ライブラリをインストールします。

logger = logging.getLogger(__name__)

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

このアプリには 2 つのエンドポイントがあります。

• /multi エンドポイントは、multi 関数によって処理されます。アプリの負荷生成ツールが /multi エンドポイントにリクエストを発行します。このエンドポイントは、リクエストを受信すると、ローカル サーバーの /single エンドポイントに 3～7 件のリクエストを送信します。

  @app.route('/multi')
  def multi():
      """Handle an http request by making 3-7 http requests to the /single endpoint."""
      subRequests = randint(3, 7)
      logger.info("handle /multi request", extra={'subRequests': subRequests})
      for _ in range(subRequests):
          requests.get(url_for('single', _external=True))
      return 'ok'

• /single エンドポイントは、single 関数によって処理されます。このエンドポイントは、リクエストを受信すると、少しの間スリープしてから、文字列で応答します。

  @app.route('/single')
  def single():
      """Handle an http request by sleeping for 100-200 ms, and write the number of seconds slept as the response."""
      duration = uniform(0.1, 0.2)
      time.sleep(duration)
      return f'slept {duration} seconds'

アプリをダウンロードしてデプロイする

サンプルを実行するには、次の操作を行います。

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. リポジトリのクローンを作成します。

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python
   

3. サンプル ディレクトリに移動します。

   cd opentelemetry-operations-python/samples/instrumentation-quickstart
   

4. サンプルをビルドして実行します。

   docker compose up --abort-on-container-exit
   

   Cloud Shell で実行していない場合は、認証情報ファイルを指す GOOGLE_APPLICATION_CREDENTIALS 環境変数を使用してアプリケーションを実行します。アプリケーションのデフォルト認証情報は、$HOME/.config/gcloud/application_default_credentials.json にある認証情報ファイルを提供します。

   # Set environment variables
   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
   export USERID="$(id -u)"
   
   # Run
   docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
   

指標を表示する

サンプルアプリの OpenTelemetry 計測は、Metrics Explorer で表示可能な Prometheus 指標を生成します。

• Prometheus/http_server_duration_milliseconds/histogram は、サーバー リクエストの所要時間を記録し、結果をヒストグラムに保存します。

• Prometheus/http_client_duration_milliseconds/histogram は、クライアント リクエストの所要時間を記録し、結果をヒストグラムに保存します。

1. Google Cloud コンソールで、[leaderboardMetrics explorer] ページに移動します。

   Metrics Explorer に移動

   検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] である結果を選択します。

2. Google Cloud コンソールのツールバーで、Google Cloud プロジェクトを選択します。App Hub 構成の場合は、App Hub ホスト プロジェクトまたはアプリ対応フォルダの管理プロジェクトを選択します。
3. [指標] 要素の [指標を選択] メニューを開いてフィルタバーに「http_server」と入力し、サブメニューを使用して特定のリソースタイプと指標を選択します。
   1. [有効なリソース] メニューで、[Prometheus Target] を選択します。
   2. [有効な指標カテゴリ] メニューで、[Http] を選択します。
   3. [ACTIVE METRICS] メニューで指標を選択します。
   4. [適用] をクリックします。
4. データの表示方法を構成します。
   

   指標の測定値が累積の場合、Metrics Explorer はアライメント期間ごとに測定データを自動的に正規化し、グラフに率を表示します。詳細については、種類、タイプ、変換をご覧ください。

   2 つの counter 指標など、integer 値または double 値が測定されると、Metrics Explorer はすべての時系列を自動的に合計します。HTTP ルート /multi と /single のデータを表示するには、[集計] エントリの最初のメニューを [なし] に設定します。

   グラフの構成の詳細については、Metrics Explorer 使用時の指標の選択をご覧ください。

トレースを表示する

トレースデータが利用可能になるまでに数分かかることがあります。たとえば、プロジェクトでトレースデータが受信されたときに、Google Cloud Observability がそのデータを保存するデータベースを作成することが必要になる場合があります。データベースの作成には数分かかることがあり、その間トレースデータを表示することはできません。

トレースデータを表示するには、次の操作を行います。

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

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

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

2. ページの表セクションで、スパンの名称が /multi の行を選択します。

3. [トレースの詳細] パネルのガントチャートで、/multi というラベルのスパンを選択します。

   パネルが開き、HTTP リクエストに関する情報が表示されます。詳細には、メソッド、ステータス コード、バイト数、呼び出し元のユーザー エージェントが含まれます。

4. このトレースに関連付けられているログを表示するには、[ログとイベント] タブを選択します。

   このタブには、個々のログが表示されます。ログエントリの詳細を表示するには、ログエントリを開きます。[ログを表示] をクリックし、ログ エクスプローラを使用してログを表示することもできます。

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

ログを表示する

ログ エクスプローラではログを調査できます。また、関連するトレース（存在する場合）を確認することもできます。

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

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

   検索バーを使用してこのページを検索する場合は、小見出しが「Logging」の結果を選択します。

2. handle /multi request の説明を含むログを見つけます。

   ログの詳細を表示するには、ログエントリを開きます。

3. 「handle /multi request」メッセージを含むログエントリの [ トレース] をクリックし、[トレースの詳細表示] を選択します。

   [トレースの詳細] パネルが開き、選択したトレースが表示されます。

   ログデータは、トレースデータが利用可能になる数分前に利用可能になる場合があります。ID でトレースを検索するか、このタスクの手順に沿ってトレースデータを表示するときにエラーが発生した場合は、1～2 分待ってから操作を再試行してください。

ログ エクスプローラの使用方法については、ログ エクスプローラを使用してログを表示するをご覧ください。

次のステップ

• OpenTelemetry
• OTLP の仕様
• 構造化ロギング
• Managed Service for Prometheus のトラブルシューティング
• Cloud Trace のトラブルシューティング