Monitoring your PHP applications in Kubernetes becomes effortless when you pair the Datadog Agent with the PHP tracer. Whether you're debugging performance issues or collecting logs for deeper visibility, Datadog provides powerful features like distributed tracing, error tracking, and real-time log aggregation.

In this post, we'll walk through how to:
- Install the Datadog PHP tracer
- Deploy the Datadog Agent with APM and log collection enabled
- Use Kubernetes annotations to auto-discover and monitor your PHP pods

🐘 Step 1: Install Datadog PHP Tracer in Dockerfile

To instrument your PHP application with Datadog APM, install the tracer in your Dockerfile using the official setup script:

# Datadog APM
RUN curl -LO https://github.com/DataDog/dd-trace-php/releases/latest/download/datadog-setup.php && \
    php datadog-setup.php --php-bin=all

🐶 Step 2: Configure the Datadog Agent with APM and Logs

Deploy the Datadog Agent in your Kubernetes cluster using Helm, with both APM (traces) and logs enabled.

Here’s a sample snippet for your values.yaml file:

datadog:
  apiKeyExistingSecret: "<YOUR_K8S_SECRET_NAME>"
  site: "us5.datadoghq.com"

  apm:
    portEnabled: true
    port: 8126

  logs:
    enabled: true
    containerCollectAll: true

📌 What this does:
- apm.portEnabled: Enables trace collection on port 8126.
- logs.enabled: Enables log collection from your containers.
- containerCollectAll: true: Automatically collects logs from all containers.

🔐 If you’re deploying this via GitHub Actions, store your Datadog API key in GitHub Secrets (e.g., DATADOG_API_KEY). Then, create a Kubernetes secret like this:

kubectl create secret generic datadog-secret \
  --from-literal=api-key=$secrets.DATADOG_API_KEY

Use apiKeyExistingSecret: "datadog-secret" in your Helm config.

🧾 Step 3: Add Annotations for Auto-Discovery

Add the following annotations to your PHP deployment YAML (or Helm template):

annotations:
  ad.datadoghq.com/legacy.logs: '[{"source":"legacy","service":"legacy"}]'
  ad.datadoghq.com/legacy.checks: '{"http_check":{"instances":[{"name":"Legacy App","url":"http://localhost:80/health","timeout":1}]}}'
  ad.datadoghq.com/legacy.version: "1.0.0"

📘 These annotations:
- Enable log collection for the pod
- Define a basic HTTP health check
- Tag the app version for trace correlation

You can replace legacy with your actual service name.

✅ Final Check: Validate in Datadog

Once deployed:
1. Send some traffic to your PHP app.
2. Visit APM → Services in Datadog to view trace data.
3. Check Logs → Live Tail to verify logs from the PHP container are flowing in.

🚀 Wrapping Up

With just a few lines in your Dockerfile and Helm chart, you’ve enabled full-stack observability for your PHP application:
- ✅ Automatic tracing via Datadog PHP tracer
- ✅ APM enabled with service-level insights
- ✅ Container log collection with contextual metadata
- ✅ Health checks and version tagging via annotations

🧠 Pro Tip: Use DD_ENV, DD_SERVICE, and DD_VERSION environment variables to add context to your traces. It helps filter and analyze services by environment and release version.

🔗 References

For more detailed information, refer to the official Datadog documentation:
- PHP Tracer Instrumentation
- Agent Installation & Configuration