サポート対象のライブラリと言語の一覧については、互換性要件ページをご覧ください。
Datadog アプリ内のクイックスタート手順に従って、最高のエクスペリエンスを実現します。例:
service
、env
、version
タグを動的に設定します。APM で使用される用語の説明は、公式ドキュメントを参照してください。
PHP トレーサーのオープンソースに対する貢献に関しては、コントリビューションガイドを参照してください。
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 トレーサーは、複数のライブラリの自動インスツルメンテーションをサポートします。
自動インスツルメンテーションは以下を取得します。
注: アプリケーションが Composer や spl_autoload_register()
で登録されたオートローダーを使用しない場合、環境変数を DD_TRACE_NO_AUTOLOADER=true
と設定し、自動インスツルメンテーションを有効にします。
アプリケーションレベルのトレーサーを設定し、以下のカスタム Agent ホスト名にトレースを送信します。
PHP トレーサーが自動的に検索し環境変数の DD_AGENT_HOST
や DD_TRACE_AGENT_PORT
で初期化します。
変数の設定方法については、トレーサーコンフィギュレーションを参照してください。
PHP トレーサーは環境変数で設定できます。
注: コードの自動インスツルメンテーションを使用する場合(推奨されるアプローチ)、インスツルメンテーションコードはどのユーザーコードよりも先に実行されることに注意してください。そのため、以下の環境変数はサーバーレベルで設定し、ユーザーコードが実行される前に PHP ランタイムで使用できるようにします。たとえば、putenv()
や .env
ファイルは機能しません。
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 の場合、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 コンフィギュレーションを参照してください。
コマンドラインで設定しサーバーを起動します。
DD_TRACE_DEBUG=true php -S localhost:8888
環境変数 | デフォルト | 注 |
---|---|---|
DD_AGENT_HOST | localhost | Agent のホスト名 |
DD_AUTOFINISH_SPANS | false | トレーサーがフラッシュされた時点でスパンを自動終了させるかどうか |
DD_DISTRIBUTED_TRACING | true | 分散型トレーシングの有効にするかどうか |
DD_ENV | null | アプリケーションの環境 (例: prod 、pre-prod 、stage ) を設定します。バージョン 0.47.0 で追加されました。 |
DD_PRIORITY_SAMPLING | true | 優先度付きサンプリングを有効にするかどうか |
DD_SERVICE | null | デフォルトのアプリ名。バージョン 0.47.0 以降では、DD_SERVICE_NAME になります。 |
DD_SERVICE_MAPPING | null | APM インテグレーションのデフォルトの名前を変更します。一度に 1 つ以上のインテグレーションの名前を変更できます。例: DD_SERVICE_MAPPING=pdo:payments-db,mysqli:orders-db (インテグレーション名を参照してください) |
DD_TRACE_AGENT_ATTEMPT_RETRY_TIME_MSEC | 5000 | IPC ベースの構成可能なサーキットブレーカーの再試行時間(ミリ秒) |
DD_TRACE_AGENT_CONNECT_TIMEOUT | 100 | Agent の接続設定に使える最大時間(ミリ秒) |
DD_TRACE_AGENT_CONNECT_TIMEOUT | 100 | Agent の接続タイムアウト(ミリ秒) |
DD_TRACE_AGENT_MAX_CONSECUTIVE_FAILURES | 3 | IPC ベースの構成可能なサーキットブレーカーの連続エラー最大数 |
DD_TRACE_AGENT_PORT | 8126 | Agent ポート番号 |
DD_TRACE_AGENT_TIMEOUT | 500 | Agent リクエストの転送タイムアウト(ミリ秒) |
DD_TRACE_AGENT_URL | null | Agent の URL。DD_AGENT_HOST および DD_TRACE_AGENT_PORT よりも優先されます。例: https://localhost:8126 。バージョン 0.47.1 で追加されました。 |
DD_TRACE_ANALYTICS_ENABLED | false | Web インテグレーションで関連するスパンに対するApp Analytics を有効にするためのフラグ |
DD_TRACE_AUTO_FLUSH_ENABLED | false | すべてのスパンが終了されたタイミングでトレーサーを自動でフラッシュします。長時間実行されるプロセスをトレースするために、DD_TRACE_GENERATE_ROOT_SPAN=0 と併せて true に設定されます。 |
DD_TRACE_CLI_ENABLED | false | CLI から PHP スクリプトのトレースを有効にする |
DD_TRACE_DEBUG | false | トレーサーの[デバッグモード](#カスタム URL からリソースへのマッピング)を有効にする |
DD_TRACE_ENABLED | true | トレーサーをグローバルに有効にする |
DD_TRACE_GENERATE_ROOT_SPAN | true | トップレベルのスパンを自動生成します。長時間実行されるプロセスをトレースするために、DD_TRACE_AUTO_FLUSH_ENABLED=1 と併せて false に設定されます |
DD_TAGS | null | すべてのスパンに設定されるタグ。例、key1:value1,key2:value2 。バージョン 0.47.0 で追加されました。 |
DD_TRACE_HTTP_CLIENT_SPLIT_BY_DOMAIN | false | HTTP リクエストのサービス名を host-<ホスト名> に設定します。例: https://datadoghq.com に対する curl_exec() コールのサービス名は、デフォルトのサービス名 curl ではなく host-datadoghq.com となります。 |
DD_TRACE_<INTEGRATION>_ANALYTICS_ENABLED | false | 特定のインテグレーションで関連するスパンの App Analytics を有効にするためのフラグ (インテグレーション名を参照してください)。バージョン < 0.47.1 の場合、このパラメーターは DD_<INTEGRATION>_ANALYTICS_ENABLED です。 |
DD_TRACE_<INTEGRATION>_ANALYTICS_SAMPLE_RATE | 1.0 | 特定のインテグレーションで関連するスパンの App Analytics サンプルレートを設定するためのフラグ (インテグレーション名を参照してください)。バージョン < 0.47.1 の場合、このパラメーターは DD_<INTEGRATION>_ANALYTICS_SAMPLE_RATE です。 |
DD_TRACE_<INTEGRATION>_ENABLED | true | インテグレーションを有効または無効にします。すべてのインテグレーションはデフォルトで有効になっています (インテグレーション名を参照してください)。バージョン < 0.47.1 の場合、このパラメーターは無効にするインテグレーションの CSV リストを取得する DD_INTEGRATIONS_DISABLED です (例: curl,mysqli )。 |
DD_TRACE_MEASURE_COMPILE_TIME | true | リクエストのコンパイル時間 (ミリ秒) をトップレベルのスパン上に記録します。 |
DD_TRACE_NO_AUTOLOADER | false | オートローダーを使用しないアプリケーションには、true に設定して自動インスツルメンテーションを有効にします。 |
DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX | null | ID に対応するパスフラグメントを特定する正規表現のCSV(リソース名を正規化された URI にマッピング を参照してください)。 |
DD_TRACE_RESOURCE_URI_MAPPING_INCOMING | null | 受信リクエストのリソース名を正規化するための URI マッピングの CSV(リソース名を正規化された URI にマッピング を参照してください)。 |
DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING | null | 発信リクエストのリソース名を正規化するための URI マッピングの CSV(リソース名を正規化された URI にマッピング を参照してください)。 |
DD_TRACE_SAMPLE_RATE | 1.0 | トレースのサンプリングレート (デフォルトは 0.0 および 1.0 )。 バージョン < 0.36.0 の場合、このパラメーターは DD_SAMPLING_RATE となります。 |
DD_TRACE_SAMPLING_RULES | null | JSON でエンコードされた文字列で、サンプリングレートを構成します。例: サンプルレートを 20% に設定する場合は [{"sample_rate": 0.2}] となります。‘a’ ではじまる、スパン名が ‘b’ のサービスのサンプルレートを 10% に、その他のサービスのサンプルレートを 20% に設定する場合は [{"service": "a.*", "name": "b", "sample_rate": 0.1}, {"sample_rate": 0.2}] のようになります (インテグレーション名 を参照してください) 。 |
DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED | true | リソース名として URL を有効にします。([リソース名を正規化された URI にマッピング](#リソース名を正規化された URI にマッピング)を参照してください) 。 |
DD_VERSION | null | トレースとログで、アプリケーションのバージョン(例: 1.2.3 , 6c44da20 , 2020.02.13 )を設定します。バージョン 0.47.0 で追加されました。 |
以下の表は、各インテグレーションに紐付くデフォルトのサービス名をまとめたものです。サービス名は DD_SERVICE_MAPPING
に変更してください。
インテグレーション固有のコンフィギュレーションを設定する場合は、DD_TRACE_<INTEGRATION>_ANALYTICS_ENABLED
の形式で名前をつけてください。例: Laravel の場合、DD_TRACE_LARAVEL_ANALYTICS_ENABLED
インテグレーション | サービス名 |
---|---|
CakePHP | cakephp |
CodeIgniter | codeigniter |
cURL | curl |
ElasticSearch | elasticsearch |
Eloquent | eloquent |
Guzzle | guzzle |
Laravel | laravel |
Lumen | lumen |
Memcached | memcached |
Mongo | mongo |
Mysqli | mysqli |
PDO | pdo |
PhpRedis | phpredis |
Predis | predis |
Slim | slim |
Symfony | symfony |
WordPress | wordpress |
Yii | yii |
ZendFramework | zendframework |
DD_TRACE_RESOURCE_URI_MAPPING
は非推奨となります。しばらくはまだ機能しますが、レガシーサポートが外された際の問題を回避するために、ここにある新しい設定を使用することを強くお勧めします。以下の設定: DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX
、DD_TRACE_RESOURCE_URI_MAPPING_INCOMING
、DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING
は新しいリソース正規化アプローチをオプトインし、DD_TRACE_RESOURCE_URI_MAPPING
の値はすべて無視されることに注意してください。
HTTP サーバーとクライアントインテグレーションでは、URL はクエリ文字列が URL から削除された状態で、トレースリソース名を作成するために <HTTP_REQUEST_METHOD> <NORMALIZED_URL>
の形式で使用されます。URL を正規化し 1 つのリソースの下に一般的なエンドポイントをグループ化することで、自動インスツルメンテーションされないカスタムフレームワークにおける可視性を向上することができます。
HTTP リクエスト | リソース名 |
---|---|
GET request to /foo?a=1&b=2 | GET /foo |
POST request to /bar?foo=bar | POST /bar |
数値 ID、UUID (ダッシュの有無不問)、32〜512 ビットの 16 進数ハッシュは、自動的に ?
に置換されます。
URL (GET リクエスト) | リソース名 |
---|---|
/user/123/show | GET /user/?/show |
/widget/b7a992e0-3300-4030-8617-84553b11c993 | GET /widget/? |
/api/v2/b7a992e033004030861784553b11c993/123 | GET /api/v2/?/? |
/book/0dbf3596 | GET /book/? |
DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED=false
を使用してこの機能をオフにすることも可能です。
適用された自動正規化ではカバーされないケースがいくつかあります。
URL (GET リクエスト) | 考えられるリソース名 |
---|---|
/using/prefix/id123/for/id | GET /using/prefix/?/for/id |
/articles/slug-of-title | GET /articles/? |
/cities/new-york/rivers | GET /cities/?/rivers |
/nested/cities/new-york/rivers | GET /nested/cities/?/rivers |
自動正規化ではカバーされないシナリオには、次の 2 つのクラスがあります。
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トレーサーを削除するには:
98-ddtrace.ini
と 99-ddtrace-custom.ini
のファイルのリンクを外します。注: OPcache でパラメーターを opcache.file_cache
に設定してセカンドレベルキャッシングを使用する場合は、キャッシュフォルダーを削除します。
このページ