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+ on supported PHP versions) dpkg -i datadog-php-tracer.deb # using APK package (Alpine) apk add datadog-php-tracer.apk --allow-untrusted
The extension will be installed for the default PHP version. To install the extension for a specific PHP version, use the
DD_TRACE_PHP_BIN environment variable to set the location of the target PHP binary before installing.
export DD_TRACE_PHP_BIN=$(which php-fpm7)
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 traces still do not appear after a few minutes, run the dd-doctor.php diagnostic script from the host machine to help identify any issues.
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:
Note: If your application does not use Composer nor an autoloader registered with
spl_autoload_register(), set the environment variable,
DD_TRACE_NO_AUTOLOADER=true, to enable automatic instrumentation.
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||3.3, 3.4, 4.x||Fully Supported|
|Zend Framework||1.12||Fully Supported|
|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
|CakePHP Console||2.x||Fully Supported|
|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|
|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|
|Whether to enable distributed tracing|
|CSV list of disabled extensions; e.g., |
|Whether to enable priority sampling|
|The sampling rate for the traces. Between |
|The default app name|
|IPC-based configurable circuit breaker retry time (in milliseconds)|
|Maximum time the allowed for Agent connection setup (in milliseconds)|
|The Agent connection timeout (in milliseconds)|
|IPC-based configurable circuit breaker max consecutive failures|
|The Agent port number|
|The Agent request transfer timeout (in milliseconds)|
|Flag to enable app analytics for relevant spans in web integrations|
|Enable tracing of PHP scripts from the CLI|
|Enable debug mode for the tracer|
|Enable the tracer globally|
|Tags to be set on all spans: e.g.: |
|Set to |
|Enable hostname reporting on the root span|
|CSV of URL-to-resource-name mapping rules; e.g., |
|Enable URL’s as resource names; see “Map Resource Names To Normalized URI”|
|Flag to enable app analytics for relevant spans in a specific integration|
DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED=true, the URL is used to form the trace resource name in the format
<HTTP_REQUEST_METHOD> <NORMALIZED_URL>, with the query string removed from the URL. This allows better visibility in any custom framework that is not automatically instrumented by normalizing the URLs and grouping together generic endpoints under one resource.
|HTTP Request||Resource Name|
|GET request to |
|POST request to |
Numeric IDs, UUIDs (with and without dashes), and 32-to-512-bit hexadecimal hashes are automatically replaced with a
|URL (GET request)||Resource Name|
When URL resource names are enabled, custom URL mapping is configured via
DD_TRACE_RESOURCE_URI_MAPPING which accepts a CSV list of mapping rules. The wildcards
$* are supported, so
DD_TRACE_RESOURCE_URI_MAPPING=/foo/*,/bar/$*/baz. In this context,
* is a greedy match with a replacement character
$* performs a greedy match without replacement
Rules are applied in the same order as they appear in
DD_TRACE_RESOURCE_URI_MAPPING. Less greedy rules should appear in the list before more greedy rules, e.g.
* wildcard is replaced with
|Mapping Rule||URL (GET request)||Resource Name|
$* wildcard matches without replacement.
|Mapping Rule||URL (GET request)||Resource Name|