OOM Kill: Docker documentation missing `CAP_PERFMON` capability for Linux Kernel >= 5.8

[colinbjohnson]

Current State

The OOM Kill README states, under "Configuration with Docker":

From kernel version 5.8, the --privileged parameter can be replaced by --cap-add CAP_BPF.

This is incomplete. CAP_BPF alone is insufficient to run the OOM Kill check.

Reproducible Steps

Run the datadog-agent container on a Linux host with kernel >= 5.8 following the documented Docker configuration and using CAP_BPF in place of --privileged:

docker run \
  --name datadog-agent \
  --cap-add CAP_BPF \
  -v /sys/kernel/debug:/sys/kernel/debug \
  -v /lib/modules:/lib/modules \
  -v /usr/src:/usr/src \
  -e DD_API_KEY=<DD_API_KEY> \
  -e DD_HOSTNAME=test-oom-kill \
  -e DD_SYSTEM_PROBE_ENABLED=true \
  -e DD_SYSTEM_PROBE_CONFIG_ENABLE_OOM_KILL=true \
  public.ecr.aws/datadog/agent:latest

Observed result: The following error appears in the agent logs:

2026-06-16 05:19:57 UTC | CORE | ERROR | (pkg/collector/worker/check_logger.go:71 in Error) | check:oom_kill | Error running check: non-ok status code: url http://sysprobe/oom_kill_probe/check, status_code: 404, response: `404 page not found`

Why this happens: On kernel >= 5.8, CAP_SYS_ADMIN was split into more granular capabilities. Loading an eBPF program requires CAP_BPF, but attaching a kprobe (which oom_kill_probe does via kprobe/oom_kill_process) additionally requires CAP_PERFMON. With only CAP_BPF, the probe fails to attach, system-probe skips registering the /oom_kill_probe/check HTTP route entirely, and the agent check receives a 404.

Desired State

The documentation should reflect that both capabilities are required on kernel >= 5.8:

docker run \
  --name datadog-agent \
  --cap-add CAP_BPF \
  --cap-add CAP_PERFMON \
  -v /sys/kernel/debug:/sys/kernel/debug \
  -v /lib/modules:/lib/modules \
  -v /usr/src:/usr/src \
  -e DD_API_KEY=<DD_API_KEY> \
  -e DD_HOSTNAME=test-oom-kill \
  -e DD_SYSTEM_PROBE_ENABLED=true \
  -e DD_SYSTEM_PROBE_CONFIG_ENABLE_OOM_KILL=true \
  public.ecr.aws/datadog/agent:latest

The corrected note in the README should read:

From kernel version 5.8, the --privileged parameter can be replaced by --cap-add CAP_BPF --cap-add CAP_PERFMON.

Test Results

With the latter configuration OOM Kill events and metrics will be sent to datadog. This can be tested by running a command such as stress-ng --vm 2 --vm-bytes 1900m --timeout 120