Configuring the PHP Tracing Library

After you set up the tracing library with your code and configure the Agent to collect APM data, optionally configure the tracing library as desired, including setting up Unified Service Tagging.

The PHP tracer can be configured using environment variables and INI settings.

INI settings can be configured globally, for example, in the php.ini file, or for a specific web server or virtual host.

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 and the INI settings 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 do not work.


For Apache with php-fpm, use the env directory in your www.conf configuration file to configure the PHP tracer, for example:

; Example of passing the host environment variable SOME_ENV
; to the PHP process as DD_AGENT_HOST
; Example of passing the value 'my-app' to the PHP
; process as DD_SERVICE
env[DD_SERVICE] = my-app
; Or using the equivalent INI setting
php_value datadog.service my-app

Alternatively, you can use SetEnv from the server config, virtual host, directory, or .htaccess file.

# In a virtual host configuration as an environment variable
# In a virtual host configuration as an INI setting
php_value datadog.service my-app


Note: PHP-FPM does not support the value false in env[...] directives. Use 1 in place of true and 0 in place of false.

For NGINX, use the env directive in the php-fpm’s www.conf file, for example:

; Example of passing the host environment variable SOME_ENV
; to the PHP process as DD_AGENT_HOST
; Example of passing the value 'my-app' to the PHP
; process as DD_SERVICE
env[DD_SERVICE] = my-app
; Or using the equivalent INI setting
php_value[datadog.service] = my-app

Note: If you have enabled APM for your NGINX server, make sure you have properly configured the opentracing_fastcgi_propagate_context setting for distributed tracing to properly work. See NGINX APM configuration for more details.

PHP CLI server

Set in the command line to start the server.

DD_TRACE_DEBUG=1 php -d datadog.service=my-app -S localhost:8888

Environment variable configuration

The following table lists the environment variables for configuring tracing, and corresponding INI settings (where available) and defaults.

INI: datadog.agent_host
Default: localhost
The Agent host name.
INI: datadog.autofinish_spans
Default: 0
Whether spans are automatically finished when the tracer is flushed.
INI: datadog.distributed_tracing
Default: 1
Whether to enable distributed tracing.
INI: datadog.env
Default: null
Set an application’s environment, for example: prod, pre-prod, stage. Added in version 0.47.0.
INI: Not available
Default: 0
Enable the Datadog profiler. Added in version 0.69.0. See Enabling the PHP Profiler.
INI: Not available
Default: 1
Enable the experimental CPU profile type. Added in version 0.69.0. For version 0.76 and below it defaulted to 0.
INI: Not available
Default: off
Set the profiler’s log level. Acceptable values are off, error, warn, info, and debug. The profiler’s logs are written to the standard error stream of the process. Added in version 0.69.0.
INI: datadog.priority_sampling
Default: 1
Whether to enable priority sampling.
INI: datadog.service
Default: null
The default app name. For versions <0.47.0 this is DD_SERVICE_NAME.
INI: datadog.service_mapping
Default: null
Change the default name of an APM integration. Rename one or more integrations at a time, for example: DD_SERVICE_MAPPING=pdo:payments-db,mysqli:orders-db (see Integration names).
INI: datadog.trace.agent_attempt_retry_time_msec
Default: 5000
IPC-based configurable circuit breaker retry time (in milliseconds).
INI: datadog.trace.agent_connect_timeout
Default: 100
The Agent connection timeout (in milliseconds).
INI: datadog.trace.agent_max_consecutive_failures
Default: 3
IPC-based configurable circuit breaker max consecutive failures.
INI: datadog.trace.agent_port
Default: 8126
The Agent port number.
INI: datadog.trace.agent_timeout
Default: 500
The Agent request transfer timeout (in milliseconds).
INI: datadog.trace.agent_url
Default: null
The Agent URL; takes precedence over DD_AGENT_HOST and DD_TRACE_AGENT_PORT; for example: https://localhost:8126. Added in version 0.47.1.
INI: datadog.trace.auto_flush_enabled
Default: 0
Automatically flush the tracer when all the spans are closed; set to 1 in conjunction with DD_TRACE_GENERATE_ROOT_SPAN=0 to trace long-running processes.
INI: datadog.trace.cli_enabled
Default: 0
Enable tracing of PHP scripts from the CLI. See Tracing CLI scripts.
INI: datadog.trace.debug
Default: 0
Enable debug mode. When 1, log messages are sent to the device or file set in the error_log INI setting. The actual value of error_log might be different than the output of php -i as it can be overwritten in the PHP-FPM/Apache configuration files.
INI: datadog.trace.enabled
Default: 1
Enable the tracer globally.
INI: datadog.trace.generate_root_span
Default: 1
Automatically generate a top-level span; set to 0 in conjunction with DD_TRACE_AUTO_FLUSH_ENABLED=1 to trace long-running processes.
INI: datadog.tags
Default: null
Tags to be set on all spans, for example: key1:value1,key2:value2. Added in version 0.47.0.
INI: datadog.trace.header_tags
Default: null
CSV of header names that are reported on the root span as tags.
INI: datadog.trace.http_client_split_by_domain
Default: 0
Set the service name of HTTP requests to host-<hostname>, for example a curl_exec() call to has the service name instead of the default service name of curl.
INI: datadog.trace.redis_client_split_by_host
Default: 0
Set the service name of Redis clients operations to redis-<hostname>. Added in version 0.51.0.
INI: datadog.trace.<INTEGRATION>_enabled
Default: 1
Enable or disable an integration; all integrations are enabled by default (see Integration names). For versions < 0.47.1, this parameter is DD_INTEGRATIONS_DISABLED which takes a CSV list of integrations to disable, for example: curl,mysqli.
INI: datadog.trace.measure_compile_time
Default: 1
Record the compile time of the request (in milliseconds) onto the top-level span.
INI: datadog.trace.resource_uri_fragment_regex
Default: null
CSV of regexes that identifies path fragments corresponding to IDs (see Map resource names to normalized URI).
INI: datadog.trace.resource_uri_mapping_incoming
Default: null
CSV of URI mappings to normalize resource naming for incoming requests (see Map resource names to normalized URI).
INI: datadog.trace.resource_uri_mapping_outgoing
Default: null
CSV of URI mappings to normalize resource naming for outgoing requests (see Map resource names to normalized URI).
INI: datadog.trace.retain_thread_capabilities
Default: 0
Works for Linux. Set to true to retain capabilities on Datadog background threads when you change the effective user ID. This option does not affect most setups, but some modules - to date Datadog is only aware of Apache’s mod-ruid2 - may invoke setuid() or similar syscalls, leading to crashes or loss of functionality as it loses capabilities.

Note: Enabling this option may compromise security. This option, standalone, does not pose a security risk. However, an attacker being able to exploit a vulnerability in PHP or web server may be able to escalate privileges with relative ease, if the web server or PHP were started with full capabilities, as the background threads will retain their original capabilities. Datadog recommends restricting the capabilities of the web server with the setcap utility.
INI: datadog.trace.sample_rate
Default: 1.0
The sampling rate for the traces (defaults to: between 0.0 and 1.0). For versions < 0.36.0, this parameter is DD_SAMPLING_RATE.
INI: datadog.trace.sampling_rules
Default: null
A JSON encoded string to configure the sampling rate. Examples: Set the sample rate to 20%: '[{"sample_rate": 0.2}]'. Set the sample rate to 10% for services starting with ‘a’ and span name ‘b’ and set the sample rate to 20% for all other services: '[{"service": "a.*", "name": "b", "sample_rate": 0.1}, {"sample_rate": 0.2}]' (see Integration names). Note that the JSON object must be included in single quotes (') to avoid problems with escaping of the double quote (") character.|
INI: datadog.trace.spans_limit Default: 1000
The maximum number of spans that are generated within one trace. If the maximum number of spans is reached, then spans are no longer generated. If the limit is increased, then the amount of memory that is used by a pending trace will increase and might reach the PHP maximum amount of allowed memory. The maximum amount of allowed memory can be increased with the PHP INI system setting memory_limit.
INI: datadog.trace.url_as_resource_names_enabled
Default: 1
Enable URL’s as resource names (see Map resource names to normalized URI).
INI: datadog.version
Default: null
Set an application’s version in traces and logs, for example: 1.2.3, 6c44da20, 2020.02.13. Added in version 0.47.0.
INI: datadog.trace.http_url_query_param_allowed
Default: *
A comma-separated list of query parameters to be collected as part of the URL. Set to empty to prevent collecting any parameters, or * to collect all parameters. Added in version 0.74.0.
INI: datadog.trace.client_ip_header_disabled
Default: 0
Disable client IP collection from relevant IP headers. Added in version 0.76.0.
INI: datadog.trace.client_ip_header
Default: null
The IP header to be used for client IP collection, for example: x-forwarded-for. Added in version 0.76.0.
INI: datadog.trace.obfuscation_query_string_regexp

Regular expression used to obfuscate the query string included as part of the URL. Added in version 0.76.0.

INI: datadog.trace.propagation_style_inject
Default: Datadog
Propagation styles to use when injecting tracing headers. If using multiple styles, comma separate them. The supported styles are:
INI: datadog.trace.propagation_style_extract
Default: Datadog,B3,B3 single header
Propagation styles to use when extracting tracing headers. If using multiple styles, comma separate them. The supported styles are:

Integration names

The table below specifies the default service names for each integration. Change the service names with DD_SERVICE_MAPPING.

Use the name when setting integration-specific configuration such as, DD_TRACE_<INTEGRATION>_ENABLED, for example: Laravel is DD_TRACE_LARAVEL_ENABLED.

IntegrationService Name

Map resource names to normalized URI

Deprecation notice: As of version 0.47.0 the legacy setting DD_TRACE_RESOURCE_URI_MAPPING is deprecated. It still works for the foreseeable future but it is strongly encouraged that you use the new settings outlined in this paragraph to avoid issues when legacy support is removed.

Note that setting any of the following: DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX, DD_TRACE_RESOURCE_URI_MAPPING_INCOMING, and DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING will opt-in to the new resource normalization approach and any value in DD_TRACE_RESOURCE_URI_MAPPING will be ignored.

For HTTP server and client integrations, 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 RequestResource Name
GET request to /foo?a=1&b=2GET /foo
POST request to /bar?foo=barPOST /bar

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

URL (GET request)Resource Name
/user/123/showGET /user/?/show
/widget/b7a992e0-3300-4030-8617-84553b11c993GET /widget/?
/api/v2/b7a992e033004030861784553b11c993/123GET /api/v2/?/?
/book/0dbf3596GET /book/?

You can turn this functionality OFF using DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED=0.

Custom URL-to-resource mapping

There are a few cases that are not covered by the automatic normalization that is applied.

URL (GET request)Expected Resource Name
/using/prefix/id123/for/idGET /using/prefix/?/for/id
/articles/slug-of-titleGET /articles/?
/cities/new-york/riversGET /cities/?/rivers
/nested/cities/new-york/riversGET /nested/cities/?/rivers

There are two classes of scenarios that are not covered by automatic normalization:

  • The path fragment to normalize has a reproducible pattern and can be present in any part of the url, for example id<number> in the example above. This scenario is covered by the setting DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX below.
  • The path fragment can be anything, and the previous path fragment indicates that a value has to be normalized. For example /cities/new-york tells us that new-york has to be normalized as it is the name of a city. This scenario is covered by settings DD_TRACE_RESOURCE_URI_MAPPING_INCOMING and DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING for incoming and outgoing requests respectively.

This setting is a CSV of one or more regular expressions that are applied to every path fragment independently. For example, setting DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX to ^id\d+$ for a path of /using/prefix/id123/for/id applies the regex to each of the fragments: using, prefix, id123, for, and id.

URLregexExpected Resource Name
/using/prefix/id123/for/id^id\d+$GET /using/prefix/?/for/id

Note that because the format of this variable is a CSV, the comma character , is not escaped and cannot be used in your regular expressions.


This setting is a CSV of patterns that can contain a wildcard *. For example, adding the pattern cities/* means that every time the fragment cities is found while analyzing a URL, then the next fragment, if any, will be replaced with ?. Patterns are applied at any depth, so applying the following rule will both normalize /cities/new-york and /nested/cities/new-york in the table above.

Patterns can be applied to a part of a specific fragment. For example path/*-fix would normalize the url /some/path/changing-fix/nested to /some/path/?-fix/nested

Note that DD_TRACE_RESOURCE_URI_MAPPING_INCOMING applies to only incoming requests (for example web frameworks) while DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING only applies to outgoing requests (for example curl and guzzle requests).

open_basedir restrictions

When open_basedir setting is used, then /opt/datadog-php should be added to the list of allowed directories. When the application runs in a docker container, the path /proc/self should also be added to the list of allowed directories.

Further Reading