docker-exporter

Prerequisites

• Go

Installation

Using Docker

The exporter is available as a Docker image. You can run it using the following example:

$ docker run \
  -u root \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 8080:8080 \
  ghcr.io/davidborzek/docker-exporter:latest

Note: To run Docker Exporter, you'll need to mount the Docker socket from your host system. This operation necessitates root privileges or the user running the command to be a member of the Docker group. It's important to note that mounting the Docker socket grants the container unrestricted access to Docker. For a more secure approach, consider utilizing the Docker Socket Proxy, which is further explained below for additional information.

Running with docker-socket-proxy

$ docker run \
  -e "DOCKER_HOST=tcp://localhost:2375" \
  -p 8080:8080 \
  ghcr.io/davidborzek/docker-exporter:latest

Note: the docker-socket-proxy needs to have container access enabled. (CONTAINERS=1)

Prometheus config

Once you have configured the exporter, update your prometheus.yml scrape config:

scrape_configs:
  - job_name: "docker_exporter"
    static_configs:
      - targets: ["localhost:8080"]

Config

Exported Metrics

Ignoring Containers

You can ignore containers by setting the label docker-exporter.ignore on the container. The label name can be configured with the --ignore-label flag.

services:
  nginx:
    image: nginx
    labels:
      docker-exporter.ignore: "true"

Exposing Container Labels

By default no container labels are exported. Selected labels are exposed on a dedicated docker_container_labels metric (value 1), following the kube_pod_labels convention: the Docker label key is prefixed with container_label_ and any character outside [a-zA-Z0-9_] becomes _. A series only carries the selected labels a container actually sets — absent labels are omitted, not exported empty.

There are two ways to select labels, and they combine (union):

1. Globally, for every container, via the --container-label flag (repeatable) or a comma-separated DOCKER_EXPORTER_CONTAINER_LABELS environment variable:

   $ docker-exporter --container-label com.docker.compose.project --container-label maintainer
   

2. Per container, by setting the docker-exporter.exposed-labels label to a comma-separated list of that container's own label keys to expose:

   services:
     web:
       image: nginx
       labels:
         docker-exporter.exposed-labels: "com.docker.compose.project,maintainer"
   

Either way the result is the same metric:

docker_container_labels{name="web",container_label_com_docker_compose_project="shop",container_label_maintainer="acme"} 1

Join labels onto other metrics in PromQL via the container name:

docker_container_cpu_usage_percentage
  * on(name) group_left(container_label_com_docker_compose_project) docker_container_labels

Exporting all labels is intentionally not offered. Labels are selected by an explicit allowlist to keep metric cardinality bounded — note the per-container option delegates that choice to whoever can set container labels.

Contributing

Contributions are welcome — see CONTRIBUTING.md for the development workflow and release process, SECURITY.md for reporting vulnerabilities, and CODE_OF_CONDUCT.md. Notable changes are tracked in CHANGELOG.md.

License

MIT