cAdvisor (Container Advisor)

Housekeeping refers to the periodic actions cAdvisor takes to gather container stats. You can control the frequency and behavior of these actions.

Dynamic Housekeeping:

• --allow_dynamic_housekeeping=true: Allows cAdvisor to vary the housekeeping interval based on container activity. Disabling this provides predictable intervals but increases resource usage.

Interval Settings:

• --global_housekeeping_interval=1m0s: Interval for global housekeeping (used for detecting new containers).
• --housekeeping_interval=1s: Interval for per-container housekeeping (used for gathering container stats).
• --max_housekeeping_interval=1m0s: The maximum allowed interval between container housekeepings.

cAdvisor provides a built-in web interface to visualize container resource usage. The UI is accessible at the hostname and port where cAdvisor is running:

http://<hostname>:<port>/

For more details on the interface, see docs/web.md.

cAdvisor uses Kustomize to manage Kubernetes manifests. You can deploy cAdvisor to your cluster using a remote build by pointing Kustomize to the official repository with a specific version tag.

Ensure you have Kustomize installed before proceeding.

VERSION=v0.42.0
kustomize build "https://github.com/google/cadvisor/deploy/kubernetes/base?ref=${VERSION}" | kubectl apply -f -

After building, you can run the cAdvisor binary using sudo.

If you built with Perf Support, you must provide a performance events configuration file using the -perf_events_config flag to enable performance monitoring.

# Standard run
$ sudo ./cadvisor

# Run with performance monitoring configuration
$ sudo ./cadvisor -perf_events_config=perf/testing/perf-non-hardware.json

To build the cAdvisor Docker container from source, run the provided build script. This script performs a static build of the cAdvisor binary and then packages it into a minimal Docker image named google/cadvisor:beta. Note that the beta image is highly stripped down, containing only the cAdvisor binary.

$ ./deploy/build.sh

To quickly monitor your machine's containers using Docker, run the cAdvisor image with the necessary volume mounts to allow it to observe the host's filesystem, Docker state, and system statistics.

Note: If you are using CentOS, Fedora, RHEL, or LXC, refer to the specific running instructions in docs/running.md.

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 # for versions prior to v0.53.0, use gcr.io/cadvisor/cadvisor instead

If you require cAdvisor with performance monitoring support, use the overlays/examples_perf overlay. This includes necessary modifications to the DaemonSet and the ConfigMap for perf events configuration.

To generate and apply the daemonset with perf support patches:

kubectl kustomize deploy/kubernetes/overlays/examples_perf | kubectl apply -f -

cAdvisor is distributed as a static Go binary with no external dependencies. You can run it directly on your host system. Note that running without root privileges may cause cAdvisor to gracefully degrade by omitting certain data sources it cannot access.

$ sudo cadvisor

RHEL and CentOS environments often require additional permissions and specific volume mounts due to tightened security and cgroup hierarchy locations.

General RHEL/CentOS Requirements

• Use --privileged=true to allow cAdvisor to access the Docker daemon socket.
• If cgroup hierarchies are mounted in /cgroup, add --volume=/cgroup:/cgroup:ro.

RedHat 7 Specific Configuration

If you are running on a RedHat 7 host, the standard Docker command may throw OCI errors. Use the following specific command instead:

docker run \
--volume=/:/rootfs:ro \
--volume=/var/run:/var/run:rw \
--volume=/sys/fs/cgroup/cpu,cpuacct:/sys/fs/cgroup/cpuacct,cpu \
--volume=/var/lib/docker/:/var/lib/docker:ro \
--publish=8080:8080 \
--detach=true \
--name=cadvisor \
--privileged=true \
google/cadvisor:latest

Once you have the source code and Go installed, navigate to the cAdvisor source directory and use make to build the binary or run tests.

Note: Ensure you are in the $GOPATH/src/github.com/google/cadvisor directory.

# Build the cAdvisor binary
$ make build

# Run only unit tests
$ make test