PHP 用 Cloud Trace の設定

PHP アプリケーション用の Cloud Trace を有効にするには、OpenCensus を使用します。OpenCensus は、複数のバックエンドで機能するトレースと指標データを収集するための、一連のインストゥルメンテーション ライブラリです。PHP 用の OpenCensus に関する最新情報、その他のドキュメントとサンプルについては、opencensus-php-exporter-stackdriver をご覧ください。

ライブラリのインストール

  1. OpenCensus Stackdriver exporter composer パッケージをインストールします。

    composer require opencensus/opencensus-exporter-stackdriver
    

    上記のコマンドは、OpenCensus パッケージと Trace composer パッケージもインストールします。

  2. このページの後半セクションで説明するフレームワークの統合を使用するには、OpenCensus の拡張機能をインストールします。

    pecl install opencensus-alpha
    
  3. php.ini ファイルに次の行を追加します。

    extension=opencensus.so
    
  4. Windows 環境の場合は、pecl のダウンロード ページから PHP インストールの拡張ディレクトリに DLL ファイルをダウンロードし、php.ini ファイルに次の行を追加します。

    extension=opencensus.dll
    

クライアントの構成

PHP 用 OpenCensus ライブラリを有効にするには、次の手順を実行します。

  1. 必要なクラスを読み込みます。

    use OpenCensus\Trace\Exporter\StackdriverExporter;
    use OpenCensus\Trace\Tracer;
    
  2. StackdriverExporter オブジェクトを初期化します。

    $exporter = new StackdriverExporter([
        'clientConfig' => [
            'projectId' => $projectId
        ]
    ]);

    Google Cloud インフラストラクチャ上で実行している場合、projectId を Google Cloud プロジェクト ID に設定する必要はありません。このフィールドを設定しない場合、PHP 用クライアント ライブラリは Google Cloud メタデータ サーバーからこのデータを自動的に収集します。

    Google Cloud インフラストラクチャ上で実行していない場合は、Google Cloud プロジェクト ID をアプリケーションに指定する必要があります。

    インフラストラクチャに関係なく、PHP の場合、Google Cloud プロジェクト ID を明示的に設定しないと、OpenCensus によって呼び出される google-cloud PHP ライブラリは、環境変数 GOOGLE_CLOUD_PROJECT が設定されているかどうかを自動的に判断します。設定されている場合、ライブラリは Google Cloud プロジェクト ID として GOOGLE_CLOUD_PROJECT の値を使用します。詳細については、認証をご覧ください。環境変数を設定するには、次のようにします。

    Linux または macOS

    export GOOGLE_CLOUD_PROJECT=your-project-id

    Windows

    set GOOGLE_CLOUD_PROJECT=your-project-id

    PowerShell:

    $env:GOOGLE_CLOUD_PROJECT="your-project-id"
  3. トレーサーを起動します。

    Tracer::start($exporter);

エクスポータを作成し、アプリケーションのできるだけ早い段階でトレーサーを起動します。

カスタマイズ

PHP 用 Cloud Trace ライブラリの動作をカスタマイズできます。エクスポータ構成オプションの一覧については、opencensus-php-exporter-stackdriver または OpenCensus PHP API をご覧ください。

App Engine フレキシブル環境では、バックグラウンド プロセスによってデータが送信されるため、トレースデータのレポートのパフォーマンスに対する影響を軽減できます。 バックグラウンド レポートを有効にする方法は次のとおりです。

  1. app.yaml ファイルの runtime_config セクションを変更して、enable_stackdriver_integration フラグを指定します。

    enable_stackdriver_integration: true

    このフラグにより、PHP バッチ処理デーモン BatchRunner が生成されます。

  2. 環境変数 IS_BATCH_DAEMON_RUNNINGtrue に設定します。

  3. OpenCensus StackdriverExporter に渡される clientConfig オプションに、値を true に設定された async オプションを含めます。 詳細については、StackdriverExporter をご覧ください。

カスタム トレーススパンの追加

PHP 用 Cloud Trace ライブラリは、HTTP リクエストごとにトレース レコードを自動的に作成します。リクエスト内にカスタム トレーススパンを追加することもできます。

Tracer::inSpan(
    ['name' => 'slow_function'],
    function () {
        sleep(1);
    }
);

フレームワークの統合

OpenCensus ライブラリは、ウェブのフレームワークと機能に役立つ統合を提供します。詳細については、使用できる統合フレームワークの例をご覧ください。

プラットフォームの構成

Cloud Trace は Google Cloud と他のプラットフォームで使用できます。

Google Cloud での実行

アプリケーションが Google Cloud で実行されている場合、認証情報をサービス アカウントの形式でクライアント ライブラリに提供する必要はありません。ただし、Google Cloud Platform で Cloud Trace API のアクセス スコープが有効になっている必要があります。

次の構成では、デフォルトのアクセス スコープ設定により Cloud Trace API が有効化されます。

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

  • Google Kubernetes Engine(GKE)

  • Compute Engine

カスタム アクセス スコープを使用する場合は、Cloud Trace API のアクセス スコープを有効にする必要があります。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 に関する問題のトラブルシューティングについては、トラブルシューティング ページをご覧ください。

リソース