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+ 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.

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

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.

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:

PHP APM supports the following SAPI’s:

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.

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.

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

Datastore Compatibility

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

Library Compatibility

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

Map Resource Names To Normalized URI

When 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.

Numeric IDs, UUIDs (with and without dashes), and 32-to-512-bit hexadecimal hashes are automatically replaced with a ? character.

Custom URL-To-Resource Mapping

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 * and $* are supported, so DD_TRACE_RESOURCE_URI_MAPPING=/foo/*,/bar/$*/baz. In this context, * is a greedy match with a replacement character ?, and $* 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. /foo/$*/bar,/foo/*

The * wildcard is replaced with ?.

The $* wildcard matches without replacement.

Upgrading

To upgrade the PHP tracer, download the latest release and follow the same steps as installing the extension.

Further Reading

Documentation, liens et articles supplémentaires utiles:

PHP monitoring with Datadog APM and distributed tracingBLOG Source codeGITHUB Explore your services, resources and tracesDOCUMENTATION Advanced UsageDOCUMENTATION