For descriptions of terminology used in APM, take a look at the official documentation.
For details about open-source contributions to the PHP tracer, refer to the contributing guide.
The PHP APM tracer sends trace data through the Datadog Agent.
Make sure the Agent has APM enabled.
Install the PHP extension using one of the precompiled packages for supported distributions.
Once downloaded, install the package with one of the commands below.
# using RPM package (RHEL/Centos 6+, Fedora 20+) $ rpm -ivh datadog-php-tracer.rpm # using DEB package (Debian Jessie+ , Ubuntu 14.04+) $ dpkg -i datadog-php-tracer.deb # using APK package (Alpine) $ apk add datadog-php-tracer.apk --allow-untrusted
Restart PHP (PHP-FPM or the Apache SAPI) and then visit a tracing-enabled endpoint of your application. View the APM UI to see the traces.
Note: It might take a few minutes before traces appear in the UI.
If you can’t find your distribution, you can manually install the PHP extension.
Tracing is automatically instrumented by default. Once the extension is installed, ddtrace traces your application and sends traces to the Agent.
Even if Datadog does not officially support your web framework, you may not need any manual instrumentation. Datadog records generic web requests and creates generic traces for them. If you use one of the supported frameworks, however, Datadog sets more relevant metadata, which makes it easier to navigate through your services.
Automatic instrumentation works by modifying PHP’s runtime to wrap certain functions and methods in order to trace them. The PHP tracer supports automatic instrumentation for several libraries.
Automatic instrumentation captures:
Configure your application level tracers to submit traces to a custom Agent hostname:
The PHP tracer automatically looks for and initializes with the ENV variables
See tracer configuration for more information on how to set these variables.
PHP APM supports the following PHP versions:
PHP APM supports the following SAPI’s:
If the web framework that you use is not listed below, you can still see traces for your web requests in the UI. However, some metadata and spans that are very specific to that particular web framework may not display.
|Laravel||4.2, 5.x||Fully Supported|
|Symfony||2.x, 3.3, 3.4, 4.x||Fully Supported|
|Zend Framework||1.12||Fully Supported|
|CodeIgniter||2, 3||Coming Soon|
|Phalcon||1.3, 3.4||Coming Soon|
Don’t see your desired frameworks? Datadog is continually adding additional support. Check with the Datadog team for help.
Tracing from the CLI SAPI is disabled by default. To enable tracing of PHP CLI scripts, set
|Laravel Artisan||5.x||Fully Supported|
|Symfony Console||Coming Soon|
Don’t see your desired CLI library? Datadog is continually adding additional support. Check with the Datadog team for help.
|Amazon RDS (using PDO or MySQLi)||(Any Supported PHP)||Fully Supported|
|CakePHP Console||2.x||Fully Supported|
|Eloquent||Laravel supported versions||Fully Supported|
|Memcached||(Any Supported PHP)||Fully Supported|
|MySQLi||(Any Supported PHP)||Fully Supported|
|PDO (MySQL, PostgreSQL, MariaDB)||(Any Supported PHP)||Fully Supported|
|AWS Couchbase||AWS PHP SDK 3||Coming Soon|
|AWS DynamoDB||AWS PHP SDK 3||Coming Soon|
|AWS ElastiCache||AWS PHP SDK 3||Coming Soon|
|Doctrine ORM||2||Coming Soon|
|ODBC||(Any Supported PHP)||Coming Soon|
Don’t see your desired datastores? Datadog is continually adding additional support. Check with the Datadog team for help.
|Curl||(Any Supported PHP)||Fully Supported|
Don’t see your desired libraries? Datadog is continually adding additional support. Check with the Datadog team for help.
The PHP tracer can be configured using environment variables.
Note: If you use code auto-instrumentation (the recommended approach) be aware that the instrumenting code is executed before any user code. As a result, the environment variables below must be set at the server level and be available to the PHP runtime before any user code is executed. For example,
.env files would not work.
SetEnv from the server config, virtual host, directory, or .htaccess file.
SetEnv DD_TRACE_DEBUG true
fastcgi_param from the
fastcgi_param DD_TRACE_DEBUG true;
Set in the command line to start the server.
DD_TRACE_DEBUG=true php -S localhost:8888
|The Agent host name|
|Whether spans are automatically finished when the tracer is flushed|
|Enable tracing of PHP scripts from the CLI|
|Whether to enable distributed tracing|
|CSV list of disabled extensions; e.g., |
|The sampling rate for the traces. Between |
|``||The default app name|
|The Agent port number|
|Maximum time the Agent is allowed to take (in milliseconds)|
|Maximum time the allowed for Agent connection setup (in milliseconds)|
|Flag to enable trace analytics for relevant spans in web integrations|
|Enable debug mode for the tracer|
|Enable the tracer globally|
|``||Tags to be set on all spans: e.g.: |
|Flag to enable trace analytics for relevant spans in a specific integration|
Additional helpful documentation, links, and articles: