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

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

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

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

注: このドキュメントには、動作中のアプリケーションの一部のみが表示されます。たとえば、このサンプルには、インポートされたパッケージのリストは表示されません。ただし、アプリケーション全体は GitHub で入手できます。サンプル全体を表示するには、 [その他] をクリックして、[GitHub で表示] を選択します。

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

この言語について、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 the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• 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 the serviceusage.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 the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• 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 the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

1. 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）

   ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

   必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

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

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

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

OpenTelemetry を構成する

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

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

def setup_opentelemetry() -> None:
    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()}",
        }
    )
    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
    logs.set_logger_provider(logger_provider)

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

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

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

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

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

class JsonFormatter(jsonlogger.JsonFormatter):
    def formatTime(self, record: logging.LogRecord, datefmt: Optional[str] = None):
        # Format the timestamp as RFC 3339 with microsecond precision
        isoformat = datetime.fromtimestamp(record.created).isoformat()
        return f"{isoformat}Z"


def setup_structured_logging() -> None:
    LoggingInstrumentor().instrument()

    log_handler = logging.StreamHandler()
    formatter = 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",
        },
    )
    log_handler.setFormatter(formatter)
    logging.basicConfig(
        level=logging.INFO,
        handlers=[log_handler],
    )

前の構成では、アクティブなスパンに関する情報がログメッセージから抽出され、抽出された情報が 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__)

# Initialize OpenTelemetry Python SDK and structured logging
setup_opentelemetry()
setup_structured_logging()

app = Flask(__name__)

# Add instrumentation
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."""
      sub_requests = randint(3, 7)
      logger.info("handle /multi request", extra={"subRequests": sub_requests})
      for _ in range(sub_requests):
          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)
      logger.info("handle /single request", extra={"duration": duration})
      time.sleep(duration)
      return f"slept {duration} seconds"
  
  

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

注: Cloud Shell を使用してサンプルアプリを実行することをおすすめします。ただし、Linux または Mac でサンプルアプリをローカルで実行する場合は、次のステップの最初の手順は省略してください。

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

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 コンソールで [Metrics 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. クエリ結果から時系列を削除するフィルタを追加するには、[フィルタ] 要素を使用します。

5. データの表示方法を構成します。
   

   指標の測定値が累積の場合、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 のトラブルシューティング