このドキュメントでは、オープンソースの OpenTelemetry フレームワークを使用してトレースと指標データを収集するように Python アプリを変更する方法と、構造化 JSON ログを標準出力に出力する方法について説明します。このドキュメントでは、インストールして実行できる Python サンプルアプリについても説明します。このアプリは Flask ウェブ フレームワークを使用し、指標、トレース、ログを生成するように構成されています。
計測について詳しくは、次のドキュメントをご覧ください。
手動インストルメンテーションとゼロコード インストルメンテーションについて
この言語について、OpenTelemetry はゼロコード インストルメンテーションを、コードを変更せずにライブラリとフレームワークからテレメトリーを収集する手法と定義しています。ただし、モジュールをインストールし、環境変数を設定する必要があります。
このドキュメントでは、ゼロコード インストルメンテーションについては説明しません。このトピックについては、Python zero-code instrumentation をご覧ください。
一般的な情報については、OpenTelemetry Instrumentation for Python をご覧ください。
始める前に
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
Install the Google Cloud CLI.
-
外部 ID プロバイダ(IdP)を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。
-
gcloud CLI を初期化するには、次のコマンドを実行します。
gcloud init
-
Create or select a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles.gcloud services enable logging.googleapis.com
monitoring.googleapis.com cloudtrace.googleapis.com -
Install the Google Cloud CLI.
-
外部 ID プロバイダ(IdP)を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。
-
gcloud CLI を初期化するには、次のコマンドを実行します。
gcloud init
-
Create or select a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_ID
with a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_ID
with your Google Cloud project name.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles.gcloud services enable logging.googleapis.com
monitoring.googleapis.com cloudtrace.googleapis.com Cloud Shell、 Google Cloudリソース、ローカル開発環境でサンプルを実行する場合は、このセクションに記載されている権限で十分です。本番環境アプリケーションの場合、通常、サービス アカウントはログ、指標、トレースデータを書き込む認証情報を提供します。
サンプル アプリケーションがログ、指標、トレースデータを書き込むために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
-
ログ書き込み(
roles/logging.logWriter
) -
モニタリング指標の書き込み(
roles/monitoring.metricWriter
) -
Cloud トレース エージェント(
roles/cloudtrace.agent
)
ログ、指標、トレースデータを表示するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。
-
ログ閲覧者(
roles/logging.viewer
) -
モニタリング閲覧者(
roles/monitoring.viewer
) -
Cloud トレース ユーザー(
roles/cloudtrace.user
)
ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。
-
ログ書き込み(
logging.googleapis.com/trace
: ログエントリに関連付けられているトレースのリソース名。logging.googleapis.com/spanId
: ログエントリに関連付けられているトレースのスパン ID。logging.googleapis.com/trace_sampled
: このフィールドの値はtrue
またはfalse
にする必要があります。/multi
エンドポイントは、multi
関数によって処理されます。アプリの負荷生成ツールが/multi
エンドポイントにリクエストを発行します。このエンドポイントは、リクエストを受信すると、ローカル サーバーの/single
エンドポイントに 3~7 件のリクエストを送信します。/single
エンドポイントは、single
関数によって処理されます。このエンドポイントは、リクエストを受信すると、少しの間スリープしてから、文字列で応答します。-
In the Google Cloud console, 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.
リポジトリのクローンを作成します。
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python
サンプル ディレクトリに移動します。
cd opentelemetry-operations-python/samples/instrumentation-quickstart
サンプルをビルドして実行します。
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
Prometheus/http_server_duration_milliseconds/histogram
は、サーバー リクエストの所要時間を記録し、結果をヒストグラムに保存します。Prometheus/http_client_duration_milliseconds/histogram
は、クライアント リクエストの所要時間を記録し、結果をヒストグラムに保存します。-
Google Cloud コンソールで leaderboard [Metrics Explorer] のページに移動します。
検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] の結果を選択します。
- Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub の構成には、App Hub ホスト プロジェクトまたはアプリ管理用フォルダの管理プロジェクトを選択します。
- [指標] 要素の [指標を選択] メニューを開いてフィルタバーに「
http_server
」と入力し、サブメニューを使用して特定のリソースタイプと指標を選択します。- [有効なリソース] メニューで、[Prometheus Target] を選択します。
- [有効な指標カテゴリ] メニューで、[Http] を選択します。
- [ACTIVE METRICS] メニューで指標を選択します。
- [適用] をクリックします。
クエリ結果から時系列を削除するフィルタを追加するには、[フィルタ] 要素を使用します。
- データの表示方法を構成します。
指標の測定値が累積の場合、Metrics Explorer はアライメント期間ごとに測定データを自動的に正規化し、グラフに率を表示します。詳細については、種類、タイプ、変換をご覧ください。
2 つの
counter
指標など、integer 値または double 値が測定されると、Metrics Explorer はすべての時系列を自動的に合計します。HTTP ルート/multi
と/single
のデータを表示するには、[集計] エントリの最初のメニューを [なし] に設定します。グラフの構成の詳細については、Metrics Explorer 使用時の指標の選択をご覧ください。
-
Google Cloud コンソールで、[Trace エクスプローラ] ページに移動します。
このページは、検索バーを使用して見つけることもできます。
- ページの表セクションで、スパンの名称が
/multi
の行を選択します。 [トレースの詳細] パネルのガントチャートで、
/multi
というラベルのスパンを選択します。パネルが開き、HTTP リクエストに関する情報が表示されます。詳細には、メソッド、ステータス コード、バイト数、呼び出し元のユーザー エージェントが含まれます。
このトレースに関連付けられているログを表示するには、[ログとイベント] タブを選択します。
このタブには、個々のログが表示されます。ログエントリの詳細を表示するには、ログエントリを開きます。[ログを表示] をクリックし、ログ エクスプローラを使用してログを表示することもできます。
-
Google Cloud コンソールで [ログ エクスプローラ] ページに移動します。
検索バーを使用してこのページを検索する場合は、小見出しが「Logging」の結果を選択します。
handle /multi request
の説明を含むログを見つけます。ログの詳細を表示するには、ログエントリを開きます。
「handle /multi request」メッセージを含むログエントリの [
トレース] をクリックし、[トレースの詳細表示] を選択します。
[トレースの詳細] パネルが開き、選択したトレースが表示されます。
ログデータは、トレースデータが利用可能になる数分前に利用可能になる場合があります。ID でトレースを検索するか、このタスクの手順に沿ってトレースデータを表示するときにエラーが発生した場合は、1~2 分待ってから操作を再試行してください。
アプリを計測してトレース、指標、ログを収集する
アプリを計測して、トレースと指標データを収集し、構造化 JSON を標準出力に出力するには、このドキュメントの以降のセクションで説明する手順を実施します。
OpenTelemetry を構成する
このサンプルアプリは、OpenTelemetry Python SDK を使用して OTLP プロトコルでトレースと指標をエクスポートするように構成されています。デフォルトでは、OpenTelemetry Python SDK はトレース コンテキストの伝播に W3C トレース コンテキスト形式を使用します。これにより、トレース内でスパンが正しい親子関係を持つことが保証されます。
次のコードサンプルでは、OpenTelemetry を設定するための Python モジュールを示します。サンプル全体を表示するには、more_vert(その他アイコン)をクリックして、[GitHub で表示] を選択します。
Flask アプリは、Flask の本番環境へのデプロイガイドの推奨事項に従い、Gunicorn を使用して HTTP リクエストを処理します。Gunicorn は、独立したワーカー プロセスで実行されるアプリの複数のコピーを起動して、スループットを向上させます。ワーカー プロセスの指標が互いに競合しないようにするには、各ワーカー プロセスで service.instance.id
リソース属性に一意の値を設定することをおすすめします。これを行う一つの方法は、service.instance.id
にプロセス ID を含めることです。詳細については、時系列の衝突をご覧ください。
詳細と構成オプションについては、OpenTelemetry Python 計測をご覧ください。
構造化ロギングを構成する
トレースにリンクされた構造化ログを書き込むには、トレース情報を含むキーを使用して JSON 形式のログを標準出力に出力するようにアプリを構成します。次のコードサンプルは、python-json-logger
ライブラリを使用して JSON 構造化ログを出力するように標準の logging
ライブラリを構成する方法と、opentelemetry-instrumentation-logging
パッケージを使用してトレース情報を含める方法を示しています。
前の構成では、アクティブなスパンに関する情報がログメッセージから抽出され、抽出された情報が JSON 構造化ログに属性として追加されます。これらの属性を使用して、ログをトレースに関連付けることができます。
これらのフィールドの詳細については、LogEntry
構造体をご覧ください。
テレメトリーを収集するように構成されたサンプルアプリを実行する
サンプルアプリでは、ログに JSON、指標とトレースに OTLP を使用するなど、ベンダーに依存しない形式を使用しています。アプリからのテレメトリーは、Google エクスポータで構成された OpenTelemetry Collector
を使用して Google Cloud に転送されます。Flask を使用して HTTP リクエストを処理し、requests ライブラリを使用して HTTP リクエストを送信します。HTTP クライアントとサーバーの指標とトレースを生成するため、サンプルアプリは opentelemetry-instrumentation-flask
インストルメンテーション ライブラリと opentelemetry-instrumentation-requests
インストルメンテーション ライブラリをインストールします。
このアプリには 2 つのエンドポイントがあります。
アプリをダウンロードしてデプロイする
サンプルを実行するには、次の操作を行います。
指標を表示する
サンプルアプリの OpenTelemetry 計測は、Metrics Explorer で表示可能な Prometheus 指標を生成します。
トレースを表示する
トレースデータが利用可能になるまでに数分かかることがあります。たとえば、プロジェクトでトレースデータが受信されたときに、Google Cloud Observability がそのデータを保存するデータベースを作成することが必要になる場合があります。データベースの作成には数分かかることがあり、その間トレースデータを表示することはできません。
トレースデータを表示するには、次の操作を行います。
Cloud Trace エクスプローラの使用方法について詳しくは、トレースを検索して調査するをご覧ください。
ログを表示する
ログ エクスプローラではログを調査できます。また、関連するトレース(存在する場合)を確認することもできます。
ログ エクスプローラの使用方法については、ログ エクスプローラを使用してログを表示するをご覧ください。