Docker platform notes

How the agent runs in Docker mode. For installation, see the Docker installation guide.

What’s automatic

Running in Docker mode, the agent covers your host and containers without touching them:

Infrastructure, metrics, and logs: host and container metrics and container logs, from the containerized collector. See Host metrics and logs.

Container monitoring isn’t unique to Docker mode. A Linux agent on a Docker host collects the same per-container metrics and logs automatically, because it reads the host’s Docker socket. The section below covers when to pick each.

Docker mode vs the Linux agent

For monitoring containers, the two are equivalent. A Linux (systemd) agent on a Docker host and a containerized Docker-mode agent both collect container metrics and logs automatically, and both trace containers per service with eBPF (Off or eBPF). Pick between them by how you want to run the agent, not by what they can see:

Host processes. The Linux agent also instruments the host’s own non-containerized processes with the OpenTelemetry SDK, through systemd. A Docker-mode agent is itself a container, so it can’t do that, and the host’s processes are traced with eBPF only.
PHP containers. A PHP container can offer an SDK option that injects the tracer with no redeploy. That option is on by default in Docker mode. On the Linux agent it’s opt-in: set KM_CONTAINER_INSTRUMENT_ENABLED=true.
How the agent runs. Docker mode runs the agent as a container and needs the Docker socket mounted, plus a privileged container with host access for eBPF. The Linux agent runs as a systemd service on the host and already has that access.

Application traces

Application tracing (Rate, Errors, and Duration metrics and trace spans) is not automatic. The agent lists every host process and container it finds under Discovered Services, and for each one you choose how it’s traced:

Off: not traced. This is the default, so nothing is traced (and nothing costs) until you turn it on, which matters on a host running many containers.
eBPF: RED metrics and trace spans, captured in the host kernel with no code change and no restart.
SDK: offered for PHP containers. It injects the tracer and reloads the web server, so tracing starts with no redeploy and no container restart. See Instrument PHP containers.

The in-process OpenTelemetry SDK can’t be injected into a running container, because it reads its configuration from the process’s start-time environment, and that can’t change without recreating the container. So Java, Node.js, Python, .NET, and Go containers offer Off or eBPF only. For full SDK depth on those runtimes, add OpenTelemetry to the app yourself (below), or run it on a Linux host or Amazon ECS, where the agent injects it for you.

Runtime	In Discovered Services	Full SDK depth
Java, Node.js, Python, .NET	Off / eBPF: RED and spans, opt-in, no restart	Not injectable on Docker. Add OpenTelemetry yourself, or run on Linux or ECS.
Go	Off / eBPF	eBPF only. Go is a static binary with no runtime to attach.
PHP 7 and 8	Off / eBPF / SDK: SDK injects the tracer, no redeploy	Covered by the SDK option, no redeploy

Instrument PHP containers

A PHP container offers an SDK option in Discovered Services. Turn it on for a container and the agent injects the tracer, matches it to the container’s PHP build, and reloads the web server (an Apache graceful reload or a php-fpm reload). Tracing starts with no redeploy and no container restart.

The SDK option appears whenever the PHP-container instrumentation path is enabled. It’s on by default in Docker mode. On a Linux host agent it’s opt-in: set KM_CONTAINER_INSTRUMENT_ENABLED=true.

For automated or immutable deployments, instrument PHP containers without picking each one:

# Instrument every PHP container, with no per-service selection
KM_CONTAINER_INSTRUMENT_ALL=true

# Or restrict the automatic set to specific containers or images
KM_CONTAINER_INSTRUMENT_NAMES=app1,app2
KM_CONTAINER_INSTRUMENT_IMAGES=wordpress,my-php-app

# Turn the PHP-container SDK path off entirely
KM_CONTAINER_INSTRUMENT_ENABLED=false

What is supported

Web servers: Apache with mod_php, and PHP-FPM. The agent reloads them gracefully, so tracing starts without a restart. WordPress and the official php:8.x-apache images work this way.
PHP versions: 7.0 through 8.x. The tracer is matched to the container’s exact PHP build automatically.

The agent cannot instrument a container that serves requests from the PHP built-in server (php -S), because that server does not reload configuration without a full restart. The official Adminer image is one example. Alpine (musl) images are also a problem, because the bundled tracer assets target glibc.

How PHP-container tracing is selected

By default, a PHP container is traced when you set it to SDK in Discovered Services, the same per-service choice as any other service. The environment variables above override that for automated rollouts: KM_CONTAINER_INSTRUMENT_ALL, KM_CONTAINER_INSTRUMENT_NAMES, or KM_CONTAINER_INSTRUMENT_IMAGES instrument a fixed set with no UI step, and autonomous mode instruments every PHP container. Setting KM_CONTAINER_INSTRUMENT_ENABLED=false turns the SDK path off, so PHP containers fall back to Off or eBPF.

Send full OpenTelemetry traces from your containers

For Java, Node.js, Python, and .NET, eBPF (the per-service toggle above) already gives you RED metrics and spans with no code change. For full SDK depth — client spans, database and library instrumentation, custom spans — run OpenTelemetry inside the application. Add it once, at build or deploy time, and point it at the agent. The agent already listens for OpenTelemetry (OTLP) data:

gRPC on port 4317
HTTP on port 4318

1. Instrument the application. Add OpenTelemetry to the service, with either the language’s zero-code auto-instrumentation (the Java agent jar, the Node.js --require loader, and so on) or the OpenTelemetry SDK. These are the same language agents the agent adds automatically on a host, listed in the application APM overview.

2. Point it at the agent. Set these environment variables on the application container:

OTEL_EXPORTER_OTLP_ENDPOINT=http://AGENT_HOST:4318
OTEL_SERVICE_NAME=your-service-name

Replace AGENT_HOST with an address that reaches the agent from inside the container:

Docker Desktop (Mac or Windows): host.docker.internal.
Linux: the Docker bridge gateway, commonly 172.17.0.1. Or add --add-host=host.docker.internal:host-gateway to the application container and use host.docker.internal.
Same Docker network: if the agent runs as a service on the same user-defined network as the application, use its service name, for example http://kmagent:4317.

To send over HTTP instead of gRPC, use port 4318 and add OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.

3. Restart the service so the instrumentation loads. Its traces then appear in KloudMate, joined to the service’s eBPF spans on one trace.

The agent produces this same result automatically on a Linux host or on Amazon ECS. In plain Docker you add the instrumentation yourself, because the agent cannot change a running container’s startup environment without recreating it.

Deployment posture

PHP container instrumentation reaches the containers through the Docker socket, so it works from a host-process agent or from the containerized collector, as long as the socket is mounted.

eBPF monitoring is different: it needs host kernel access, so a plain, non-privileged agent container cannot produce the eBPF signals. Run the agent on the host, or as a privileged container with host mounts.

PHP 7 in containers

A tracer built on the host must match the container’s exact PHP build, so PHP 7 in a container is the hardest case. The reliable path is to add the tracer at image build time. See PHP instrumentation.

Next steps

Install with Docker Run the agent as a container.

eBPF observability Kernel-level monitoring that covers your containers.

Application APM overview How opt-in tracing works.