Join us at the Dash conference! July 16-17, NYC

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

putenv('DD_AGENT_HOST=localhost');
putenv('DD_TRACE_AGENT_PORT=8126');

Compatibility

PHP APM supports the following PHP versions:

Version Support type
7.3.x Fully Supported
7.2.x Fully Supported
7.1.x Fully Supported
7.0.x Fully Supported
5.6.x Fully Supported
5.4.x Fully Supported

PHP APM supports the following SAPI’s:

SAPI Support type
apache2handler Fully Supported
cli Fully Supported
fpm Fully 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.

Module Versions Support Type
Laravel 4.2, 5.x Fully Supported
Lumen 5.2+ Fully Supported
Symfony 2.x, 3.3, 3.4, 4.x Fully Supported
Zend Framework 1.12 Fully Supported
CakePHP 1.3, 2.8, 3.x Coming Soon
CodeIgniter 2, 3 Coming Soon
Drupal Coming Soon
Magento 2 Coming Soon
Phalcon 1.3, 3.4 Coming Soon
Slim 2, 3 Coming Soon
Wordpress Coming Soon
Yii 1.1 Coming 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.

Module Versions Support Type
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.

Datastore Compatibility

Module Versions Support Type
Amazon RDS (using PDO or MySQLi) (Any Supported PHP) Fully Supported
Elasticsearch 1.x Fully Supported
Eloquent Laravel supported versions Fully Supported
Memcached (Any Supported PHP) Fully Supported
MongoDB 1.4.x Fully Supported
MySQLi (Any Supported PHP) Fully Supported
PDO (MySQL, PostgreSQL, MariaDB) (Any Supported PHP) Fully Supported
Predis 1.1 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
PHPredis 4 Coming Soon
Solarium 4.2 Coming Soon

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

Library Compatibility

Module Versions Support Type
Curl (Any Supported PHP) Fully Supported
Guzzle 5.x Fully Supported
Guzzle 6.x Fully Supported
Beanstalkd Coming Soon
ReactPHP Coming 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 variable Default Note
DD_AGENT_HOST localhost The Agent host name
DD_AUTOFINISH_SPANS false Whether spans are automatically finished when the tracer is flushed
DD_TRACE_CLI_ENABLED false Enable tracing of PHP scripts from the CLI
DD_DISTRIBUTED_TRACING true Whether to enable distributed tracing
DD_INTEGRATIONS_DISABLED null CSV list of disabled extensions; e.g., curl,mysqli
DD_PRIORITY_SAMPLING true Whether to enable priority sampling.
DD_SAMPLING_RATE 1.0 The sampling rate for the traces. Between 0.0 and 1.0 (default)
DD_SERVICE_NAME `` The default app name
DD_TRACE_AGENT_PORT 8126 The Agent port number
DD_TRACE_ANALYTICS_ENABLED false Flag to enable trace analytics for relevant spans in web integrations
DD_TRACE_DEBUG false Enable debug mode for the tracer
DD_TRACE_ENABLED true Enable the tracer globally
DD_TRACE_GLOBAL_TAGS `` Tags to be set on all spans: e.g.: key1:value1,key2:value2
DD_<INTEGRATION>_ANALYTICS_ENABLED false Flag to enable trace analytics for relevant spans in a specific integration

Further Reading