cAdvisor: a per-container metrics daemon you run next to your workloads

What cAdvisor answers that a host-level agent cannot

A node exporter tells you the machine is busy. It does not tell you which container is busy, how much of its memory limit it has consumed, or whether it is being throttled. cAdvisor exists to close that gap. The README describes it as "a running daemon that collects, aggregates, processes, and exports information about running containers," and for each container it keeps resource isolation parameters, historical resource usage, histograms of complete historical resource usage, and network statistics. That list matters because the four items are not the same kind of data. Isolation parameters are configuration (limits, shares, cgroup settings). Usage is a counter. Histograms are derived distributions. Network statistics come from a different kernel subsystem entirely.

The intended audience is narrow and specific. If you operate a container host, a Kubernetes node, or a fleet of either, and you want to know what a single container did over the last hour, cAdvisor is built for that question. If you run one long-lived process per virtual machine with no container runtime, the daemon has almost nothing to observe and you should use a host metrics agent instead.

The daemon reads the host, then republishes what it read

cAdvisor is not an agent you instrument your application with. It observes from outside. The Docker quick start in the README shows the mechanism directly: the container is given read-only bind mounts of /, /var/run, /sys, /var/lib/docker and /dev/disk, plus /dev/kmsg as a device. Those mounts are the data sources. /sys exposes cgroup and kernel state, /var/lib/docker holds Docker's own state directory, /var/run carries runtime sockets, and /dev/kmsg is the kernel ring buffer used for OOM and similar events.

The container abstraction is hierarchical. The README states it is based on lmctfy's abstraction, so "containers are inherently nested hierarchically." In practice that means a parent container's numbers can include its children, which is convenient for a pod and confusing if you assumed every series was flat. The go.mod file confirms which runtimes the code actually talks to: github.com/moby/moby/client and github.com/moby/moby/api for Docker, github.com/containerd/containerd/api for containerd, github.com/opencontainers/runc and github.com/opencontainers/runtime-spec for OCI, and github.com/opencontainers/cgroups for cgroup handling. There are also collectors for ZFS (github.com/mistifyio/go-zfs) and device mapper, and the repository has top-level directories named zfs/, devicemapper/, resctrl/, nvm/ and perf/, which tells you the storage and hardware coverage is broader than the Docker path alone.

Output leaves the daemon by two routes. A versioned remote REST API exposes raw and processed stats, and there is an official Go client in the client/ directory. Separately, storage plugins can export stats to other systems, documented under docs/storage/.

Installing cAdvisor with Docker and reading the first numbers

The README's quick start is the shortest path. It pins a version, mounts the host paths read-only, publishes port 8080, and runs privileged. Note the image registry change: the README says to use ghcr.io/google/cadvisor for current versions, and gcr.io/cadvisor/cadvisor only for versions prior to v0.53.0.

VERSION=0.55.1 # use the latest release version from https://github.com/google/cadvisor/releases
sudo docker run \
  --volume=/:/rootfs:ro \
  --volume=/var/run:/var/run:ro \
  --volume=/sys:/sys:ro \
  --volume=/var/lib/docker/:/var/lib/docker:ro \
  --volume=/dev/disk/:/dev/disk:ro \
  --publish=8080:8080 \
  --detach=true \
  --name=cadvisor \
  --privileged \
  --device=/dev/kmsg \
  ghcr.io/google/cadvisor:$VERSION

After this returns, the README states cAdvisor is running in the background on http://localhost:8080. Open that URL and you get the web UI, documented in docs/web.md. The same port serves the REST API described in docs/api.md, so you can query a container's stats without the UI once you know the path you want.

If you would rather not run it in a container, the README points to docs/running.md for standalone instructions and notes that CentOS, Fedora, RHEL and LXC users should read that page rather than the quick start. Advanced flags live in docs/runtime_options.md. Kubernetes users get a daemonset under deploy/kubernetes, which the README says can be customized with kustomize.

Privileged host mounts are the price of admission

The quick start runs the container with --privileged and mounts the entire host root filesystem at /rootfs. That is a large amount of trust to hand a monitoring daemon. The mounts are read-only, which limits the blast radius, but privileged mode is privileged mode. On a shared or multi-tenant host this is a decision you should make deliberately rather than copy from a README block.

The second constraint is that cAdvisor reports what the kernel and runtime expose, nothing more. It does not instrument your code, so it cannot tell you which function allocated the memory or which request blocked. It also cannot see a container that its collector does not understand. The README says cAdvisor "has native support for Docker containers and should support just about any other container type out of the box," and invites issues where that is not the case. That sentence is a support aspiration, not a guarantee. The dependencies name Docker, containerd and OCI runtimes; if you run something further from that lineage, treat support as something to verify on your own nodes before you depend on it.

The third constraint is retention. cAdvisor keeps historical usage and histograms in memory for the lifetime of the daemon. It is a source, not a time-series database. Restart the daemon and the history it accumulated is gone unless something scraped it in the meantime. There is no documented rollback procedure for a bad upgrade either; the README is silent on that.

Where cAdvisor sits next to Prometheus and node-level collectors

The most common pairing is cAdvisor as a scrape target behind Prometheus, which is why so many people search for cadvisor prometheus and cadvisor grafana dashboard. The division of labour is clean: cAdvisor produces per-container series, Prometheus stores and queries them over time, and Grafana draws them. cAdvisor itself does not store long-term data, does not alert, and does not render dashboards beyond its own web UI.

The real alternative to compare it against is a host-level metrics agent such as node_exporter. The difference is the unit of observation. node_exporter reports on the machine: CPU, memory, disks, network interfaces. cAdvisor reports on containers, with the cgroup hierarchy as the organizing structure. If you want to know that a node is at 90 percent memory, node_exporter answers it. If you want to know which container on that node is responsible, you need cAdvisor, or a runtime-specific metrics endpoint. Many deployments run both, because the two answer different questions and neither substitutes for the other.

A second alternative is your container runtime's own metrics endpoint. containerd and Docker expose some runtime metrics directly. The trade-off is coverage: a runtime endpoint generally describes the runtime, while cAdvisor's stated goal is the container's resource usage and performance characteristics, including filesystem and network statistics and histograms. If you only need runtime health, the runtime endpoint may be enough and you avoid the privileged mounts. If you need per-container resource history, cAdvisor is the broader source.

Building, testing and the cost of staying current

cAdvisor is written in Go and go.mod declares go 1.25.0. The Makefile defines the targets you would actually run. make all runs presubmit, build and test. The test target lists every package except integration and runs the race detector by default through GO_TEST ?= $(GO) test $(or $(GO_FLAGS),-race), then runs the cmd and lib trees separately. Integration tests are a different path: make test-integration builds with build/build.sh, compiles the integration test binaries for the api, common and metrics packages, and runs build/integration.sh. There are also CRI-O variants (test-integration-crio) and container-based runs (container-test, docker-test-integration).

The Makefile also pins GOLANGCI_VER := 2.6.2, so lint behaviour is tied to that version. If you vendor this project or build it in CI, expect the toolchain version to matter. The release cadence visible in the repository is rapid: v0.60.4, v0.60.5 and v0.60.6 all landed within roughly two months, with the newest tagged on 2026-09-18 and the last push to master on the same day. Upgrading is cheap if you run the published image and pin the tag, and expensive if you have forked or patched the collector layer, because the collector/, container/ and fs/ directories are where runtime and filesystem behaviour lives.

On licensing: the repository metadata reports the licence as NOASSERTION, meaning GitHub could not classify the LICENSE file automatically. The source file headers in the Makefile carry the Apache License, Version 2.0 notice. Read the LICENSE file in the repository root yourself and have your own counsel review it if the distinction matters to your distribution model; nothing here is legal advice.

Editorial conclusion

Adopt cAdvisor when you need per-container CPU, memory, filesystem and network numbers from a host and you already have a Prometheus-compatible scraper to store them. Skip it if you need application-level tracing, log aggregation, or anything that works without privileged host mounts, because the documented Docker quick start requires --privileged and read-only bind mounts of /, /var/run, /sys, /var/lib/docker and /dev/disk. Before rolling it out, verify which cgroup version your nodes use and confirm that your container runtime is one the collector actually reads, since the README claims broad support while the dependency list names Docker, containerd, runc and cgroups specifically.

Frequently asked questions

Official sources

1. google/cadvisor on GitHub
2. Issues
3. README
4. Releases