Datadog PHP APM integration

This integration lets you reuse your existing Datadog PHP APM instrumentation and forward the same traces, logs and profiling data into Middleware.

What it does

  • Your PHP application is instrumented using the Datadog PHP tracer (dd-trace-php)
  • The tracer sends APM data to the Middleware Host Agent using the Datadog APM protocol on port 8126
  • The Middleware Host Agent exposes a Datadog-compatible receiver, converts the data, and forwards it to the Middleware backend
  • You can then explore traces in Middleware alongside other services and infrastructure.

How it works

Middleware does not replace your Datadog PHP tracer. Instead, it relies on Datadog's tracing library to generate spans inside your PHP runtime, then points that tracer to the Middleware Host Agent.

The PHP tracer:

  • Instruments common PHP frameworks and libraries automatically
  • Measures request latency, throughput and errors per endpoint
  • Captures context like HTTP URLs, status codes, database queries and unhandled exceptions

By enabling the Datadog receiver in the Middleware Host Agent, the agent listens on a Datadog-compatible port and accepts traces and optional profiling data from your PHP application. From there, the data behaves like native APM telemetry inside the Middleware.

Prerequisites

Before you start, make sure the following are in place:

1 Middleware Host Agent

  • The Middleware Host Agent must be installed and running on the same machine as your PHP application, or reachable from it.
  • If not installed, follow the Host Agent installation guide and pick the correct installer for your environment.

2 Network connectivity

  • The PHP application must reach the Middleware Host Agent on port 8126.
  • For non-container workloads, this is usually http://localhost:8126.
  • For container workloads, the agent is usually reachable at the Docker host IP or a Kubernetes service, which you will configure through MW_AGENT_SERVICE.

3 Supported PHP environment

  • A supported PHP version (PHP version 7 and newer)
  • Web server or runtime such as Apache, PHP-FPM, Nginx with PHP-FPM, or PHP CLI server.

Installation

1 Ensure the Middleware Host Agent is reachable

Install and run the Middleware Host Agent on the same machine that hosts your PHP application.

If you are running your application in a containerized environment, you must expose the agent to the container and set MW_AGENT_SERVICE so the application can resolve the agent:

Docker
Kubernetes
1MW_AGENT_SERVICE=172.17.0.1
1MW_AGENT_SERVICE=mw-service.mw-agent-ns.svc.cluster.local

Use the value that matches how you deployed the Middleware Host Agent in your cluster or host. You will pass this environment variable into your container or deployment spec so that the PHP runtime can route traces to the Host Agent.

2 Download the Datadog PHP APM installer

Download the latest Datadog PHP tracer installer directly from GitHub:

1curl -LO https://github.com/DataDog/dd-trace-php/releases/latest/download/datadog-setup.php

Tip: Commit the script or a pinned version of it to your deployment pipeline if you want a reproducible tracer version across environments.

3 Run the installer

Run the installer so it detects all available PHP binaries on the host and configures the tracer for each of them:

1sudo php datadog-setup.php --php-bin=all

What this does:

  • Detects PHP installations such as Apache PHP module, PHP-FPM, CLI binaries
  • Installs the Datadog tracer extension and required configuration snippets
  • Prepares the runtime so that future requests are traced automatically once you set the environment variables

4 Configure Datadog tracer environment variables

You now need to configure environment variables so the Datadog tracer knows:

  • Which logical service name to use
  • Where to send traces, which in this case is the Middleware Host Agent Datadog receiver at http://localhost:8126 or http://$MW_AGENT_SERVICE:8126
Apache with PHP-FPM
Apache without PHP-FPM
PHP CLI

For Apache with PHP-FPM, use the env[] directive in your www.conf pool configuration:

1env[DD_SERVICE] = <service-name>
2env[DD_TRACE_AGENT_URL] = "http://localhost:8126"

Replace <service-name> with a meaningful name such as checkout-service or billing-api. This name will appear as the service name in Middleware.

If the agent is not on local loopback inside your PHP container, use the MW_AGENT_SERVICE host:

1env[DD_SERVICE] = <service-name>
2env[DD_TRACE_AGENT_URL] = "http://mw-service.mw-agent-ns.svc.cluster.local:8126"

If PHP runs directly inside Apache, you can configure environment variables at server, virtual host, or directory level, including .htaccess, using SetEnv:

1SetEnv DD_SERVICE <service-name>
2SetEnv DD_TRACE_AGENT_URL http://localhost:8126

Again, change the URL if your Middleware Host Agent runs on a different host or service name.

For built-in PHP server, CLI scripts or artisan style commands, you can set environment variables inline:

1DD_TRACE_DEBUG=1 DD_SERVICE=<service-name> DD_TRACE_AGENT_URL=http://localhost:8126 php -S localhost:8888

DD_TRACE_DEBUG=1 enables verbose tracer logs which are useful while validating the integration. Turn this off in production for lower log noise.

Optional tagging for environments and versions

Datadog's PHP tracer supports additional environment variables like DD_ENV and DD_VERSION that help you filter traces by environment and application version.

You can optionally set these to improve how Middleware groups and filters your traces:

1DD_ENV=production
2DD_VERSION=1.3.2
3DD_SERVICE=<service-name>
4DD_TRACE_AGENT_URL=http://localhost:8126

Middleware will receive these tags, and you can use them to separate staging and production services, or to compare performance across releases.

Restart services after installation

After the installer completes, restart your PHP runtime:

  • For Apache with the PHP module: restart Apache
  • For PHP-FPM: restart the PHP-FPM service and reload the web server
  • For other servers, restart the relevant process so the new PHP configuration is loaded.

5 Enable the Datadog receiver in the Middleware Host Agent

The Middleware Host Agent must be configured to accept Datadog-formatted traces. This is controlled by the Datadog receiver configuration.

You can enable it in two ways.

Environment Variable
Configuration File

Enable through environment variable at install time

When installing the agent, pass the following environment variable so the Datadog receiver is enabled from the start:

1MW_ENABLE_DATADOG_RECEIVER=true

Follow the standard Host Agent installation reference for all supported flags and examples.

Enable through agent-config.yaml after installation

If the agent is already installed, edit the configuration file and append the Datadog receiver setting.

  • On Unix-based systems: /etc/mw-agent/agent-config.yaml
  • On Windows systems: agent-installation-directory\agent-config.yaml

Add or update the following line:

1enable-datadog-receiver: true

Save the file and restart the agent:

1sudo systemctl restart mw-agent

After the restart, the agent listens for Datadog APM traffic on its configured Datadog receiver port, usually 8126.

Troubleshooting

No traces appear in Middleware

  • Confirm enable-datadog-receiver: true is present in agent-config.yaml and the agent is restarted.
  • Check that DD_TRACE_AGENT_URL points to the Middleware Host Agent and not to a Datadog Agent running elsewhere.
  • Verify there are no firewalls or network policies blocking port 8126.
  • Enable DD_TRACE_DEBUG=1 temporarily and inspect application logs for tracer errors.

Wrong or missing service name

  • Confirm DD_SERVICE is set for the runtime that actually serves traffic.
  • For Apache with PHP-FPM, make sure env[] directives are defined in the correct pool configuration and the pool was reloaded.
  • For Apache without PHP-FPM, verify SetEnv is not overridden in a deeper .htaccess or virtual host.

PHP process not instrumented

  • Run php -i | grep ddtrace or check the PHP info page to confirm the ddtrace extension is loaded.
  • Ensure the Datadog installer was run with the --php-bin=all flag if you have multiple PHP binaries.

CLI scripts not traced

  • CLI scripts require the same environment variables as web requests.
  • When running scheduled jobs or workers, set DD_SERVICE, DD_TRACE_AGENT_URL and other tags in the environment of the scheduler or worker process.

Need assistance or want to learn more about Middleware? Contact our support team at [email protected] or join our Slack channel.