Application Real-Time Monitoring Service:OpenTelemetry を使用した PHP アプリケーションからのトレースデータのレポート

ステップ 1：アプリケーションの作成

1. プロジェクトを初期化します。

      mkdir <project-name> && cd <project-name>

      composer init \
        --no-interaction \
        --stability beta \
        --require slim/slim:"^4" \
        --require slim/psr7:"^1"
      composer update

2. プロジェクトディレクトリ内に index.php ファイルを作成します。

      <?php
      use Psr\Http\Message\ResponseInterface as Response;
      use Psr\Http\Message\ServerRequestInterface as Request;
      use Slim\Factory\AppFactory;
   
      require __DIR__ . '/vendor/autoload.php';
   
      $app = AppFactory::create();
   
      $app->get('/rolldice', function (Request $request, Response $response) {
          $result = random_int(1,6);
          $response->getBody()->write(strval($result));
          return $response;
      });
   
      $app->run();

3. アプリケーションの動作を確認します：ブラウザで http://localhost:8080/rolldice を開きます。1 ～ 6 の範囲の乱数が表示されます。

      php -S localhost:8080

ステップ 2：OpenTelemetry PHP 拡張のビルド

1. ビルド依存関係をインストールします。

   • macOS:

     brew install gcc make autoconf

   • Linux (apt):

     sudo apt-get install gcc make autoconf

2. PECL を使用して拡張をビルドおよびインストールします：正常に完了した場合、以下のような出力が表示されます。

      pecl install opentelemetry

      Build process completed successfully
      Installing '/opt/homebrew/Cellar/php/8.2.8/pecl/20220829/opentelemetry.so'
      install ok: channel://pecl.php.net/opentelemetry-1.0.0beta6
      Extension opentelemetry enabled in php.ini

3. （任意）出力に Extension opentelemetry enabled in php.ini が含まれていない場合は、php.ini ファイルに手動で拡張を追加します。

      opentelemetry
      opentelemetry サポート => 有効
      拡張のバージョン => 1.0.0beta6

4. 拡張が読み込まれていることを確認します：期待される出力です。また、詳細な拡張情報は php --ri opentelemetry を実行して確認できます。

      php -m | grep opentelemetry

      opentelemetry

      opentelemetry
      opentelemetry support => enabled
      extension version => 1.0.0beta6

ステップ 3：イベントトラッキング依存関係のインストール

# gRPC 拡張のインストール（数分かかる場合があります）
pecl install grpc

composer config allow-plugins.php-http/discovery false
composer require \
  open-telemetry/sdk \
  open-telemetry/opentelemetry-auto-slim \
  open-telemetry/exporter-otlp \
  php-http/guzzle7-adapter \
  open-telemetry/transport-grpc

ステップ 4：イベントトラッキング対応アプリケーションの実行

OpenTelemetry SDK を構成する環境変数を指定してアプリケーションを起動します。

env OTEL_PHP_AUTOLOAD_ENABLED=true \
    OTEL_SERVICE_NAME=<your-service-name> \
    OTEL_TRACES_EXPORTER=otlp \
    OTEL_METRICS_EXPORTER=none \
    OTEL_LOGS_EXPORTER=none \
    OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
    OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint> \
    OTEL_EXPORTER_OTLP_HEADERS=Authentication=<token> \
    OTEL_PROPAGATORS=baggage,tracecontext \
    php -S localhost:8080

以下のプレースホルダーを実際の値に置き換えてください。

検証

1. ブラウザで http://localhost:8080/rolldice を開きます。各リクエストでトレースが自動的に生成されます。

2. OpenTelemetry 向けマネージドサービスコンソール にログインします。

3. アプリケーション ページで、ご自身のアプリケーションを見つけ、名前をクリックしてトレースを表示します。

コンソールにトレースが表示されるまで数分かかる場合があります。トレースが依然として表示されない場合は、OpenTelemetry 拡張が読み込まれていること（php -m | grep opentelemetry）、およびエンドポイントとトークンが正しいことを確認してください。

ステップ 1：アプリケーションの作成

自動イベントトラッキングの「ステップ 1：アプリケーションの作成」セクションと同じ手順に従って、Slim をベースとしたダイスロールアプリケーションを作成します。

ステップ 2：OpenTelemetry SDK 依存関係のインストール

HTTP クライアントライブラリおよび OpenTelemetry SDK パッケージをインストールします。エクスポートプロトコルに応じて、該当するタブを選択してください。

composer require guzzlehttp/guzzle

composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp

# gRPC 拡張がまだインストールされていない場合はインストールします
pecl install grpc
composer require open-telemetry/transport-grpc

composer require guzzlehttp/guzzle

composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp

ステップ 3：初期化コードの記述

opentelemetry_util.php ファイルを index.php と同じディレクトリ内に作成します。このファイルでは TracerProvider、エクスポーター、およびサンプラーを設定します。

<?php
use OpenTelemetry\API\Common\Instrumentation\Globals;
use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator;
use OpenTelemetry\Contrib\Otlp\SpanExporter;
use OpenTelemetry\SDK\Common\Attribute\Attributes;
use OpenTelemetry\SDK\Common\Export\Stream\StreamTransportFactory;
use OpenTelemetry\SDK\Resource\ResourceInfo;
use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
use OpenTelemetry\SDK\Sdk;
use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
use OpenTelemetry\SDK\Trace\Sampler\ParentBased;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessorBuilder;
use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\SemConv\ResourceAttributes;
use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory;
use OpenTelemetry\SDK\Common\Export\TransportFactoryInterface;

function initOpenTelemetry()
{
    // 1. サービスリソースを定義します
    $resource = ResourceInfoFactory::emptyResource()->merge(ResourceInfo::create(Attributes::create([
        ResourceAttributes::SERVICE_NAME => '<your-service-name>',  // 必須
        ResourceAttributes::HOST_NAME => '<your-host-name>'         // オプション
    ])));

    // 2. HTTP 経由でデータを送信する SpanExporter を作成します
    $transport = (new OtlpHttpTransportFactory())->create(
        '<http-endpoint>',
        'application/x-protobuf'
    );
    $spanExporter = new SpanExporter($transport);

    // 3. グローバルな TracerProvider をビルドして登録します
    $tracerProvider = TracerProvider::builder()
        ->addSpanProcessor(
            (new BatchSpanProcessorBuilder($spanExporter))->build()
        )
        ->setResource($resource)
        ->setSampler(new ParentBased(new AlwaysOnSampler()))
        ->build();

    Sdk::builder()
        ->setTracerProvider($tracerProvider)
        ->setPropagator(TraceContextPropagator::getInstance())
        ->setAutoShutdown(true)   // シャットダウン時に保留中のスパンをフラッシュします
        ->buildAndRegisterGlobal();
}
?>

<?php
use OpenTelemetry\API\Common\Instrumentation\Globals;
use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator;
use OpenTelemetry\Contrib\Otlp\SpanExporter;
use OpenTelemetry\SDK\Common\Attribute\Attributes;
use OpenTelemetry\SDK\Common\Export\Stream\StreamTransportFactory;
use OpenTelemetry\SDK\Resource\ResourceInfo;
use OpenTelemetry\SDK\Resource\ResourceInfoFactory;
use OpenTelemetry\SDK\Sdk;
use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
use OpenTelemetry\SDK\Trace\Sampler\ParentBased;
use OpenTelemetry\SDK\Trace\SpanProcessor\SimpleSpanProcessor;
use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessorBuilder;
use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\SemConv\ResourceAttributes;
use OpenTelemetry\Contrib\Otlp\OtlpHttpTransportFactory;
use OpenTelemetry\SDK\Common\Export\TransportFactoryInterface;

function initOpenTelemetry()
{
    // 1. サービスリソースを定義します
    $resource = ResourceInfoFactory::emptyResource()->merge(ResourceInfo::create(Attributes::create([
        ResourceAttributes::SERVICE_NAME => '<your-service-name>',  // 必須
        ResourceAttributes::HOST_NAME => '<your-host-name>'         // 任意
    ])));

    // 2. HTTP 経由でデータを送信する SpanExporter を作成します
    $transport = (new OtlpHttpTransportFactory())->create(
        '<http-endpoint>',
        'application/x-protobuf'
    );
    $spanExporter = new SpanExporter($transport);

    // 3. グローバル TracerProvider を構築および登録します
    $tracerProvider = TracerProvider::builder()
        ->addSpanProcessor(
            (new BatchSpanProcessorBuilder($spanExporter))->build()
        )
        ->setResource($resource)
        ->setSampler(new ParentBased(new AlwaysOnSampler()))
        ->build();

    Sdk::builder()
        ->setTracerProvider($tracerProvider)
        ->setPropagator(TraceContextPropagator::getInstance())
        ->setAutoShutdown(true)   // シャットダウン時に保留中のスパンをフラッシュします
        ->buildAndRegisterGlobal();
}
?>

ステップ 4：アプリケーションへのイベントトラッキングの追加

index.php を更新して、OpenTelemetry の初期化およびスパンの作成を行います。

1. index.php の先頭で必要なパッケージをインポートし、OpenTelemetry を初期化します。

      <?php
      use OpenTelemetry\API\Common\Instrumentation\Globals;
      use OpenTelemetry\SDK\Common\Attribute\Attributes;
      use OpenTelemetry\SDK\Trace\TracerProvider;
   
      require __DIR__ . '/opentelemetry_util.php';
   
      // OpenTelemetry の初期化：サービス名、エクスポーター、グローバル TracerProvider の設定
      initOpenTelemetry();

2. /rolldice ルートでリクエストレベルのトレースをキャプチャするスパンを作成します。

      $app->get('/rolldice', function (Request $request, Response $response) {
          // トレーサーインスタンスを取得します
          $tracer = \OpenTelemetry\API\Globals::tracerProvider()->getTracer('my-tracer');
   
          // この操作のスパンを開始します
          $span = $tracer->spanBuilder("/rolldice")->startSpan();
          $span->setAttribute("http.method", "GET");
          $span->addEvent("Init");
   
          // 属性付きイベントを設定します
          $eventAttributes = Attributes::create([
              "key1" => "value",
              "key2" => 3.14159,
          ]);
   
          // ビジネスロジック
          $result = random_int(1,6);
          $response->getBody()->write(strval($result));
   
          $span->addEvent("End");
          $span->end();
   
          return $response;
      });

3. マルチステップ操作をトレースするためにネストされたスパンを作成します。/rolltwodices ルートは、親子スパン関係を示す例です。

      $app->get('/rolltwodices', function (Request $request, Response $response) {
          $tracer = \OpenTelemetry\API\Globals::tracerProvider()->getTracer('my-tracer');
   
          // 親スパンを作成します
          $parentSpan = $tracer->spanBuilder("/rolltwodices/parent")->startSpan();
          $scope = $parentSpan->activate();
   
          $value1 = random_int(1,6);
   
          // 親スコープ内で子スパンを作成します
          $childSpan = $tracer->spanBuilder("/rolltwodices/parent/child")->startSpan();
   
          // ビジネスロジック
          $value2 = random_int(1,6);
          $result = "dice1: " . $value1 . ", dice2: " . $value2;
   
          // スパンを終了し、スコープをデタッチします
          $childSpan->end();
          $parentSpan->end();
          $scope->detach();
   
          $response->getBody()->write(strval($result));
          return $response;
      });

4. スパン上で例外を記録します。/error ルートは、例外処理の例です。

      $app->get('/error', function (Request $request, Response $response) {
          $tracer = \OpenTelemetry\API\Globals::tracerProvider()->getTracer('my-tracer');
          $span3 = $tracer->spanBuilder("/error")->startSpan();
   
          try {
              // 例外をシミュレートします
              throw new \Exception('exception!');
          } catch (\Throwable $t) {
              // スパンをエラーとしてマークします
              $span3->setStatus(\OpenTelemetry\API\Trace\StatusCode::STATUS_ERROR, "exception in span3!");
              // スタックトレース付きで例外を記録します
              $span3->recordException($t, ['exception.escaped' => true]);
          } finally {
              $span3->end();
              $response->getBody()->write("error");
              return $response;
          }
      });

ステップ 5：実行および検証

1. アプリケーションを起動します。

      php -S localhost:8080

2. トレースデータを生成するためにリクエストを送信します。

      http://localhost:8080/rolldice
      http://localhost:8080/rolltwodices
      http://localhost:8080/error

3. OpenTelemetry 向けマネージドサービスコンソール にログインします。アプリケーション ページで、ご自身のアプリケーションを見つけ、名前をクリックしてトレースを表示します。

コンソールにトレースが表示されるまで数分かかる場合があります。トレースが依然として表示されない場合は、エンドポイントおよびトークンが正しいこと、およびサーバーがネットワーク経由でエンドポイントに到達できることを確認してください。