PHP continuous profiling
In this tutorial, you enable continuous profiling for a PHP application by using the open-source dd-trace-php extension and report profiling data to Application Real-Time Monitoring Service (ARMS) Continuous Profiling.
The workflow consists of three stages: deploy a profiling receiver in your cluster, install the dd-trace-php extension with profiling enabled, and configure environment variables to connect the profiler to the receiver.
Step 1: Install the profiling receiver
The profiling receiver accepts data from the dd-trace-php profiler and uploads it to ARMS through OSS. Deploy the receiver in the same cluster as your PHP application.
Log on to the Container Service for Kubernetes (ACK) console. In the left-side navigation pane, click Clusters. Then, click the name of the target cluster.
In the left-side navigation pane, click Components and Add-ons. Find the
arms-obiadd-on and install it. SetinstallModetoprofiling.
Step 2: Install dd-trace-php with profiling
Install the dd-trace-php extension with the profiling module enabled. Run the following commands:
curl -sSL -o /tmp/datadog-setup.php \
https://github.com/DataDog/dd-trace-php/releases/download/1.23.0/datadog-setup.php
php /tmp/datadog-setup.php --php-bin all --enable-profiling
php -m | grep -i datadog # You should see datadog-profilingThe --enable-profiling flag is critical: without it, only the tracer is installed and the profiler is not included. Add the installation steps to your Dockerfile to avoid downloading the package on every container startup. For installation issues, refer to the dd-trace-php open-source repository.
Configure php-fpm (conditional)
If your application runs on php-fpm, you must disable clear_env. By default, php-fpm sets clear_env = yes, which clears all environment variables in worker processes. This prevents the DD_* variables from reaching the profiler, causing the symptom of "installed but not reporting."
Add the following setting to your pool configuration:
; /usr/local/etc/php-fpm.d/www.conf
clear_env = noThis setting applies only to php-fpm. CLI and mod_php are not affected.
Step 3: Configure environment variables
Set the following environment variables in your PHP application's runtime environment. The profiler reads these variables to determine what data to collect and where to send it.
Basic (required)
Variable | Description | Recommended value |
| Profiling master switch ( |
|
| Service name used to identify different applications. | Your service name |
| Environment tag (prod/staging...) |
|
| Version tag |
|
| Receiver address. The profiler reports data to |
|
DD_TRACE_AGENT_URL is the fully qualified domain name of the pprof-agent profiling receiver, and the reporting path for the Profiler is {DD_TRACE_AGENT_URL}/profiling/v1/input. This address supports cross-namespace access, which allows the application and the receiver to communicate even if they are in different namespaces.
Sampling dimension switches
Variable | Description | Default |
| Memory allocation sampling | Enabled ( |
| Exception sampling (call stacks when exceptions are thrown) | Enabled |
| Exception sampling interval (sample once every N exceptions). Higher values reduce overhead. |
|
| Timeline (events arranged by time, including GC/IO) | Recommended: explicitly set to |
CPU and wall time are basic dimensions that are enabled together with the DD_PROFILING_ENABLED master switch. No separate configuration is required.
Upload and debugging
Variable | Description | Default |
| Upload interval in seconds. Shorter intervals make data visible sooner. |
|
| Profiler log level: |
|
| Tracing switch. Set to |
|
Profiling and tracing are independent. Profiling continues to work when DD_TRACE_ENABLED=false.
Complete example
The following example shows a Kubernetes environment variable configuration that enables profiling only:
env:
- { name: DD_PROFILING_ENABLED, value: "1" }
- { name: DD_SERVICE, value: "my-php-app" }
- { name: DD_ENV, value: "prod" }
- { name: DD_VERSION, value: "1.0.0" }
- { name: DD_TRACE_AGENT_URL, value: "http://arms-obi-pprof-agent-receiver.obi-system.svc:8126" }
- { name: DD_PROFILING_ALLOCATION_ENABLED, value: "1" }
- { name: DD_PROFILING_UPLOAD_PERIOD, value: "15" }
- { name: DD_PROFILING_LOG_LEVEL, value: "info" }
- { name: DD_TRACE_ENABLED, value: "false" }FAQs
Symptom | Cause and resolution |
| The |
Installed but no data received | php-fpm does not have |
Profiler log reports connection failure | Run |
Data does not appear in time | Wait for one |
Startup hangs while downloading the installation package | Slow network access to GitHub. Pre-install dd-trace-php in the container image instead. |