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

互換性要件

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

インストールと利用開始

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

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

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

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

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

Datadog Agent の設定

PHP APM トレーサーは、Datadog Agent を使用してトレースデータを送信します。

Datadog Agent をインストール、構成します。Docker アプリケーションのトレースまたは Kubernetes アプリケーションのトレースに関する追加ドキュメントを確認します。

Agent バージョン 7.18.0 以降の場合、APM はすべての環境でデフォルトで有効になっており、これ以上の操作は必要ありません。 これより古いバージョンの Agent を実行している場合は、Agent で **APM が有効**になっていることを確認してください。

拡張機能をインストール

対応するディストリビューション用にプリコンパイルされたパッケージの 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 と設定し、自動インスツルメンテーションを有効にします。

Agent ホスト名の変更

アプリケーションレベルのトレーサーを設定し、以下のカスタム Agent ホスト名にトレースを送信します。

PHP トレーサーが自動的に検索し環境変数の DD_AGENT_HOST や DD_TRACE_AGENT_PORT で初期化します。

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

コンフィギュレーション

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 に設定してセカンドレベルキャッシングを使用する場合は、キャッシュフォルダーを削除します。

その他の参考資料

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

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