PHP continuous profiling

Updated at:

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.

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

  2. In the left-side navigation pane, click Components and Add-ons. Find the arms-obi add-on and install it. Set installMode to profiling.

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-profiling
Note

The --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 = no
Note

This 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

DD_PROFILING_ENABLED

Profiling master switch (0/1). If disabled, no data is collected.

1

DD_SERVICE

Service name used to identify different applications.

Your service name

DD_ENV

Environment tag (prod/staging...)

prod

DD_VERSION

Version tag

1.0.0

DD_TRACE_AGENT_URL

Receiver address. The profiler reports data to {DD_TRACE_AGENT_URL}/profiling/v1/input. Use the fully qualified service name so that cross-namespace access works.

http://arms-obi-pprof-agent-receiver.obi-system.svc:8126

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

DD_PROFILING_ALLOCATION_ENABLED

Memory allocation sampling

Enabled (1)

DD_PROFILING_EXCEPTION_ENABLED

Exception sampling (call stacks when exceptions are thrown)

Enabled

DD_PROFILING_EXCEPTION_SAMPLING_DISTANCE

Exception sampling interval (sample once every N exceptions). Higher values reduce overhead.

100

DD_PROFILING_TIMELINE_ENABLED

Timeline (events arranged by time, including GC/IO)

Recommended: explicitly set to 1

Note

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

DD_PROFILING_UPLOAD_PERIOD

Upload interval in seconds. Shorter intervals make data visible sooner.

60 (can be reduced to 15 during verification)

DD_PROFILING_LOG_LEVEL

Profiler log level: off/error/warn/info/debug

off

DD_TRACE_ENABLED

Tracing switch. Set to false if you only need profiling without tracing.

true

Note

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

php -m does not show datadog

The --enable-profiling flag was omitted during installation, or the installation failed.

Installed but no data received

php-fpm does not have clear_env = no set (environment variables cannot reach worker processes). This is the most common cause.

Profiler log reports connection failure

Run curl http://arms-obi-pprof-agent-receiver.obi-system.svc:8126/info to test connectivity.

Data does not appear in time

Wait for one DD_PROFILING_UPLOAD_PERIOD cycle. Reduce the value to 15 during verification.

Startup hangs while downloading the installation package

Slow network access to GitHub. Pre-install dd-trace-php in the container image instead.