- 重要な情報
- はじめに
- 用語集
- ガイド
- エージェント
- インテグレーション
- OpenTelemetry
- 開発者
- API
- CoScreen
- アプリ内
- Service Management
- インフラストラクチャー
- アプリケーションパフォーマンス
- 継続的インテグレーション
- ログ管理
- セキュリティ
- UX モニタリング
- 管理
最新の PHP トレーサーは、バージョン 5.4.x 以降をサポートしています。
Datadog の PHP バージョンとフレームワークのサポート一覧 (レガシーバージョンとメンテナンスバージョンを含む) については、互換性要件ページをご覧ください。
作業を始める前に、Agent のインストールと構成が済んでいることを確認してください。
公式インストーラーをダウンロードします。
curl -LO https://github.com/DataDog/dd-trace-php/releases/latest/download/datadog-setup.php
Alpine Linux をお使いの場合は、インストーラーを実行する前に libgcc_s をインストールする必要があります。
apk add libgcc
インストーラーを実行します。
# フルインストール: APM + ASM + プロファイリング (ベータ版)
php datadog-setup.php --php-bin=all --enable-appsec --enable-profiling
# APM のみ
php datadog-setup.php --php-bin=all
# APM + ASM
php datadog-setup.php --php-bin=all --enable-appsec
# APM + プロファイリング (ベータ版)
php datadog-setup.php --php-bin=all --enable-profiling
このコマンドは、ホストまたはコンテナ内に存在する全ての PHP バイナリに拡張機能をインストールします。もし --php-bin が省略された場合、インストーラーはインタラクティブモードで実行され、インストールするバイナリを選択するようユーザーに要求します。このとき、--php-bin の値には、特定のバイナリへのパスを指定することができます。
PHP (PHP-FPM または Apache SAPI) を再起動し、アプリケーションのトレース可能なエンドポイントにアクセスします。トレースについては、APM サービス一覧を参照してください。
--enable-appsec を指定しない場合、AppSec 拡張機能は起動時にすぐにロードされ、デフォルトでは有効になっていません。これはすぐにショートサーキットを起こし、ほとんど無視できる程度のパフォーマンスオーバーヘッドを引き起こします。
phpinfo() ページを作成し、`ddtrace` までスクロールダウンしてください。診断に失敗したチェックはこのセクションに表示され、問題を特定するのに役立ちます。/path/to/php-zts --ini を実行して Datadog の .ini ファイルがある場所を探し、ファイル名から -zts サフィックスを追加してください。例えば、extension=ddtrace-20210902.so から extension=ddtrace-20210902-zts.so になります。allow httpd_t httpd_tmpfs_t:file { execute execute_no_trans };
トレースはデフォルトで自動的に有効になります。拡張機能がインストールされると、ddtrace はアプリケーションをトレースし、トレースを Agent に送信します。
Datadog はそのままの状態ですべてのウェブフレームワークをサポートします。自動インスツルメンテーションは、特定の関数やメソッドをトレースするために、PHPのランタイムを変更してこれらをラップすることで動作します。PHP トレーサーは、複数のライブラリの自動インスツルメンテーションをサポートします。
自動インスツルメンテーションは以下を取得します。
必要に応じて、統合サービスタグ付けの設定など、アプリケーションパフォーマンスのテレメトリーデータを送信するためのトレースライブラリーを構成します。詳しくは、ライブラリの構成を参照してください。
CLI スクリプトのインスツルメンテーションを行うには、追加の手順が必要です。詳細は PHP CLI スクリプトのトレースを参照ください。
PHP トレーサーをアップグレードするには、最新のリリースをダウンロードし、拡張機能のインストールと同じ手順に従います。
インストールが完了したら、PHP (PHP-FPM または Apache SAPI) を再起動します。
注: OPcache でパラメーターを opcache.file_cache に設定してセカンドレベルキャッシングを使用する場合は、キャッシュフォルダーを削除します。
PHPトレーサーを削除するには:
98-ddtrace.ini と 99-ddtrace-custom.ini のファイルのリンクを外します。注: OPcache でパラメーターを opcache.file_cache に設定してセカンドレベルキャッシングを使用する場合は、キャッシュフォルダーを削除します。
PHP トレーサーが原因でアプリケーションがクラッシュするという異常なイベントが発生した場合、通常はセグメンテーションフォールトが原因で、最善の対応はコアダンプや Valgrind トレースを取得し、Datadog サポートに連絡することです。
コアダンプを読み取るためには、PHP を実行するシステムに PHP バイナリのデバッグシンボルがインストールされていなければなりません。
PHP や PHP-FPM にデバッグシンボルがインストールされているかどうかを確認するには、gdb を使用してください。
gdb をインストールします。
apt|yum install -y gdb
対象のバイナリで gdb を実行します。たとえば、PHP-FPM の場合は次のようになります。
gdb php-fpm
gdb で以下のような行が出力された場合、デバッグシンボルはすでにインストールされています。
...
Reading symbols from php-fpm...Reading symbols from /usr/lib/debug/path/to/some/file.debug...done.
...
gdb で以下のような行が出力された場合は、デバッグシンボルをインストールする必要があります。
...
Reading symbols from php-fpm...(no debugging symbols found)...done.
...
debuginfo-install プログラムを含む yum-utils パッケージをインストールします。
yum install -y yum-utils
PHP バイナリのパッケージ名を確認します。PHP のインストール方法により異なる場合があります。
yum list installed | grep php
デバッグシンボルをインストールします。php-fpm パッケージの場合は次のようになります。
debuginfo-install -y php-fpm
注: PHP バイナリを提供するリポジトリがデフォルトで有効になっていない場合は、debuginfo-install コマンドを実行する際に有効にすることができます。たとえば、次のようになります。
debuginfo-install --enablerepo=remi-php74 -y php-fpm
PHP を Sury Debian DPA からインストールした場合は、DPA からすでにデバッグシンボルを利用できます。例えば、PHP-FPM 7.2 の場合は次のようになります。
apt update
apt install -y php7.2-fpm-dbgsym
Debian プロジェクトでは、wiki ページにデバッグシンボルのインストール手順を掲載しています。
/etc/apt/sources.list ファイルを編集します。
# ... 既存のパッケージをすべてここに残す
# `deb` deb http://deb.debian.org/debian-debug/ $RELEASE-debug main を追加
# buster の場合の例
deb http://deb.debian.org/debian-debug/ buster-debug main
apt を更新します。
apt update
デバッグシンボルには、まず標準パッケージ名をお試しください。たとえば、パッケージ名が php7.2-fpm の場合は次のようになります。
apt install -y php7.2-fpm-dbgsym
# 上記が機能しなかった場合
apt install -y php7.2-fpm-dbg
デバッグシンボルが見つからない場合は、ユーティリティーツールの find-dbgsym-packages バイナリをインストールします。
apt install -y debian-goodies
バイナリへのフルパスまたは実行中のプロセスのプロセス ID から、デバッグシンボルの検出を試みます。
find-dbgsym-packages /usr/sbin/php-fpm7.2
見つかった場合は、見つかった場合は、結果として得られたパッケージ名をインストールします。
apt install -y php7.2-fpm-{package-name-returned-by-find-dbgsym-packages}
ppa:ondrej/php から PHP をインストールした場合 PHP を ppa:ondrej/php からインストールした場合は、main/debug コンポーネントを追加して apt ソースファイル /etc/apt/sources.list.d/ondrej-*.list を編集します。
修正前:
deb http://ppa.launchpad.net/ondrej/php/ubuntu <version> main
修正後:
deb http://ppa.launchpad.net/ondrej/php/ubuntu <version> main main/debug
デバッグシンボルを更新およびインストールします。たとえば、PHP-FPM 7.2 の場合は次のようになります。
apt update
apt install -y php7.2-fpm-dbgsym
PHP バイナリのパッケージ名を確認します。PHP のインストール方法により異なる場合があります。
apt list --installed | grep php
注: php-fpm は、実際のパッケージを参照するメタパッケージである場合もあります (例: PHP-FPM 7.2 の場合は php7.2-fpm)。この場合、パッケージ名は後者のようになります。
デバッグシンボルには、まず標準パッケージ名をお試しください。たとえば、パッケージ名が php7.2-fpm の場合は次のようになります。
apt install -y php7.2-fpm-dbgsym
# 上記が機能しなかった場合
apt install -y php7.2-fpm-dbg
-dbg および -dbgsym パッケージが見つからない場合は、ddebs リポジトリを有効にしてください。ddebs からデバッグシンボルをインストールする方法についての詳細は、Ubuntu のドキュメントを参照してください。
たとえば、Ubuntu 18.04 以降の場合、ddebs リポジトリを有効にします。
echo "deb http://ddebs.ubuntu.com $(lsb_release -cs) main restricted universe multiverse" | tee -a /etc/apt/sources.list.d/ddebs.list
echo "deb http://ddebs.ubuntu.com $(lsb_release -cs)-updates main restricted universe multiverse" | tee -a /etc/apt/sources.list.d/ddebs.list
署名キーをインポートします (署名キーが正しいことを確認してください)。
apt install ubuntu-dbgsym-keyring
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys <SIGNING KEY FROM UBUNTU DOCUMENTATION>
apt update
デバッグシンボルの正規のパッケージ名を追加してください。例えば、パッケージ名が php7.2-fpm の場合は次のように試してください。
apt install -y php7.2-fpm-dbgsym
# 上記が機能しなかった場合
apt install -y php7.2-fpm-dbg
デバッグシンボルが見つからない場合は、ユーティリティツール find-dbgsym-packages を使用してください。そして、バイナリをインストールします。
apt install -y debian-goodies
バイナリへのフルパスまたは実行中のプロセスのプロセス ID から、デバッグシンボルの検出を試みます。
find-dbgsym-packages /usr/sbin/php-fpm7.2
見つかった場合は、見つかった場合は、結果として得られたパッケージ名をインストールします。
apt install -y php7.2-fpm-{package-name-returned-by-find-dbgsym-packages}
PHP アプリケーションのコアダンプを取得することは、特に 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 startcat /proc/sys/kernel/core_pattern を実行して、コアダンプを見つけます。デフォルト値は通常 core です。これは、core という名前のファイルが Web ルートフォルダーに生成されることを意味します。コアダンプが生成されなかった場合は、次のコンフィギュレーションを確認し、必要に応じて変更します。
/proc/sys/kernel/core_pattern にネストされたディレクトリを含むパスが含まれている場合は、完全なディレクトリパスが存在することを確認します。root 以外の場合 (一般的なユーザー名は www-data)、そのユーザーにコアダンプディレクトリへの書き込みアクセス許可を付与します。/proc/sys/fs/suid_dumpable の値が 0 ではないことを確認します。PHP-FPM ワーカープールを root として実行しない限り、1 または 2 に設定します。システム管理者にオプションを確認します。rlimit_core があることを確認します。これは unlimited に設定できます: rlimit_core = unlimitedulimit が設定されていることを確認します。これは unlimited に設定できます: ulimit -c unlimited/proc/sys/* への変更を行う必要があります。使用可能なオプションについては、システム管理者に問い合わせてください。可能であれば、テスト環境またはステージング環境で問題を再現してみてください。Docker コンテナでコアダンプを取得する際には、以下の情報を参考にしてください。
ulimit 値は以下の例に示すように最大値に設定する必要があります。docker run コマンドを使用する場合は、--privileged と --ulimit core=99999999999 の引数を追加しますdocker compose を使用する場合は、docker-compose.yml ファイルに以下を追加します。privileged: true
ulimits:
core: 99999999999
ulimit -c unlimited
echo '/tmp/core' > /proc/sys/kernel/core_pattern
echo 1 > /proc/sys/fs/suid_dumpable
クラッシュの詳細を把握するために、Valgrind でアプリケーションを実行します。コアダンプとは異なり、このアプローチは常に非特権のコンテナで動作します。
お使いのパッケージマネージャーで Valgrind をインストールします。アプリケーションを Valgrind で実行し、いくつかのリクエストを生成します。
CLI アプリケーションの場合は、次を実行します。
USE_ZEND_ALLOC=0 valgrind -- php path/to/script.phpphp-fpm run:USE_ZEND_ALLOC=0 valgrind --trace-children=yes -- php-fpm -F --fpm-config <CONFIG_FILE_PATH> <MORE_OPTIONS>(. /etc/apache2/envvars; USE_ZEND_ALLOC=0 valgrind --trace-children=yes -- apache2 -X)`結果として得られる Valgrind のトレースは、デフォルトでは標準エラーに出力されますが、公式ドキュメントに従って別のターゲットに出力することもできます。想定される出力は、PHP-FPM プロセスの場合、以下の例のようになります。
==322== Conditional jump or move depends on uninitialised value(s)
==322== at 0x41EE82: zend_string_equal_val (zend_string.c:403)
==322== ...
==322== ...
==322==
==322== Process terminating with default action of signal 11 (SIGSEGV): dumping core
==322== at 0x73C8657: kill (syscall-template.S:81)
==322== by 0x1145D0F2: zif_posix_kill (posix.c:468)
==322== by 0x478BFE: ZEND_DO_ICALL_SPEC_RETVAL_UNUSED_HANDLER (zend_vm_execute.h:1269)
==322== by 0x478BFE: execute_ex (zend_vm_execute.h:53869)
==322== by 0x47D9B0: zend_execute (zend_vm_execute.h:57989)
==322== by 0x3F6782: zend_execute_scripts (zend.c:1679)
==322== by 0x394F0F: php_execute_script (main.c:2658)
==322== by 0x1FFE18: main (fpm_main.c:1939)
==322==
==322== Process terminating with default action of signal 11 (SIGSEGV)
==322== ...
==322== ...
==322==
==322== HEAP SUMMARY:
==322== in use at exit: 3,411,619 bytes in 22,428 blocks
==322== total heap usage: 65,090 allocs, 42,662 frees, 23,123,409 bytes allocated
==322==
==322== LEAK SUMMARY:
==322== definitely lost: 216 bytes in 3 blocks
==322== indirectly lost: 951 bytes in 32 blocks
==322== possibly lost: 2,001,304 bytes in 16,840 blocks
==322== still reachable: 1,409,148 bytes in 5,553 blocks
==322== of which reachable via heuristic:
==322== stdstring : 384 bytes in 6 blocks
==322== suppressed: 0 bytes in 0 blocks
==322== Rerun with --leak-check=full to see details of leaked memory
==322==
==322== Use --track-origins=yes to see where uninitialised values come from
==322== For lists of detected and suppressed errors, rerun with: -s
==322== ERROR SUMMARY: 18868 errors from 102 contexts (suppressed: 0 from 0)
外的要因によって問題が引き起こされる場合もあるため、このような場合に strace は貴重な情報源となります。
strace を介して実行されるアプリケーションは、ネイティブで実行される場合に比べて極めて遅くなります。この方法は、本番ではない環境で使用することをお勧めします。お使いのパッケージマネージャーで strace をインストールしてください。Datadog サポートに送信する strace を生成する際には、-f オプションを使用して子プロセスを追跡します。
For a CLI application, run:
strace -f php path/to/script.phpphp-fpm の場合は、次を実行します。
strace -f php-fpm -F --fpm-config <CONFIG_FILE_PATH> <MORE_OPTIONS>Apache の場合は、次を実行します。
(. /etc/apache2/envvars; strace -f apache2 -X)
