---
title: Configuring the PHP Tracing Library
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: >-
  Docs > APM > Application Instrumentation > Configure the Datadog Tracing
  Library > Configuring the PHP Tracing Library
---

# 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](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging/).
To verify your runtime configuration and confirm settings, view the current configuration of your service in Datadog. Navigate to the **APM Service Page**, click **Service Config**, and select the **SDK Configuration** tab.
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.

## Apache{% #apache %}

For Apache with PHP-FPM, use the `env[]` directive in your `www.conf` configuration file to configure the PHP tracer. For example:

```gdscript3
; Example of passing the host environment variable SOME_ENV
; to the PHP process as DD_AGENT_HOST
env[DD_AGENT_HOST] = $SOME_ENV
; 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:** By default, PHP-FPM does not inherit environment variables from the host system when `clear_env=yes` is set in `www.conf`. If you need to use environment variables set on the host, you must explicitly define them using the `env[]` directive.

For Apache without PHP-FPM (mod_php setups), you can set environment variables directly in the server config, virtual host, directory, or `.htaccess` file using [`SetEnv`](https://httpd.apache.org/docs/2.4/mod/mod_env.html#setenv):

```text
# In a virtual host configuration as an environment variable
SetEnv DD_TRACE_DEBUG 1
# In a virtual host configuration as an INI setting
php_value datadog.service my-app
```

## NGINX and PHP-FPM{% #nginx-and-php-fpm %}

{% alert level="danger" %}
PHP-FPM does not support the value `false` in `env[...]` directives. Use `1` in place of `true` and `0` in place of `false`.
{% /alert %}

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

```gdscript3
; Example of passing the host environment variable SOME_ENV
; to the PHP process as DD_AGENT_HOST
env[DD_AGENT_HOST] = $SOME_ENV
; 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](https://docs.datadoghq.com/tracing/trace_collection/proxy_setup/?tab=nginx) for more details.

## PHP CLI server{% #php-cli-server %}

Set in the command line to start the server.

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

## Environment variable configuration{% #environment-variable-configuration %}

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

### Unified service tagging{% #unified-service-tagging %}

{% dl %}

{% dt %}
`DD_ENV`
{% /dt %}

{% dd %}
**INI**: `datadog.env`**Default**: `null`Set an application's environment, for example: `prod`, `pre-prod`, `stage`. Starting version `0.90.0`, changes to `datadog.version` at runtime through `ini_set` are also applied to the current root span.
{% /dd %}

{% dt %}
`DD_VERSION`
{% /dt %}

{% dd %}
**INI**: `datadog.version`**Default**: `null`Set an application's version in traces and logs, for example: `1.2.3`, `6c44da20`, `2020.02.13`. Starting version `0.90.0`, changes to `datadog.version` at runtime through `ini_set` are also applied to the current root span.
{% /dd %}

{% dt %}
`DD_SERVICE`
{% /dt %}

{% dd %}
**INI**: `datadog.service`**Default**: `null`The default app name.
{% /dd %}

{% /dl %}

### Traces{% #traces %}

{% dl %}

{% dt %}
`DD_TRACE_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.enabled`**Default**: `1`Enable the tracer globally.See also [DD_APM_TRACING_ENABLED](https://docs.datadoghq.com/tracing/trace_collection/library_config/#traces).
{% /dd %}

{% dt %}
`DD_PRIORITY_SAMPLING`
{% /dt %}

{% dd %}
**INI**: `datadog.priority_sampling`**Default**: `1`Whether to enable priority sampling.
{% /dd %}

{% dt %}
`DD_SERVICE_MAPPING`
{% /dt %}

{% dd %}
**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).
{% /dd %}

{% dt %}
`DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.128_bit_traceid_generation_enabled`**Default**: `true`When true, the tracer generates 128 bit Trace IDs, and encodes Trace IDs as 32 lowercase hexadecimal characters with zero padding.
{% /dd %}

{% dt %}
`DD_TRACE_128_BIT_TRACEID_LOGGING_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.128_bit_traceid_logging_enabled`**Default**: `0`Enable printing of the full 128-bit trace ID when formatting trace IDs for logs correlation. When false (default), only the low 64-bits of the trace ID are printed, formatted as an integer. This means if the trace ID is only 64 bits, the full ID is printed. When true, the trace ID is printed as a full 128-bit trace ID in hexadecimal format. This is the case even if the ID itself is only 64 bits.
{% /dd %}

{% dt %}
`DD_TRACE_HEALTH_METRICS_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.trace_health_metrics_enabled`**Default**: `false`When enabled, the tracer sends stats to DogStatsD. In addition, where `sigaction` is available at build time, the tracer sends uncaught exception metrics upon segfaults.
{% /dd %}

{% dt %}
`DD_TRACE_AGENT_CONNECT_TIMEOUT`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.agent_connect_timeout`**Default**: `100`The Agent connection timeout (in milliseconds).
{% /dd %}

{% dt %}
`DD_TRACE_AGENT_PORT`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.agent_port`**Default**: `8126`The Agent port number. If the [Agent configuration](https://docs.datadoghq.com/agent/configuration/network/#configure-ports) sets `receiver_port` or `DD_APM_RECEIVER_PORT` to something other than the default `8126`, then `DD_TRACE_AGENT_PORT` or `DD_TRACE_AGENT_URL` must match it.
{% /dd %}

{% dt %}
`DD_TRACE_AGENT_TIMEOUT`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.agent_timeout`**Default**: `500`The Agent request transfer timeout (in milliseconds).
{% /dd %}

{% dt %}
`DD_TRACE_AGENT_URL`
{% /dt %}

{% dd %}
**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`. If the [Agent configuration](https://docs.datadoghq.com/agent/configuration/network/#configure-ports) sets `receiver_port` or `DD_APM_RECEIVER_PORT` to something other than the default `8126`, then `DD_TRACE_AGENT_PORT` or `DD_TRACE_AGENT_URL` must match it.
{% /dd %}

{% dt %}
`DD_TRACE_AUTO_FLUSH_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.auto_flush_enabled`**Default**: `0` (`1` in CLI environment)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](https://docs.datadoghq.com/tracing/guide/trace-php-cli-scripts/#long-running-cli-scripts).
{% /dd %}

{% dt %}
`DD_TRACE_CLI_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.cli_enabled`**Default**: `1`Enable tracing of PHP scripts from the CLI. See [Tracing CLI scripts](https://docs.datadoghq.com/tracing/guide/trace-php-cli-scripts/).
{% /dd %}

{% dt %}
`DD_TRACE_DEBUG`
{% /dt %}

{% dd %}
**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` may be different than the output of `php -i` as it can be overwritten in the PHP-FPM/Apache configuration files. Takes precedence over `DD_TRACE_LOG_LEVEL` if active.
{% /dd %}

{% dt %}
`DD_TRACE_LOG_LEVEL`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.log_level`**Default**: `Error`Sets a precise log level. The log level follows RUST_LOG conventions; accepted log levels are `error`, `warn`, `info`, `debug`, `trace` and `off`.
{% /dd %}

{% dt %}
`DD_TRACE_LOG_FILE`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.log_file`**Default**: ``Specifies a log file. If none is specified, logs go to the default PHP error location. To debug datadog-ipc-helper issues (for example, submission of telemetry), you must specify the log file.
{% /dd %}

{% dt %}
`DD_TRACE_FORKED_PROCESS`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.forked_process`**Default**: `1`Indicates whether to trace a forked process. Set to `1` to trace forked processes, or to `0` to disable tracing in forked processes. If set to `0`, you can still manually re-enable a process' trace in code with `ini_set("datadog.trace.enabled", "1");`, but it will be presented as a fresh trace. Forked process traces are shown as whole distributed traces only when both `DD_TRACE_FORKED_PROCESS` and `DD_DISTRIBUTED_TRACING` are configured to `1` (on).
{% /dd %}

{% dt %}
`DD_TRACE_GENERATE_ROOT_SPAN`
{% /dt %}

{% dd %}
**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](https://docs.datadoghq.com/tracing/guide/trace-php-cli-scripts/#long-running-cli-scripts).
{% /dd %}

{% dt %}
`DD_TRACE_HEADER_TAGS`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.header_tags`**Default**: `null`CSV of header names that are reported on the root span as tags.
{% /dd %}

{% dt %}
`DD_TRACE_HTTP_CLIENT_SPLIT_BY_DOMAIN`
{% /dt %}

{% dd %}
**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 `https://datadoghq.com` has the service name `host-datadoghq.com` instead of the default service name of `curl`.
{% /dd %}

{% dt %}
`DD_TRACE_MEASURE_COMPILE_TIME`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.measure_compile_time`**Default**: `1`Record the compile time of the request (in milliseconds) onto the top-level span.
{% /dd %}

{% dt %}
`DD_TRACE_REMOVE_AUTOINSTRUMENTATION_ORPHANS`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.remove_autoinstrumentation_orphans`**Default**: `false`Automatically remove orphaned spans generated by auto-instrumentation. Currently, this only applies to some Redis and Laravel calls used in the context of Laravel Horizon. Added in version `0.88.0`.**Note:** These orphaned spans are flushed but not recorded in the trace. Moreover, the specific single-span traces that are removed with this configuration option are:
- `laravel.event.handle`
- `laravel.provider.load`
- `Predis.Client.__construct`
- `Predis.Client.executeCommand`
- `Predis.Pipeline.executePipeline`

{% /dd %}

{% dt %}
`DD_TRACE_REMOVE_ROOT_SPAN_LARAVEL_QUEUE`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.remove_root_span_laravel_queue`**Default**: `true`Automatically disable root span generation (see `DD_TRACE_GENERATE_ROOT_SPAN`) and enable auto-flushing (see `DD_TRACE_AUTO_FLUSH_ENABLED`) for Laravel Queue/Horizon commands. Added in version `0.88.0`.
{% /dd %}

{% dt %}
`DD_TRACE_REMOVE_ROOT_SPAN_SYMFONY_MESSENGER`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.remove_root_span_symfony_messenger`**Default**: `true`Automatically disable root span generation (see `DD_TRACE_GENERATE_ROOT_SPAN`) and enable auto-flushing (see `DD_TRACE_AUTO_FLUSH_ENABLED`) for Symfony Messenger commands. Added in version `1.3.0`.
{% /dd %}

{% dt %}
`DD_TRACE_LARAVEL_QUEUE_DISTRIBUTED_TRACING`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.laravel_queue_distributed_tracing`**Default**: `true`Disables the creation of an additional `laravel.queue.process` span and relies solely on span links. Added in version `0.93.0`.
{% /dd %}

{% dt %}
`DD_TRACE_SYMFONY_MESSENGER_DISTRIBUTED_TRACING`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.symfony_messenger_distributed_tracing`**Default**: `true`When disabled, causal produce/consume relationships will be associated using span links. Added in version `1.3.0`.
{% /dd %}

{% dt %}
`DD_TRACE_SYMFONY_MESSENGER_MIDDLEWARES`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.symfony_messenger_middlewares`**Default**: `false`Enables the tracing of Symfony Messenger middlewares. Added in version `1.3.0`.
{% /dd %}

{% dt %}
`DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX`
{% /dt %}

{% dd %}
**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).
{% /dd %}

{% dt %}
`DD_TRACE_RESOURCE_URI_MAPPING_INCOMING`
{% /dt %}

{% dd %}
**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).
{% /dd %}

{% dt %}
`DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING`
{% /dt %}

{% dd %}
**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).
{% /dd %}

{% dt %}
`DD_TRACE_RETAIN_THREAD_CAPABILITIES`
{% /dt %}

{% dd %}
**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](https://github.com/mind04/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.
{% /dd %}

{% dt %}
`DD_HTTP_SERVER_ROUTE_BASED_NAMING`
{% /dt %}

{% dd %}
**INI**: `datadog.http_server_route_based_naming`**Default**: `true`Enable route-based naming for HTTP server requests. Set to `true` to use the integration-specific root span's resource name format. When `false`, the HTTP method and path are used instead. Added in version `0.89.0`.
{% /dd %}

{% dt %}
`DD_TRACE_RATE_LIMIT`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.rate_limit`**Default**: `0`Maximum number of spans to sample per second. All processes in an Apache or FPM pool share the same limiter. When unset (0) rate limiting is delegated to the Datadog Agent.
{% /dd %}

{% dt %}
`DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.url_as_resource_names_enabled`**Default**: `1`Enable URL's as resource names (see Map resource names to normalized URI).
{% /dd %}

{% dt %}
`DD_TRACE_HTTP_URL_QUERY_PARAM_ALLOWED`
{% /dt %}

{% dd %}
**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`.
{% /dd %}

{% dt %}
`DD_TRACE_HTTP_POST_DATA_PARAM_ALLOWED`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.http_post_data_param_allowed`**Default**: ""A comma-separated list of HTTP POST data fields to be collected. Leave empty if you don't want to collect any posted values. When setting this value to the wildcard `*`, all posted data is collected, but the values for fields that match the `DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP` obfuscation rule are redacted. If specific fields are given, then only these fields' values are visible, while the values for all other fields are redacted. Added in version `0.86.0`.**Example**:
- The posted data is `qux=quux&foo[bar][password]=Password12!&foo[bar][username]=admin&foo[baz][bar]=qux&foo[baz][key]=value`
- `DD_TRACE_HTTP_POST_DATA_PARAM_ALLOWED` is set to `foo.baz,foo.bar.password`
- In this scenario, the collected metadata is:
  - `http.request.foo.bar.password=Password12!`
  - `http.request.foo.bar.username=<redacted>`
  - `http.request.foo.baz.bar=qux`
  - `http.request.foo.baz.key=value`
  - `http.request.qux=<redacted>`

{% /dd %}

{% dt %}
`DD_TRACE_RESOURCE_URI_QUERY_PARAM_ALLOWED`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.resource_uri_query_param_allowed`**Default**: `*`A comma-separated list of query parameters to be collected as part of the resource URI. Set to empty to prevent collecting any parameters, or `*` to collect all parameters. Added in version `0.74.0`.
{% /dd %}

{% dt %}
`DD_TRACE_CLIENT_IP_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.client_ip_enabled`**Default**: `false`Enables IP collection client side. Added in version `0.84.0`.
{% /dd %}

{% dt %}
`DD_TRACE_CLIENT_IP_HEADER`
{% /dt %}

{% dd %}
**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.84.0` (`0.76.0` when using AAP).
{% /dd %}

{% dt %}
`DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.obfuscation_query_string_regexp`**Default**:
```
(?i)(?:p(?:ass)?w(?:or)?d|pass(?:_?phrase)?|secret|(?:api_?|private_?|public_?|access_?|secret_?)key(?:_?id)?|token|consumer_?(?:id|key|secret)|sign(?:ed|ature)?|auth(?:entication|orization)?)(?:(?:\s|%20)*(?:=|%3D)[^&]+|(?:"|%22)(?:\s|%20)*(?::|%3A)(?:\s|%20)*(?:"|%22)(?:%2[^2]|%[^2]|[^"%])+(?:"|%22))|bearer(?:\s|%20)+[a-z0-9\._\-]|token(?::|%3A)[a-z0-9]{13}|gh[opsu]_[0-9a-zA-Z]{36}|ey[I-L](?:[\w=-]|%3D)+\.ey[I-L](?:[\w=-]|%3D)+(?:\.(?:[\w.+\/=-]|%3D|%2F|%2B)+)?|[\-]{5}BEGIN(?:[a-z\s]|%20)+PRIVATE(?:\s|%20)KEY[\-]{5}[^\-]+[\-]{5}END(?:[a-z\s]|%20)+PRIVATE(?:\s|%20)KEY|ssh-rsa(?:\s|%20)*(?:[a-z0-9\/\.+]|%2F|%5C|%2B){100,}
```

Regular expression used to obfuscate the query string included as part of the URL. This expression is also used in the redaction process for HTTP POST data. Added in version `0.76.0`.
{% /dd %}

{% dt %}
`DD_TRACE_SPANS_LIMIT`
{% /dt %}

{% dd %}
**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`.
{% /dd %}

{% /dl %}

### Agent{% #agent %}

{% dl %}

{% dt %}
`DD_AGENT_HOST`
{% /dt %}

{% dd %}
**INI**: `datadog.agent_host`**Default**: `localhost`The Agent host name.
{% /dd %}

{% dt %}
`DD_AUTOFINISH_SPANS`
{% /dt %}

{% dd %}
**INI**: `datadog.autofinish_spans`**Default**: `0`Whether spans are automatically finished when the tracer is flushed.
{% /dd %}

{% dt %}
`DD_DISTRIBUTED_TRACING`
{% /dt %}

{% dd %}
**INI**: `datadog.distributed_tracing`**Default**: `1`Whether to enable distributed tracing.
{% /dd %}

{% dt %}
`DD_DOGSTATSD_URL`
{% /dt %}

{% dd %}
**INI**: `datadog.dogstatsd_url`**Default**: `null`The URL used to negotiate connection to DogStatsD. This setting takes precedence over `DD_AGENT_HOST` and `DD_DOGSTATSD_PORT`. Supports `udp://` or `unix://` schemas only.
{% /dd %}

{% dt %}
`DD_DOGSTATSD_PORT`
{% /dt %}

{% dd %}
**INI**: `datadog.dogstatsd_port`**Default**: `8125`The port used to connect to DogStatsD, used in combination with `DD_AGENT_HOST` to negotiate connection to DogStatsD when `DD_TRACE_HEALTH_METRICS_ENABLED` is enabled.
{% /dd %}

{% dt %}
`DD_TAGS`
{% /dt %}

{% dd %}
**INI**: `datadog.tags`**Default**: `null`Tags to be set on all spans, for example: `key1:value1,key2:value2`.
{% /dd %}

{% dt %}
`DD_INSTRUMENTATION_TELEMETRY_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.instrumentation_telemetry_enabled`**Default**: `true`Datadog may collect [environmental and diagnostic information about your system](https://docs.datadoghq.com/tracing/configure_data_security#telemetry-collection) to improve the product. When false, this telemetry data will not be collected.
{% /dd %}

{% /dl %}

### Databases{% #databases %}

{% dl %}

{% dt %}
`DD_TRACE_DB_CLIENT_SPLIT_BY_INSTANCE`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.db_client_split_by_instance`**Default**: `0`Set the service name of HTTP requests to `pdo-<hostname>`. For example, a `PDO->query()` call to a database host `datadoghq.com` has the service name `pdo-datadoghq.com` instead of the default service name of `pdo`.
{% /dd %}

{% dt %}
`DD_TRACE_REDIS_CLIENT_SPLIT_BY_HOST`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.redis_client_split_by_host`**Default**: `0`Set the service name of Redis clients operations to `redis-<hostname>`.
{% /dd %}

{% /dl %}

### Database monitoring{% #database-monitoring %}

{% dl %}

{% dt %}
`DD_DBM_PROPAGATION_MODE`
{% /dt %}

{% dd %}
**INI**: `datadog.dbm_propagation_mode`**Default**: `'disabled'`Enables linking between data sent from APM and the Database Monitoring product when set to `'service'` or `'full'`.The `'service'` option enables the connection between DBM and APM services. Available for Postgres, MySQL and SQLServer.The `'full'` option enables connection between database spans with database query events. Available for Postgres and MySQL.
{% /dd %}

{% /dl %}

### Logs{% #logs %}

{% dl %}

{% dt %}
`DD_LOGS_INJECTION`
{% /dt %}

{% dd %}
**INI**: `datadog.logs_injection`**Default**: `1`Enables or disables automatic injection of correlation identifiers into JSON/structured application logs. Added in version `0.89.0`See [logs correlation documentation](https://docs.datadoghq.com/tracing/other_telemetry/connect_logs_and_traces/php) for more information.
{% /dd %}

{% /dl %}

### OpenTelemetry{% #opentelemetry %}

{% dl %}

{% dt %}
`DD_TRACE_OTEL_ENABLED`
{% /dt %}

{% dd %}
Enables or disables OpenTelemetry based tracing, both for [custom](https://docs.datadoghq.com/tracing/trace_collection/otel_instrumentation/php/) or [automatic](https://docs.datadoghq.com/tracing/trace_collection/compatibility/php/) instrumentation.Valid values are: `true` or `false`.**Default**: `false`
{% /dd %}

{% /dl %}

### Profiling{% #profiling %}

{% dl %}

{% dt %}
`DD_PROFILING_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.enabled`. INI available since `0.82.0`.**Default**: `1`Enable the Datadog profiler. Added in version `0.69.0`. See [Enabling the PHP Profiler](https://docs.datadoghq.com/profiler/enabling/php/). For version `0.81.0` and below it defaulted to `0`.
{% /dd %}

{% dt %}
`DD_PROFILING_ENDPOINT_COLLECTION_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.endpoint_collection_enabled`. INI available since `0.82.0`.**Default**: `1`Whether to enable the endpoint data collection in profiles. Added in version `0.79.0`.
{% /dd %}

{% dt %}
`DD_PROFILING_ALLOCATION_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.allocation_enabled`. INI available since `0.88.0`.**Default**: `1`Enable the allocation size and allocation bytes profile type. Added in version `0.88.0`. When an active JIT is detected, allocation profiling is turned off for PHP version `8.0.0`-`8.1.20` and `8.2.0`-`8.2.7` due to a limitation of the ZendEngine.**Note**: This supersedes the `DD_PROFILING_EXPERIMENTAL_ALLOCATION_ENABLED` environment variable (`datadog.profiling.experimental_allocation_enabled` INI setting), which was available since `0.84`. If both are set, this one takes precedence.
{% /dd %}

{% dt %}
`DD_PROFILING_ALLOCATION_SAMPLING_DISTANCE`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.allocation_sampling_distance`. **Default**: `4194304` (4 MB)Configure the sampling distance for allocations. The higher the sampling distance, the fewer samples are created and the lower the overhead. Added in version `1.9.0`.
{% /dd %}

{% dt %}
`DD_PROFILING_EXPERIMENTAL_FEATURES_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.experimental_features_enabled`. INI available since `0.96.0`.**Default**: `0`Enable all experimental features.**Note**: This setting overrides the more specific configurations and if enabled, toggling other experimental configuration settings won't have an effect.
{% /dd %}

{% dt %}
`DD_PROFILING_EXPERIMENTAL_CPU_TIME_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.experimental_cpu_time_enabled`. INI available since `0.82.0`.**Default**: `1`Enable the experimental CPU profile type. Added in version `0.69.0`. For version `0.76` and below it defaulted to `0`.
{% /dd %}

{% dt %}
`DD_PROFILING_EXCEPTION_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.exception_enabled`. INI available since `0.96.0`.**Default**: `1`Enable the exception profile type. Added in version `0.92.0` and GA in version `0.96.0`.**Note**: This supersedes the `DD_PROFILING_EXPERIMENTAL_EXCEPTION_ENABLED` environment variable (`datadog.profiling.experimental_exception_enabled` INI setting), which was available since `0.92`. If both are set, this one takes precedence.
{% /dd %}

{% dt %}
`DD_PROFILING_EXCEPTION_MESSAGE_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.exception_message_enabled`. INI available since `0.98.0`.**Default**: `0`Enable the collection of exception messages with exception samples.**Note**: Please be aware that your exception messages might contain PII (Personal Identifiable Information), which is the reason why this setting is default disabled.
{% /dd %}

{% dt %}
`DD_PROFILING_EXCEPTION_SAMPLING_DISTANCE`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.exception_sampling_distance`. INI available since `0.96.0`.**Default**: `100`Configure the sampling distance for exceptions. The higher the sampling distance, the fewer samples are created and the lower the overhead.**Note**: This supersedes the `DD_PROFILING_EXPERIMENTAL_EXCEPTION_SAMPLING_DISTANCE` environment variable (`datadog.profiling.experimental_exception_sampling_distance` INI setting), which was available since `0.92`. If both are set, this one takes precedence.
{% /dd %}

{% dt %}
`DD_PROFILING_TIMELINE_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.timeline_enabled`. INI available since `0.98.0`.**Default**: `1`Enable the timeline profile type. Added in version `0.89.0`.**Note**: This supersedes the `DD_PROFILING_EXPERIMENTAL_TIMELINE_ENABLED` environment variable (`datadog.profiling.experimental_timeline_enabled` INI setting), which was available since `0.89` (default `0`). If both are set, this one takes precedence.
{% /dd %}

{% dt %}
`DD_PROFILING_EXPERIMENTAL_IO_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.experimental_io_enabled`. INI available since `1.7.2`.**Default**: `1`Enable the I/O profile type. Added as beta in version `1.7.2`.
{% /dd %}

{% dt %}
`DD_PROFILING_LOG_LEVEL`
{% /dt %}

{% dd %}
**INI**: `datadog.profiling.log_level`. INI available since `0.82.0`.**Default**: `off`Set the profiler's log level. Acceptable values are `off`, `error`, `warn`, `info`, `debug`, and `trace`. The profiler's logs are written to the standard error stream of the process. Added in version `0.69.0`.
{% /dd %}

{% /dl %}

### Trace context propagation{% #trace-context-propagation %}

Read [Trace Context Propagation](https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation/) for information about configuring the PHP tracing library to extract and inject headers for propagating distributed trace context.

{% dl %}

{% dt %}
`DD_TRACE_PROPAGATION_STYLE_INJECT`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.propagation_style_inject`**Default**: `Datadog,tracecontext,baggage`Propagation styles to use when injecting tracing headers. If using multiple styles, comma separate them. The supported styles are:
- [tracecontext](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format)
- [b3multi](https://github.com/openzipkin/b3-propagation)
- [B3 single header](https://github.com/openzipkin/b3-propagation#single-header)
- Datadog
- [Baggage](https://www.w3.org/TR/baggage/)

{% /dd %}

{% dt %}
`DD_TRACE_PROPAGATION_STYLE_EXTRACT`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.propagation_style_extract`**Default**: `Datadog,tracecontext,b3multi,B3 single header,baggage`Propagation styles to use when extracting tracing headers. If using multiple styles, comma separate them. The supported styles are:
- [tracecontext](https://www.w3.org/TR/trace-context/#trace-context-http-headers-format)
- [b3multi](https://github.com/openzipkin/b3-propagation)
- [B3 single header](https://github.com/openzipkin/b3-propagation#single-header)
- Datadog
- [Baggage](https://www.w3.org/TR/baggage/)

{% /dd %}

{% /dl %}

### Integrations{% #integrations %}

{% dl %}

{% dt %}
`DD_TRACE_<INTEGRATION>_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.<INTEGRATION>_enabled`**Default**: `1`Enable or disable an integration; all integrations are enabled by default (see Integration names).
{% /dd %}

{% dt %}
`DD_TRACE_WORDPRESS_ADDITIONAL_ACTIONS`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.wordpress_additional_actions`**Default**: `null`A comma-separated list of WordPress action hooks to be instrumented. This feature is only available when `DD_TRACE_WORDPRESS_ENHANCED_INTEGRATION` is enabled. Added in version `0.91.0`.
{% /dd %}

{% dt %}
`DD_TRACE_WORDPRESS_CALLBACKS`
{% /dt %}

{% dd %}
**INI**: `datadog.trace.wordpress_callbacks`**Default**: `true` for PHP tracer >= v1.0Enables WordPress action hook callbacks instrumentation. This feature is only available when `DD_TRACE_WORDPRESS_ENHANCED_INTEGRATION` is enabled. Added in version `0.91.0`.
{% /dd %}

{% dt %}
`DD_OPENAI_SERVICE`
{% /dt %}

{% dd %}
**INI**: `datadog.openai.service`**Default**: `DD_SERVICE`The service name reported by default for OpenAI requests.
{% /dd %}

{% dt %}
`DD_OPENAI_LOGS_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.openai.logs_enabled`**Default**: `false`Enable collection of prompts and completions as logs. You can adjust the rate of prompts and completions collected using the sample rate configuration described below.
{% /dd %}

{% dt %}
`DD_OPENAI_METRICS_ENABLED`
{% /dt %}

{% dd %}
**INI**: `datadog.openai.metrics_enabled`**Default**: `true`Enable collection of OpenAI metrics.If the Datadog Agent is configured to use a non-default StatsD hostname or port, use `DD_DOGSTATSD_URL` to configure the OpenAI metrics collection.
{% /dd %}

{% dt %}
`DD_OPENAI_SPAN_CHAR_LIMIT`
{% /dt %}

{% dd %}
**INI**: `datadog.openai.span_char_limit`**Default**: `128`Configure the maximum number of characters for the following data within span tags:
- Prompt inputs and completions
- Message inputs and completions
- Embedding inputs

{% /dd %}

{% /dl %}

Text exceeding the maximum number of characters is truncated to the character limit and has `...` appended to the end.

{% dl %}

{% dt %}
`DD_OPENAI_SPAN_PROMPT_COMPLETION_SAMPLE_RATE`
{% /dt %}

{% dd %}
**INI**: `datadog.openai.span_prompt_completion_sample_rate`**Default**: `1.0`Configure the sample rate for the collection of prompts and completions as span tags.
{% /dd %}

{% dt %}
`DD_OPENAI_LOG_PROMPT_COMPLETION_SAMPLE_RATE`
{% /dt %}

{% dd %}
**INI**: `datadog.openai.log_prompt_completion_sample_rate`**Default**: `0.1`Configure the sample rate for the collection of prompts and completions as logs.
{% /dd %}

{% /dl %}

#### Integration names{% #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`.

| Integration       | Service Name       |
| ----------------- | ------------------ |
| AMQP              | `amqp`             |
| CakePHP           | `cakephp`          |
| CodeIgniter       | `codeigniter`      |
| cURL              | `curl`             |
| ElasticSearch     | `elasticsearch`    |
| Eloquent          | `eloquent`         |
| Guzzle            | `guzzle`           |
| Laminas           | `laminas`          |
| Laravel           | `laravel`          |
| Laravel Queue     | `laravelqueue`     |
| Lumen             | `lumen`            |
| Memcache          | `memcache`         |
| Memcached         | `memcached`        |
| Mongo             | `mongo`            |
| MongoDB           | `mongodb`          |
| Mysqli            | `mysqli`           |
| Nette             | `nette`            |
| OpenAI            | `openai`           |
| PCNTL             | `pcntl`            |
| PDO               | `pdo`              |
| PhpRedis          | `phpredis`         |
| Predis            | `predis`           |
| Psr18             | `psr18`            |
| Roadrunner        | `roadrunner`       |
| Sql Server        | `sqlsrv`           |
| Symfony           | `symfony`          |
| Symfony Messenger | `symfonymessenger` |
| WordPress         | `wordpress`        |
| Yii               | `yii`              |
| ZendFramework     | `zendframework`    |

## Map resource names to normalized URI{% #map-resource-names-to-normalized-uri %}

{% alert level="danger" %}
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.
{% /alert %}

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 Request                       | Resource Name |
| ---------------------------------- | ------------- |
| **GET** request to `/foo?a=1&b=2`  | `GET /foo`    |
| **POST** request to `/bar?foo=bar` | `POST /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/show`                               | `GET /user/?/show` |
| `/widget/b7a992e0-3300-4030-8617-84553b11c993` | `GET /widget/?`    |
| `/api/v2/b7a992e033004030861784553b11c993/123` | `GET /api/v2/?/?`  |
| `/book/0dbf3596`                               | `GET /book/?`      |

You can turn this functionality OFF using `DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED=0`.

### Custom URL-to-resource mapping{% #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/id`     | `GET /using/prefix/?/for/id`  |
| `/articles/slug-of-title`        | `GET /articles/?`             |
| `/cities/new-york/rivers`        | `GET /cities/?/rivers`        |
| `/nested/cities/new-york/rivers` | `GET /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.

##### `DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX`{% #dd_trace_resource_uri_fragment_regex %}

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

| URL                          | regex     | Expected 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.

##### `DD_TRACE_RESOURCE_URI_MAPPING_INCOMING` and `DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING`{% #dd_trace_resource_uri_mapping_incoming-and-dd_trace_resource_uri_mapping_outgoing %}

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{% #open_basedir-restrictions %}

When [`open_basedir`](https://www.php.net/manual/en/ini.core.php#ini.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{% #further-reading %}

- [PHP monitoring with Datadog APM and distributed tracing](https://www.datadoghq.com/blog/monitor-php-performance/)
- [Source code](https://github.com/DataDog/dd-trace-php)
- [Propagating trace context](https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation/)
- [Explore your services, resources and traces](https://docs.datadoghq.com/tracing/glossary/)
- [Advanced Usage](https://docs.datadoghq.com/tracing/)
- [OpenTelemetry Environment Variable Configurations](https://docs.datadoghq.com/opentelemetry/interoperability/environment_variable_support)