Docker State Exporter

Exporter for docker container state

Prometheus exporter for docker container state, written in Go.

One of the best known exporters of docker container information is cAdvisor.
However, cAdvisor does not export the state of the container.

This exporter will only export the container status and the restarts count.

Installation and Usage

The docker_state_exporter listens on HTTP port 8080 by default.

Docker

For Docker run.

sudo docker run -d \
  -v "/var/run/docker.sock:/var/run/docker.sock" \
  -p 8080:8080 \
  $REPO/docker_state_exporter \
  -listen-address=:8080

For Docker compose.

---
version: '3.8'

services:
  docker_state_exporter:
    image: $REPO/docker_state_exporter
    volumes:
      - type: bind
        source: /var/run/docker.sock
        target: /var/run/docker.sock
    ports:
      - "8080:8080"

Metrics

This exporter will export the following metrics.

• container_state_health_status
• container_state_status
• container_state_oomkilled
• container_state_startedat
• container_state_finishedat
• container_restartcount

These metrics will be the same as the results of docker inspect.

This exporter also exports the standard Go Collector and Process Collector.

API Documentation

docker_state_exporter

import "github.com/AdaptiveConsulting/docker_state_exporter"

Package main implements a Docker state exporter for Prometheus metrics.

This exporter connects to the Docker daemon and exports container state information as Prometheus metrics, including health status, running state, OOM killed status, and restart counts.

The exporter provides the following metrics:

• container_state_health_status: Container health status (none, starting, healthy, unhealthy)
• container_state_status: Container status (paused, restarting, running, removing, dead, created, exited)
• container_state_oomkilled: Whether the container was killed by OOMKiller
• container_state_startedat: Unix timestamp when the container started
• container_state_finishedat: Unix timestamp when the container finished
• container_restartcount: Number of times the container has been restarted

Usage:

docker_state_exporter [flags]

Flags:

-listen-address string
    The address to listen on for HTTP requests (default ":8080")
-add-container-labels
    Add labels from docker containers as metric labels (default true)
-cache-period int
    The period of time the collector will reuse the results of docker inspect
    before polling again, in seconds (default 1)

Examples:

# Start the exporter on default port 8080
docker_state_exporter

# Start on custom port with 5-second cache
docker_state_exporter -listen-address=:9090 -cache-period=5

# Start without container labels
docker_state_exporter -add-container-labels=false

The exporter exposes metrics at /metrics and provides a health check at /-/healthy.

Index

• Variables
• func errCheck(err error)
• func init()
• func main()
• type descSource
  • func (desc *descSource) Desc(labels prometheus.Labels) *prometheus.Desc
• type dockerHealthCollector
  • func (c *dockerHealthCollector) Collect(ch chan<- prometheus.Metric)
  • func (c *dockerHealthCollector) Describe(ch chan<- *prometheus.Desc)
  • func (c *dockerHealthCollector) collectContainer()
  • func (c *dockerHealthCollector) collectMetrics(ch chan<- prometheus.Metric)
• type loggerWrapper
  • func (l *loggerWrapper) Println(v ...interface{})

Variables

var (
    // addContainerLabels controls whether to include Docker container labels as Prometheus metric labels.
    // When enabled, all labels from the container will be added to the metrics with a "container_label_" prefix.
    addContainerLabels bool

    // cachePeriod defines how long to cache Docker inspect results before polling again.
    // This reduces the load on the Docker API while maintaining reasonable freshness of data.
    cachePeriod time.Duration
)

var (
    namespace        = "container_state_"
    healthStatusDesc = descSource{
        namespace + "health_status",
        "Container health status."}
    statusDesc = descSource{
        namespace + "status",
        "Container status."}
    oomkilledDesc = descSource{
        namespace + "oomkilled",
        "Container was killed by OOMKiller."}
    startedatDesc = descSource{
        namespace + "startedat",
        "Time when the Container started."}
    finishedatDesc = descSource{
        namespace + "finishedat",
        "Time when the Container finished."}
    restartcountDesc = descSource{
        "container_restartcount",
        "Number of times the container has been restarted"}
)

Define loggers.

var (
    normalLogger = log.NewJSONLogger(log.NewSyncWriter(os.Stdout))
    errorLogger  = log.NewJSONLogger(log.NewSyncWriter(os.Stderr))
)

Define flags.

var (
    address = flag.String(
        "listen-address",
        ":8080",
        "The address to listen on for HTTP requests.",
    )
)

func errCheck

func errCheck(err error)

func init

func init()

func main

func main()

type descSource

descSource provides a helper for creating Prometheus metric descriptions with consistent naming and help text.

type descSource struct {
    name string // Metric name
    help string // Help text describing the metric
}

func (*descSource) Desc

func (desc *descSource) Desc(labels prometheus.Labels) *prometheus.Desc

Desc creates a Prometheus metric description with the given labels. It returns a new prometheus.Desc that can be used to create metrics.

type dockerHealthCollector

dockerHealthCollector implements the prometheus.Collector interface to collect Docker container state metrics. It caches container information for a configurable period to reduce Docker API calls while maintaining reasonable freshness of data.

The collector exports metrics about container health status, running state, OOM kill status, start/finish times, and restart counts.

type dockerHealthCollector struct {
    mu                 sync.Mutex                  // Protects concurrent access to cache
    containerClient    *client.Client              // Docker client for API calls
    containerInfoCache []container.InspectResponse // Cached container information
    lastseen           time.Time                   // Last time cache was refreshed
}

func (*dockerHealthCollector) Collect

func (c *dockerHealthCollector) Collect(ch chan<- prometheus.Metric)

Collect is called by Prometheus when collecting metrics. It fetches current container state (using cache if fresh enough) and sends metrics to the channel.

func (*dockerHealthCollector) Describe

func (c *dockerHealthCollector) Describe(ch chan<- *prometheus.Desc)

Describe sends the super-set of all possible descriptors of metrics collected by this Collector to the provided channel and returns once the last descriptor has been sent.

func (*dockerHealthCollector) collectContainer

func (c *dockerHealthCollector) collectContainer()

func (*dockerHealthCollector) collectMetrics

func (c *dockerHealthCollector) collectMetrics(ch chan<- prometheus.Metric)

type loggerWrapper

type loggerWrapper struct {
    Logger *log.Logger
}

func (*loggerWrapper) Println

func (l *loggerWrapper) Println(v ...interface{})

Generated by gomarkdoc

Performance

The polling of docker inspect commands is set to every one second.

TODO: Allow for polling interval customization.

Build the go binary and container

git clone https://github.com/AdaptiveConsulting/docker_state_exporter
cd docker_state_exporter
docker build . -t docker_state_exporter_test

Run

sudo docker run -d \
  -v "/var/run/docker.sock:/var/run/docker.sock" \
  -p 8080:8080 \
  docker_state_exporter_test \
  -listen-address=:8080