PHP アプリケーションのトレース

互換性要件

サポート対象のライブラリと言語の一覧については、互換性要件ページをご覧ください。

インストールと利用開始

アプリ内のドキュメントに従ってください (推奨)

Datadog アプリ内のクイックスタート手順に従って、最高のエクスペリエンスを実現します。例:

• デプロイコンフィギュレーション (ホスト、Docker、Kubernetes、または Amazon ECS) を範囲とする段階的な手順。
• service、env、version タグを動的に設定します。
• セットアップ中のすべてのトレースの取り込みを有効にします。

APM で使用される用語の説明は、公式ドキュメントを参照してください。

PHP トレーサーのオープンソースに対する貢献に関しては、コントリビューションガイドを参照してください。

APM に Datadog Agent を構成する

インスツルメントされたアプリケーションからトレースを受信するように Datadog Agent をインストールして構成します。デフォルトでは、Datadog Agent は datadog.yaml ファイルの apm_enabled: true で有効になっており、localhost:8126 でトレーストラフィックをリッスンします。コンテナ化環境の場合、以下のリンクに従って、Datadog Agent 内でトレース収集を有効にします。

• Dropdown

1. メインの datadog.yaml コンフィギュレーションファイルで apm_non_local_traffic: true を設定します

2. コンテナ化された環境でトレースを受信するように Agent を構成する方法については、それぞれの説明を参照してください。

3. アプリケーションをインスツルメント化した後、トレースクライアントはデフォルトでトレースを localhost:8126 に送信します。これが正しいホストとポートでない場合は、以下の環境変数を設定して変更します。

DD_AGENT_HOST と DD_TRACE_AGENT_PORT

変数の設定方法については、トレーサーコンフィギュレーションを参照してください。

AWS Lambda で Datadog APM を設定するには、サーバーレス関数のトレースドキュメントを参照してください。

トレースは、Heroku、Cloud Foundry、AWS Elastic Beanstalk、Azure App Services Extension など、他の多くの環境で利用できます。

その他の環境については、その環境のインテグレーションのドキュメントを参照し、セットアップの問題が発生した場合はサポートにお問い合わせください。

拡張機能をインストール

対応するディストリビューション用にプリコンパイルされたパッケージの 1 つを使用して PHP 拡張機能をインストールします。

ダウンロードしたら、次のコマンドを使いパッケージをインストールします。

# RPM パッケージを使用 (RHEL/Centos 6 以降、Fedora 20 以降)
rpm -ivh datadog-php-tracer.rpm

# DEB パッケージを使用 (Debian Jessie 以降、対応するバージョンの PHP にインストールされた Ubuntu 14.04 以降)
dpkg -i datadog-php-tracer.deb

# APK パッケージを使用 (Alpine)
apk add datadog-php-tracer.apk --allow-untrusted

デフォルトの PHP バージョンの拡張機能がインストールされます。特定の PHP バージョンの拡張機能をインストールするには、インストールを実施する前に DD_TRACE_PHP_BIN 環境変数を使用してターゲット PHP バイナリの場所を設定します。

export DD_TRACE_PHP_BIN=$(which php-fpm7)

PHP (PHP-FPM または Apache SAPI) を再起動し、アプリケーションのトレース可能なエンドポイントにアクセスします。APM UI でトレースを確認できます。

注: トレースが UI に表示されるまでに数分かかる場合があります。数分たってもトレースが表示されない場合は、ホストマシンから phpinfo() ページを作成して、“ddtrace” セクションまでスクロールします。失敗した診断チェックがここに表示され、問題を特定するのに役立ちます。

ディストリビューションが見つからない場合は、PHP 拡張機能を手動でインストールします。

自動でデータと収集

トレースはデフォルトで自動的に有効になります。拡張機能がインストールされると、ddtrace はアプリケーションをトレースし、Agent へトレースを送ります。

Datadog はそのままの状態ですべてのウェブフレームワークをサポートします。自動インスツルメンテーションは、特定の関数やメソッドをトレースするためにラップするよう PHP のランタイムを変更しことで実行されます。PHP トレーサーは、複数のライブラリの自動インスツルメンテーションをサポートします。

自動インスツルメンテーションは以下を取得します。

• メソッド実行時間
• Web リクエスト用 URL やステータスレスポンスコード、またはデータベースアクセス用 SQL クエリなどの関連するトレースデータ
• 未処理の例外（該当する場合スタックトレースを含む）
• Web リクエストなど、システムを通過するトレースの合計数

注: アプリケーションが Composer や spl_autoload_register() で登録されたオートローダーを使用しない場合、環境変数を DD_TRACE_NO_AUTOLOADER=true と設定し、自動インスツルメンテーションを有効にします。

コンフィギュレーション

PHP トレーサーは環境変数で設定できます。

注: コードの自動インスツルメンテーションを使用する場合（推奨されるアプローチ）、インスツルメンテーションコードはどのユーザーコードよりも先に実行されることに注意してください。そのため、以下の環境変数はサーバーレベルで設定し、ユーザーコードが実行される前に PHP ランタイムで使用できるようにします。たとえば、putenv() や .env ファイルは機能しません。

Apache

php-fpm を使用する Apache の場合、www.conf コンフィギュレーションファイルの env ディレクトリを使用して php トレーサーを構成します。次に例を示します。

; ホスト環境変数 SOME_ENV を
; DD_AGENT_HOST として PHP プロセスへ渡す例
env[DD_AGENT_HOST] = $SOME_ENV
; Example of passing the value 'my-app' to the PHP
; process as DD_SERVICE
env[DD_SERVICE] = my-app

サーバーコンフィギュレーション、仮想ホスト、ディレクトリ、または .htaccess ファイルから SetEnv を使用することも可能です。

SetEnv DD_TRACE_DEBUG true

NGINX

NGINX の場合、php-fpm の www.conf ファイルの env ディレクティブを使用します。次に例を示します。

; ホスト環境変数 SOME_ENV を
; DD_AGENT_HOST として PHP プロセスへ渡す例
env[DD_AGENT_HOST] = $SOME_ENV
; Example of passing the value 'my-app' to the PHP
; process as DD_SERVICE
env[DD_SERVICE] = my-app

注: NGINX サーバーで APM を有効にしている場合、分散トレースが正常に機能するように opentracing_fastcgi_propagate_context 設定を適切に構成してください。詳細は、NGINX APM コンフィギュレーションを参照してください。

PHP CLI サーバー

コマンドラインで設定しサーバーを起動します。

DD_TRACE_DEBUG=true php -S localhost:8888

環境変数コンフィギュレーション

インテグレーション名

以下の表は、各インテグレーションに紐付くデフォルトのサービス名をまとめたものです。サービス名は DD_SERVICE_MAPPING に変更してください。

インテグレーション固有のコンフィギュレーションを設定する場合は、DD_TRACE_<INTEGRATION>_ANALYTICS_ENABLED の形式で名前をつけてください。例: Laravel の場合、DD_TRACE_LARAVEL_ANALYTICS_ENABLED

リソース名を正規化された URI にマッピング

HTTP サーバーとクライアントインテグレーションでは、URL はクエリ文字列が URL から削除された状態で、トレースリソース名を作成するために <HTTP_REQUEST_METHOD> <NORMALIZED_URL> の形式で使用されます。URL を正規化し 1 つのリソースの下に一般的なエンドポイントをグループ化することで、自動インスツルメンテーションされないカスタムフレームワークにおける可視性を向上することができます。

数値 ID、UUID (ダッシュの有無不問)、32〜512 ビットの 16 進数ハッシュは、自動的に ? に置換されます。

DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED=false を使用してこの機能をオフにすることも可能です。

カスタム URL からリソースマッピング

適用された自動正規化ではカバーされないケースがいくつかあります。

自動正規化ではカバーされないシナリオには、次の 2 つのクラスがあります。

• 正規化するパスフラグメントには再現可能なパターンがあり、URL の任意の部分で存在できます（上記の例では id<number>）。このシナリオは、次の DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX 設定でカバーされます。
• 何でもパスフラグメントになれますが、前のパスフラグメントは値が正規化されるべきことを示します。たとえば /cities/new-york は、new-york は都市名のため正規化する必要があることが分かります。このシナリオは以下の設定でカバーされます DD_TRACE_RESOURCE_URI_MAPPING_INCOMING、 DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING（それぞれ、受信リクエストと発信リクエスト）。

DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX

この設定は、各パスフラグメントに個々に適用される正規表現の CSV です。たとえば、最初の例、 /using/prefix/id123/for/id で DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX を ^id\d+$ に設定すると、すべてのフラグメント（using、prefix、id123、for、id）に正規表現が適用されます。最終的な正規化されたリソース名は、GET /using/prefix/?/for/id になります。

カンマで区切られた複数の正規表現を ^id\d+$,code\d+$ に追加することができますが、カンマ文字 , はエスケープされないので正規表現では使用できないことに注意してください。

DD_TRACE_RESOURCE_URI_MAPPING_INCOMING および DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING

この設定はワイルドカード * を含むことのできるパターンの CSV です。たとえば、パターン cities/* を追加すると、URL を分析中にフラグメント cities が見つかる度に、次のフラグメントがある場合 ? に置き換えられます。パターンは深さを問わず適用されるため、次の規則を適用することで、上記の表の /cities/new-york と /nested/cities/new-york の両方が正規化されます。

パターンは特定のフラグメントの一部に適用することもできます。たとえば、path/*-fix は URL /some/path/changing-fix/nested を /some/path/?-fix/nested に正規化します。

DD_TRACE_RESOURCE_URI_MAPPING_INCOMING は受信リクエスト（ウェブフレームワークなど）のみに適用され、DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING は発信リクエスト（curl や guzzle リクエストなど）のみに適用されることに、ご注意ください。

アップグレード

PHP トレーサーをアップグレードするには、最新のリリースをダウンロードし、拡張機能のインストールと同じ手順に従います。

注: OPcache でパラメーターを opcache.file_cache に設定してセカンドレベルキャッシングを使用する場合は、キャッシュフォルダーを削除します。

削除中

PHPトレーサーを削除するには:

1. php-fpm の場合は php-fpm サービスを停止し、それ以外の場合は Apache Web サーバーを停止します。
2. php コンフィギュレーションフォルダーから 98-ddtrace.ini と 99-ddtrace-custom.ini のファイルのリンクを外します。
3. php-fpm の場合は php-fpm サービスを再起動し、それ以外の場合は Apache Web サーバーを再起動します。

注: OPcache でパラメーターを opcache.file_cache に設定してセカンドレベルキャッシングを使用する場合は、キャッシュフォルダーを削除します。

アプリケーションクラッシュのトラブルシューティング

PHP トレーサーが原因でアプリケーションがクラッシュするという異常なイベントが発生した場合、通常はセグメンテーションフォールトが原因で、最善の対応はコアダンプを取得し、Datadog サポートに連絡することです。

コアダンプの取得

PHP アプリケーションのコアダンプを取得することは、特に PHP-FPM では難しい場合があります。コアダンプを取得するのに役立ついくつかのヒントを次に示します。

1. アプリケーションエラーログを調べて、PHP-FPM がコアダンプを生成したかどうかを確認します。
   • (SIGSEGV - core dumped) を検索します。これは、次のようなメッセージはダンプされたことを意味するためです: WARNING: [pool www] child <pid> exited on signal 11 (SIGSEGV - core dumped) after <duration> seconds from start
   • (SIGSEGV) を検索します。これは、次のようなメッセージはコアがダンプされなかったことを意味するためです: WARNING: [pool www] child <pid> exited on signal 11 (SIGSEGV) after <duration> seconds from start
2. cat /proc/sys/kernel/core_pattern を実行して、コアダンプを見つけます。デフォルト値は通常 core です。これは、core という名前のファイルが Web ルートフォルダーに生成されることを意味します。

コアダンプが生成されなかった場合は、次のコンフィギュレーションを確認し、必要に応じて変更します。

1. /proc/sys/kernel/core_pattern にネストされたディレクトリを含むパスが含まれている場合は、完全なディレクトリパスが存在することを確認します。
2. PHP-FPM プールワーカーを実行しているユーザーが root 以外の場合 (一般的なユーザー名は www-data)、そのユーザーにコアダンプディレクトリへの書き込みアクセス許可を付与します。
3. /proc/sys/fs/suid_dumpable の値が 0 ではないことを確認します。PHP-FPM ワーカープールを root として実行しない限り、1 または 2 に設定します。システム管理者にオプションを確認します。
4. PHP-FPM プールコンフィギュレーションセクションに適切な rlimit_core があることを確認します。これは unlimited に設定できます: rlimit_core = unlimited
5. システムに適切な ulimit が設定されていることを確認します。これは unlimited に設定できます: ulimit -c unlimited
6. アプリケーションが Docker コンテナで実行されている場合は、ホストマシンに対して /proc/sys/* への変更を行う必要があります。使用可能なオプションについては、システム管理者に問い合わせてください。可能であれば、テスト環境またはステージング環境で問題を再現してみてください。

その他の参考資料

お役に立つドキュメント、リンクや記事:

Datadog APM と分散型トレーシングを使用した PHP の監視ブログ ソースコードGITHUB サービス、リソース、トレースを調査するDOCUMENTATION 高度な使用方法DOCUMENTATION