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.

Apache

For Apache with php-fpm, use the env directive 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
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

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

# 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

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

Unified service tagging

DD_ENV

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_VERSION

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_SERVICE

INI: datadog.service
Default: null
The default app name.

Traces

DD_TRACE_ENABLED

INI: datadog.trace.enabled
Default: 1
Enable the tracer globally.

DD_PRIORITY_SAMPLING

INI: datadog.priority_sampling
Default: 1
Whether to enable priority sampling.

DD_SERVICE_MAPPING

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_TRACE_128_BIT_TRACEID_GENERATION_ENABLED

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_TRACE_128_BIT_TRACEID_LOGGING_ENABLED

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_TRACE_HEALTH_METRICS_ENABLED

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_TRACE_AGENT_CONNECT_TIMEOUT

INI: datadog.trace.agent_connect_timeout
Default: 100
The Agent connection timeout (in milliseconds).

DD_TRACE_AGENT_PORT

INI: datadog.trace.agent_port
Default: 8126
The Agent port number. If the Agent configuration 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_TRACE_AGENT_TIMEOUT

INI: datadog.trace.agent_timeout
Default: 500
The Agent request transfer timeout (in milliseconds).

DD_TRACE_AGENT_URL

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 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_TRACE_AUTO_FLUSH_ENABLED

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.

DD_TRACE_CLI_ENABLED

INI: datadog.trace.cli_enabled
Default: 0
Enable tracing of PHP scripts from the CLI. See Tracing CLI scripts.

DD_TRACE_DEBUG

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_TRACE_LOG_LEVEL

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_TRACE_LOG_FILE

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_TRACE_FORKED_PROCESS

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_TRACE_GENERATE_ROOT_SPAN

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.

DD_TRACE_HEADER_TAGS

INI: datadog.trace.header_tags
Default: null
CSV of header names that are reported on the root span as tags.

DD_TRACE_HTTP_CLIENT_SPLIT_BY_DOMAIN

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_TRACE_MEASURE_COMPILE_TIME

INI: datadog.trace.measure_compile_time
Default: 1
Record the compile time of the request (in milliseconds) onto the top-level span.

DD_TRACE_REMOVE_AUTOINSTRUMENTATION_ORPHANS

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_TRACE_REMOVE_ROOT_SPAN_LARAVEL_QUEUE

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_TRACE_REMOVE_ROOT_SPAN_SYMFONY_MESSENGER

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_TRACE_LARAVEL_QUEUE_DISTRIBUTED_TRACING

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_TRACE_SYMFONY_MESSENGER_DISTRIBUTED_TRACING

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_TRACE_SYMFONY_MESSENGER_MIDDLEWARES

INI: datadog.trace.symfony_messenger_middlewares
Default: false
Enables the tracing of Symfony Messenger middlewares. Added in version 1.3.0.

DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX

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_TRACE_RESOURCE_URI_MAPPING_INCOMING

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_TRACE_RESOURCE_URI_MAPPING_OUTGOING

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_TRACE_RETAIN_THREAD_CAPABILITIES

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.

DD_HTTP_SERVER_ROUTE_BASED_NAMING

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_TRACE_SAMPLE_RATE

INI: datadog.trace.sample_rate
Default: -1
The sampling rate for the traces, a number between 0.0 and 1.0. The default value of -1 defers control of sampling to the Datadog Agent.

DD_TRACE_RATE_LIMIT

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_TRACE_URL_AS_RESOURCE_NAMES_ENABLED

INI: datadog.trace.url_as_resource_names_enabled
Default: 1
Enable URL’s as resource names (see Map resource names to normalized URI).

DD_TRACE_HTTP_URL_QUERY_PARAM_ALLOWED

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_TRACE_HTTP_POST_DATA_PARAM_ALLOWED

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_TRACE_RESOURCE_URI_QUERY_PARAM_ALLOWED

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_TRACE_CLIENT_IP_ENABLED

INI: datadog.trace.client_ip_enabled
Default: false
Enables IP collection client side. Added in version 0.84.0.

DD_TRACE_CLIENT_IP_HEADER

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 ASM).

DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP

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_TRACE_SAMPLING_RULES

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). The JSON object must be surrounded by single quotes (') to avoid problems with escaping of the double quote (") character. The service matching takes DD_SERVICE_MAPPING into account (starting version 0.90.0). The name and service must be a valid regular expression. Rules that are not valid regular expressions are ignored.

DD_TRACE_SAMPLING_RULES_FORMAT

INI: datadog.trace.sampling_rules_format
Default: glob
Rules the format (regex or glob) used for sampling rules defined by DD_TRACE_SAMPLING_RULES. Added in version 0.98.0 and deprecated as of 1.0.0.

DD_TRACE_SPANS_LIMIT

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_SPAN_SAMPLING_RULES

INI: datadog.span_sampling_rules
Default: null
A JSON encoded string to configure the sampling rate. Rules are applied in configured order to determine the span’s sample rate. The sample_rate value must be between 0.0 and 1.0 (inclusive).
Example: Set the span sample rate to 50% for the service ‘my-service’ and operation name ‘http.request’, up to 50 traces per second: '[{"service": "my-service", "name": "http.request", "sample_rate":0.5, "max_per_second": 50}]'. The JSON object must be surrounded by single quotes (') to avoid problems with escaping of the double quote (") character.
For more information, see Ingestion Mechanisms.

Agent

DD_AGENT_HOST

INI: datadog.agent_host
Default: localhost
The Agent host name.

DD_AUTOFINISH_SPANS

INI: datadog.autofinish_spans
Default: 0
Whether spans are automatically finished when the tracer is flushed.

DD_DISTRIBUTED_TRACING

INI: datadog.distributed_tracing
Default: 1
Whether to enable distributed tracing.

DD_DOGSTATSD_URL

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_DOGSTATSD_PORT

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_TAGS

INI: datadog.tags
Default: null
Tags to be set on all spans, for example: key1:value1,key2:value2.

DD_INSTRUMENTATION_TELEMETRY_ENABLED

INI: datadog.instrumentation_telemetry_enabled
Default: true
Datadog may collect environmental and diagnostic information about your system to improve the product. When false, this telemetry data will not be collected.

Databases

DD_TRACE_DB_CLIENT_SPLIT_BY_INSTANCE

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_TRACE_REDIS_CLIENT_SPLIT_BY_HOST

INI: datadog.trace.redis_client_split_by_host
Default: 0
Set the service name of Redis clients operations to redis-<hostname>.

Database monitoring

DD_DBM_PROPAGATION_MODE

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.

Logs

DD_LOGS_INJECTION

INI: datadog.logs_injection
Default: 0
Enables or disables automatic injection of correlation identifiers into application logs. Added in version 0.89.0
See logs correlation documentation for more information.

OpenTelemetry

DD_TRACE_OTEL_ENABLED

Enables or disables OpenTelemetry based tracing, both for custom or automatic instrumentation.
Valid values are: true or false.
Default: false

Profiling

DD_PROFILING_ENABLED

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. For version 0.81.0 and below it defaulted to 0.

DD_PROFILING_ENDPOINT_COLLECTION_ENABLED

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_PROFILING_ALLOCATION_ENABLED

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_PROFILING_EXPERIMENTAL_FEATURES_ENABLED

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_PROFILING_EXPERIMENTAL_CPU_TIME_ENABLED

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_PROFILING_EXCEPTION_ENABLED

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_PROFILING_EXCEPTION_MESSAGE_ENABLED

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_PROFILING_EXCEPTION_SAMPLING_DISTANCE

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_PROFILING_TIMELINE_ENABLED

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_PROFILING_LOG_LEVEL

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.

Trace context propagation

Read Trace Context Propagation for information about configuring the PHP tracing library to extract and inject headers for propagating distributed trace context.

DD_TRACE_PROPAGATION_STYLE_INJECT

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

• tracecontext
• b3multi
• B3 single header
• Datadog

DD_TRACE_PROPAGATION_STYLE_EXTRACT

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

• tracecontext
• b3multi
• B3 single header
• Datadog

Integrations

DD_TRACE_<INTEGRATION>_ENABLED

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

DD_TRACE_WORDPRESS_ADDITIONAL_ACTIONS

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_TRACE_WORDPRESS_CALLBACKS

INI: datadog.trace.wordpress_callbacks
Default: true for PHP tracer >= v1.0
Enables 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_OPENAI_SERVICE

INI: datadog.openai.service
Default: DD_SERVICE
The service name reported by default for OpenAI requests.

DD_OPENAI_LOGS_ENABLED (beta)

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_OPENAI_METRICS_ENABLED

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_OPENAI_SPAN_CHAR_LIMIT (beta)

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

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

DD_OPENAI_SPAN_PROMPT_COMPLETION_SAMPLE_RATE (beta)

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_OPENAI_LOG_PROMPT_COMPLETION_SAMPLE_RATE (beta)

INI: datadog.openai.log_prompt_completion_sample_rate
Default: 0.1
Configure the sample rate for the collection of prompts and completions as logs.

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.

Map resource names to normalized URI

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.

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

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.

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

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.

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

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

Additional helpful documentation, links, and articles:

PHP monitoring with Datadog APM and distributed tracingBLOG Source codeSOURCE CODE Propagating trace contextDOCUMENTATION Explore your services, resources and tracesDOCUMENTATION Advanced UsageDOCUMENTATION OpenTelemetry Environment Variable ConfigurationsDOCUMENTATION