PHP のゼロコード計装¶
Beacon PHP には PHP 8.2 以降、アプリケーションにインストールした Composer パッケージ、実行環境に合う Beacon ネイティブ拡張が必要です。
接続前に共通設定を完了し、DataKit OpenTelemetry コレクターを有効にしてください。以下は Linux/macOS のシェルの例で、アプリケーションと DataKit が同じホストにあることを前提とします。別ホストやコンテナに配置する場合は、127.0.0.1 を置き換え、リッスンアドレスを調整してください。
インストール¶
- ネイティブ拡張のリリースページから、PHP のバージョン、スレッドセーフモード、OS、アーキテクチャに合うビルドをダウンロードし、拡張を有効にします。
- アプリケーションのルートに
.beaconディレクトリを作成し、Beacon PHP のリリースページから Composer ZIP アーティファクトをダウンロードして配置します。その後、使用するフレームワークの計装パッケージをインストールします。
composer config repositories.beacon artifact "$PWD/.beacon"
composer require beacon-observability/beacon-php
vendor/bin/beacon-php install pdo guzzle
vendor/bin/beacon-php components を実行すると、ほかのコンポーネントのエイリアスを確認できます。
起動¶
export OTEL_PHP_AUTOLOAD_ENABLED=true
export OTEL_SERVICE_NAME=my-php-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:9529/otel
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
vendor/bin/beacon-php doctor
php public/index.php
PHP-FPM を使用する場合は、サービスの実行環境に同じ変数を設定し、ワーカーを再起動してください。Beacon PHP は現在 Profile コンポーネントを提供していません。
デバッグと診断¶
まず実行環境の診断レポートを生成し、SDK の内部診断ログを有効にします。上記の自動読み込みと OTLP 設定を保持してください。
vendor/bin/beacon-php doctor --json > beacon-php-doctor.json
OTEL_LOG_LEVEL=debug OTEL_PHP_LOG_DESTINATION=stderr \
php public/index.php > beacon-php-debug.log 2>&1
doctor は PHP、ネイティブ拡張、SDK、Exporter、コンポーネント、ゼロコード設定を確認しますが、実際の OTLP 配信は検証しません。OTEL_PHP_LOG_DESTINATION=stderr は SDK 内部ログを標準エラーに出力し、上のコマンドでファイルに保存します。
PHP-FPM では、実際のワーカー環境にこの 2 つの変数を注入してワーカーを再起動し、FPM のログ設定に従って標準エラーを収集してください。CLI と FPM では、php.ini、拡張、環境変数が異なる場合があります。CLI の doctor の結果だけで FPM の実行環境を確認することはできません。
調査後は通常の起動コマンドに戻すか、FPM またはサービスの設定からデバッグ変数を削除して再起動してください。
接続の確認¶
対応するフレームワークやライブラリを経由するリクエストをアプリケーションの API に送り、Guance の「APM > トレース」で上記のサービス名を絞り込んでください。確認手順の詳細は共通設定を、データがない場合はトラブルシューティングを参照してください。