https://mackerel.io/ja/docs/entry/tracing/installations/php

このページでは、PHPのアプリケーションからMackerelにトレースを送信する方法を解説します。

概要

MackerelはOpenTelemetryの仕組み（計装）を利用してトレースを取得します。OpenTelemetryに対応したトレースはさまざまな方法で取得できますが、今回はゼロコード計装と呼ばれる、アプリケーションの実装を変更せずにトレースを送信する方法を解説します。

📝 補足

PHPのゼロコード計装は、ライブラリ等で計装対象となるメソッドの実行前後に観測用関数を実行することで実現されています。詳しくはPHP zero-code instrumentationをご確認ください。

動作要件

OpenTelemetryの動作要件として、PHPが指定されたバージョン以上である必要があります。

PHP8.0以上

導入方法

アプリケーションからMackerelへトレースを送信するために、以下をおこないます。

拡張ライブラリ（PECL）の追加
パッケージのインストール
環境変数の設定

1. 拡張ライブラリ（PECL）の追加

PECLを使用してPHPにOpenTelemetry用の拡張ライブラリをインストールします。

pecl install opentelemetry

その後、インストールした拡張を php.ini に追加します。

[opentelemetry]
extension=opentelemetry.so

2. パッケージのインストール

composerを使用してアプリケーションにOpenTelemetryの導入に必要なパッケージをインストールします。

composer require open-telemetry/api \
  open-telemetry/exporter-otlp \
  open-telemetry/opentelemetry-auto-http-async \
  open-telemetry/opentelemetry-auto-io \
  open-telemetry/opentelemetry-auto-laravel \
  open-telemetry/opentelemetry-auto-pdo \
  open-telemetry/opentelemetry-auto-psr3 \
  open-telemetry/opentelemetry-auto-psr15 \
  open-telemetry/opentelemetry-auto-psr18 \
  open-telemetry/sdk

open-telemetry/opentelemetry-auto-laravelがLaravel向けのパッケージです。たとえばslim向けにはopen-telemetry/opentelemetry-auto-slimというパッケージが提供されています。

提供されているパッケージは以下のページで検索できます。

opentelemetry.io

📝 補足

お使いのフレームワークやアプリケーション向けの計測ライブラリが存在しない場合は、独自に計装することもできます。詳しくはOpenTelemetry公式ドキュメントの PHP zero-code instrumentation | How it works をご確認ください。

3. 環境変数の設定

パッケージのインストール後、Mackerelにトレースを送信するための環境変数を設定します。以下はLaravelプロジェクト内の.envファイルを利用して設定する例です。

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_TRACES_EXPORTER=otlp
OTEL_SERVICE_NAME=my-sample-app
# 標準出力に出力する場合
# OTEL_TRACES_EXPORTER=console
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp-vaxila.mackerelio.com/v1/traces
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Accept=*/*,Mackerel-Api-Key=${MACKEREL_APIKEY}"
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none
OTEL_PROPAGATORS=baggage,tracecontext

OTEL_TRACES_EXPORTERをconsoleにするとトレースが標準出力に出力されます。
OTEL_SERVICE_NAMEはトレースのサービス名（service.name属性の値）になります。
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTはトレースの送信先の指定です。
- Mackerelに直接送信する場合はhttps://otlp-vaxila.mackerelio.com/v1/tracesを指定します。
- Collectorを利用して送信する場合はhttp://<Collectorのアドレス:ポート>/v1/tracesを指定します。
${MACKEREL_APIKEY}はMackerelのAPIキーの指定です。APIキーの一覧から、Write権限のあるAPIキーをアプリケーションが動作するシステム内の環境変数に定義してください。
- 環境変数ではなくAPIキーを直接記述しても動作します。

環境変数の設定後、アプリケーションを起動するとトレースが送信されます。

トレースを確認する

送信されたトレースは以下の手順で確認できます。

メニューの「APM」を選択
サービス名を選択
「トレース」タブを選択
トレース一覧からトレースを選択すると詳細が確認できます

以上、PHPで作成されたアプリケーションにゼロコード計装をおこなって、Mackerelへトレースを投稿する方法のご紹介でした。