New announcements for Serverless, Network, RUM, and more from Dash!

Tracing PHP Applications

Installation and Getting Started

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.

Setup the Datadog Agent

The PHP APM tracer sends trace data through the Datadog Agent.

Install and configure the Datadog Agent. See the additional documentation for tracing Docker applications or Kubernetes applications.

Make sure the Agent has APM enabled.

Install the extension

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.

Automatic Instrumentation

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:

  • Method execution time
  • Relevant trace data, such as URL and status response codes for web requests or SQL queries for database access
  • Unhandled exceptions, including stacktraces if available
  • A total count of traces (e.g., web requests) flowing through the system

Change Agent Hostname

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 DD_AGENT_HOST and DD_TRACE_AGENT_PORT.

See tracer configuration for more information on how to set these variables.

Compatibility

PHP APM supports the following PHP versions:

VersionSupport type
7.3.xFully Supported
7.2.xFully Supported
7.1.xFully Supported
7.0.xFully Supported
5.6.xFully Supported
5.4.xFully Supported

PHP APM supports the following SAPI’s:

SAPISupport type
apache2handlerFully Supported
cliFully Supported
fpmFully Supported

Integrations

Web Framework Compatibility

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.

ModuleVersionsSupport Type
CakePHP2.xFully Supported
Laravel4.2, 5.xFully Supported
Lumen5.2+Fully Supported
Slim3.xFully Supported
Symfony2.x, 3.3, 3.4, 4.xFully Supported
Zend Framework1.12Fully Supported
CodeIgniter2, 3Coming Soon
DrupalComing Soon
Magento2Coming Soon
Phalcon1.3, 3.4Coming Soon
WordpressComing Soon
Yii1.1Coming Soon

Don’t see your desired frameworks? Datadog is continually adding additional support. Check with the Datadog team for help.

CLI Library Compatibility

Tracing from the CLI SAPI is disabled by default. To enable tracing of PHP CLI scripts, set DD_TRACE_CLI_ENABLED=true.

ModuleVersionsSupport Type
Laravel Artisan5.xFully Supported
Symfony ConsoleComing Soon

Don’t see your desired CLI library? Datadog is continually adding additional support. Check with the Datadog team for help.

Datastore Compatibility

ModuleVersionsSupport Type
Amazon RDS (using PDO or MySQLi)(Any Supported PHP)Fully Supported
CakePHP Console2.xFully Supported
Elasticsearch1.xFully Supported
EloquentLaravel supported versionsFully Supported
Memcached(Any Supported PHP)Fully Supported
MongoDB1.4.xFully Supported
MySQLi(Any Supported PHP)Fully Supported
PDO (MySQL, PostgreSQL, MariaDB)(Any Supported PHP)Fully Supported
Predis1.1Fully Supported
AWS CouchbaseAWS PHP SDK 3Coming Soon
AWS DynamoDBAWS PHP SDK 3Coming Soon
AWS ElastiCacheAWS PHP SDK 3Coming Soon
Doctrine ORM2Coming Soon
ODBC(Any Supported PHP)Coming Soon
PHPredis4Coming Soon
Solarium4.2Coming Soon

Don’t see your desired datastores? Datadog is continually adding additional support. Check with the Datadog team for help.

Library Compatibility

ModuleVersionsSupport Type
Curl(Any Supported PHP)Fully Supported
Guzzle5.xFully Supported
Guzzle6.xFully Supported
BeanstalkdComing Soon
ReactPHPComing Soon

Don’t see your desired libraries? Datadog is continually adding additional support. Check with the Datadog team for help.

Configuration

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, putenv() and .env files would not work.

Apache

Set using SetEnv from the server config, virtual host, directory, or .htaccess file.

SetEnv DD_TRACE_DEBUG true

NGINX

Set using fastcgi_param from the http, server, or location contexts.

fastcgi_param DD_TRACE_DEBUG true;

PHP CLI server

Set in the command line to start the server.

DD_TRACE_DEBUG=true php -S localhost:8888

Environment Variable Configuration

Env variableDefaultNote
DD_AGENT_HOSTlocalhostThe Agent host name
DD_AUTOFINISH_SPANSfalseWhether spans are automatically finished when the tracer is flushed
DD_TRACE_CLI_ENABLEDfalseEnable tracing of PHP scripts from the CLI
DD_DISTRIBUTED_TRACINGtrueWhether to enable [distributed tracing][15]
DD_INTEGRATIONS_DISABLEDnullCSV list of disabled extensions; e.g., curl,mysqli
DD_SAMPLING_RATE1.0The sampling rate for the traces. Between 0.0 and 1.0 (default)
DD_SERVICE_NAME``The default app name
DD_TRACE_AGENT_PORT8126The Agent port number
DD_TRACE_AGENT_TIMEOUT500Maximum time the Agent is allowed to take (in milliseconds)
DD_TRACE_AGENT_CONNECT_TIMEOUT100Maximum time the allowed for Agent connection setup (in milliseconds)
DD_TRACE_ANALYTICS_ENABLEDfalseFlag to enable trace analytics for relevant spans in web integrations
DD_TRACE_DEBUGfalseEnable [debug mode][16] for the tracer
DD_TRACE_ENABLEDtrueEnable the tracer globally
DD_TRACE_GLOBAL_TAGS``Tags to be set on all spans: e.g.: key1:value1,key2:value2
DD_<INTEGRATION>_ANALYTICS_ENABLEDfalseFlag to enable trace analytics for relevant spans in a specific integration

Further Reading