Docker

The Docker integration requires CXDOT Collector 1.4.0 or greater. Docker is a platform for building and running applications in containers. Use the Docker integration with the Chronosphere XDOT Collector to collect per-container resource metrics and container counts from Docker daemons running in your environment. The Docker integration supports Docker Engine 29.0 or greater.

​

Supported telemetry types

The Docker integration supports these telemetry types:

​

Prerequisites

The Docker integration has the following prerequisites:

• Run Docker Engine as the container runtime on the nodes you collect from. Most Kubernetes clusters run containerd instead, which exposes no Docker daemon for this integration to read. To confirm which runtime your nodes run, run the following command and read the CONTAINER-RUNTIME column:
  kubectl get nodes -o wide
  
• Run your nodes on Linux with cgroups v2, which most current distributions use. On a cgroups v1 node the integration still reports container and image counts and the per-container metrics the Docker daemon serves, but not the fields read from the node’s cgroup tree: block I/O operation counts, memory reclaim events, kernel and swap memory, and open file descriptors.
• Make the Docker daemon reachable from the Collector, either through the node’s Unix socket or over a TCP address the daemon listens on.

​

Configure

The Docker integration is disabled by default. To configure the Docker integration, follow these steps:

1. Enable the integration. For example, add the following to the values.yaml for your Helm chart:
   config:
     integrations:
       docker:
         enabled: true
   
   Each Collector reads the Docker daemon on its own node and reports the containers that daemon runs.
2. Allow the Collector to run as root. For example, add the following to the values.yaml for your Helm chart:
   nodeCollector:
     securityContext:
       runAsRoot: true
   
   runAsRoot is required for a Unix socket endpoint. runAsRoot is also required to emit container.open_file_descriptors. Leave collect_open_file_descriptors out of your values.yaml to keep the default, where the Collector reports the count when it can read it and skips it when it can’t. Writing collect_open_file_descriptors: true makes the metric a requirement instead: the chart then refuses to deploy unless the Collector runs as root and reads a daemon on its own node.
3. Optional: Collect from a daemon at another address, such as one that listens on a TCP port. For example, add the following to the values.yaml for your Helm chart:
   config:
     integrations:
       docker:
         enabled: true
         endpoint: tcp://127.0.0.1:2375
   
   Open file descriptors are counted on the node the Collector runs on, so a daemon at any address other than a Unix socket, localhost, or 127.0.0.1 reports no container.open_file_descriptors. Don’t set collect_open_file_descriptors: true for such an endpoint, because the chart then refuses to deploy.
4. Optional: Exclude the containers of images you don’t want reported, such as short-lived build agents. For example, add the following to the values.yaml for your Helm chart:
   config:
     integrations:
       docker:
         enabled: true
         excluded_images:
           - registry.example.com/build-agents/*
   

​

Validate

To validate the Docker integration, follow these steps:

1. In the Live Telemetry Analyzer, filter for __name__=cxdot.integration.target.health and cxdot.integration.name=docker. Confirm that the metric reports 1, meaning the Collector reached the daemon. The host.name attribute identifies which node’s daemon a reading describes.
2. In Metrics Explorer, run the following query:
   count by ("host.name") ({"container.cpu.utilization"})
   
   Confirm that the query returns one time series per node, each counting the containers running on that node.

​

Troubleshooting

• Every other metric arrives, but container.open_file_descriptors is missing: Descriptor counts come from each process’s own entry under /proc, on the node the containers run on, and only that process’s own user and root can read them. A Collector that doesn’t run as root reads none of them and reports no count for any container. A Collector reading a daemon on another host reports no count either, whatever it runs as, because the counts are on that host. For a daemon on the same node, set runAsRoot to true, as shown in Configure, or set collect_open_file_descriptors to false to stop collecting the metric.

For more information about diagnosing a failing integration, see Troubleshooting.

​

Configuration reference

Configure one Docker integration instance with the following settings. In Helm values, place these settings under config.integrations.docker. In a Collector configuration file, place them under cxdot.integrations.docker.

​

Optional settings

• enabled Type: boolean. Optional. Default: true. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn’t run it.
• endpoint Type: string. Optional. Default: unix:///var/run/docker.sock. The Docker daemon the Collector reads container stats from. Either a Unix socket such as unix:///var/run/docker.sock, or a TCP address such as tcp://host:2375. The default connects to the daemon on the node the Collector runs on: directly in host mode, and in Kubernetes because the Helm chart mounts that node’s socket into the Collector.
• api_version Type: string. Optional. Default: 1.44. Docker Engine API version the Collector negotiates with the daemon. Must be at least 1.44, the oldest version Docker Engine 29 accepts, and the daemon must still support it.
• excluded_images Type: array of string. Optional. Default: []. Images whose containers aren’t reported. Each entry is a literal name, a glob, or a /regex/.
• collection_interval Type: duration. Optional. Default: 10s. How often the Collector collects metrics from the Docker daemon.
• timeout Type: duration. Optional. Default: 10s. Maximum time the Collector waits for the Docker daemon to respond during one collection. This value must not exceed collection_interval. If the deadline expires, that collection fails.
• collect_open_file_descriptors Type: boolean. Optional. Default: true. Whether to collect container.open_file_descriptors, the number of file descriptors open across all of a container’s processes. If true, the Collector reports the metric. If false, it reports everything else and omits this one. The cost of this metric grows with the number of processes in the reported containers and the descriptors each has open, because every collection counts them again. Working out which container a process belongs to takes a read for every process on the node. That answer is cached and rechecked only every few dozen collections, so its cost is paid mostly on the first collection. Turning the metric off leaves every other field read under root_path collecting normally. The Collector can read descriptor counts only for a daemon on its own node, and only when it runs as root, because another user’s open descriptors are readable only by root. In Kubernetes, set nodeCollector.securityContext.runAsRoot in the Helm chart. Left unset, the setting takes its default without making the metric a requirement: a count the Collector can’t read is skipped, with a warning, rather than reported. Written out as true, it becomes a requirement: the Helm chart fails to render unless the daemon is on the same node as the Collector and runAsRoot is set.
• root_path Type: string. Optional. Root of the node file system when the Collector runs in a container with the node root bind-mounted, for example /hostfs. In Kubernetes the Helm chart mounts it and sets this value, so it rarely needs setting by hand. The Collector reads it for the per-container cgroup fields the Docker daemon’s stats API doesn’t report on cgroups v2: block I/O operation counts, memory reclaim events, kernel and swap memory, and open file descriptors. Those fields come from the node’s cgroup tree instead. In host mode against a daemon on the same node, meaning a Unix socket or a tcp:// endpoint on a loopback host such as 127.0.0.1 or localhost, the Collector runs on the node it reports on, so this value defaults to / and those fields are read from that node’s own /proc and /sys/fs/cgroup. It stays unset for a tcp:// endpoint naming another host, because these fields can’t be collected without access to that host’s file system. It also stays unset in node mode outside the Helm chart, where nothing mounts the node root or sets this value for you. When this value is unset, those fields aren’t collected. Set it to "" to switch the fields off where the default would otherwise apply.
• containers Type: object. Optional. Settings for Docker container metrics collection.
• containers.enabled Type: boolean. Optional. Default: true. Whether to enable this configuration block. If true, the Collector runs the integration or capability. If false, the Collector doesn’t run it.