If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/google/cadvisor shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 4d ago
• 26+ active contributors
• Distributed ownership (top contributor 24% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live google/cadvisor repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/google/cadvisor.

What it runs against: a local clone of google/cadvisor — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in google/cadvisor | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of google/cadvisor. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/google/cadvisor.git
#   cd cadvisor
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of google/cadvisor and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "google/cadvisor(\\.git)?\\b" \\
  && ok "origin remote is google/cadvisor" \\
  || miss "origin remote is not google/cadvisor (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/google/cadvisor"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

cAdvisor is a container monitoring daemon that collects, aggregates, and exports real-time resource usage metrics (CPU, memory, network, disk I/O) for running containers. It runs as a background service and exposes container performance data via a REST API and web UI, with native Docker support and hierarchical container abstraction based on lmctfy. The core capability is analyzing resource isolation parameters and historical usage patterns at both per-container and machine-wide granularity. Monorepo structure: cmd/cadvisor.go is the main entry point; cache/ contains in-memory metrics storage; client/ provides API clients (v1 and v2); build/ houses compilation, testing, and deployment scripts; docs/ contains operational and development guidance. cmd/go.mod and cmd/go.sum isolate the binary build from the library module at the root, allowing relative module replacement (github.com/google/cadvisor => ../).

Container operators and platform engineers running Docker or Kubernetes who need visibility into container resource consumption and performance—specifically those deploying cAdvisor as a daemonset in Kubernetes clusters or as a standalone monitoring service to track CPU, memory, network, and disk metrics across their containerized workloads.

Production-ready. The project is well-established (actively maintained by Google), has comprehensive CI/CD workflows (.github/workflows/ shows test, release, and container publishing automation), includes unit and integration tests (build/unit-in-container.sh, build/integration.sh), supports Go 1.24.0, and maintains detailed documentation (docs/running.md, docs/storage/README.md). Recent releases (v0.55.1 mentioned in README) indicate active development.

Low-to-medium risk for standard deployments. The dependency footprint is moderate but includes heavy external integrations (InfluxDB, Elasticsearch, Kafka, BigQuery, Prometheus, Google Cloud APIs, Kubernetes client libs) which increase complexity. Single main repository dependency (github.com/google/cadvisor pointing to ../), requires privileged container access and raw filesystem mounts (/sys, /dev/kmsg) which carries security considerations. No visible breaking-change indicators in the file list, but integrations with multiple storage backends mean schema changes could affect downstream users.

Active CI/CD workflows for testing (test.yml), releasing binaries (release-binaries.yml), and publishing container images (publish-container.yml). The repo supports multiple container runtimes (plain, crio) and has integration test variants (integration-in-docker.sh, integration-crio.sh, prow_e2e.sh). Boilerplate checking (check_boilerplate.sh) and Go module hygiene validation (check_gotidy.sh) indicate mature code governance.

git clone https://github.com/google/cadvisor.git
cd cadvisor
make build  # or cd cmd && go build -o cadvisor ./cadvisor.go
# For Docker users: docker run --volume=/:/rootfs:ro --volume=/var/run:/var/run:ro --volume=/sys:/sys:ro --volume=/var/lib/docker/:/var/lib/docker:ro --publish=8080:8080 ghcr.io/google/cadvisor:0.55.1

Daily commands:

cd cmd
go run ./cadvisor.go
# Listens on http://localhost:8080
# Or build: go build -o cadvisor ./cadvisor.go && ./cadvisor

For testing: make test (from root) or specific test suites in build/unit-in-container.sh.

• cmd/cadvisor.go: Main entry point; initializes the daemon, binds HTTP handlers, sets up container runtime detection.
• cache/memory/memory.go: In-memory metrics store; core data structure for aggregating CPU, memory, network, and disk stats per container.
• cmd/internal/api/handler.go: HTTP API handlers; exposes REST endpoints for querying container stats and machine info.
• client/v2/client.go: Client library for querying cAdvisor metrics; shows the API contract and how exporters/backends consume data.
• build/build.sh: Build orchestration script; compiles binary with correct flags and handles platform-specific configurations.
• .github/workflows/test.yml: CI/CD definition; reveals how code is tested, which platforms are covered, and what gates merges.
• docs/storage/README.md: Documents the storage backend plugin architecture; critical for integrating new exporters (InfluxDB, BigQuery, Elasticsearch, etc.).
• Makefile: Top-level build targets; entry point for developers; defines test, build, and release tasks.

Start here by file category: metrics collection: examine cache/memory/memory.go and handlers in cmd/internal/api/handler.go; container runtime support: check build/config/*.sh for platform-specific logic and how crio vs. plain Docker are configured; API endpoints: modify cmd/internal/api/handler.go; new exporters/backends: reference client/v2/client.go and docs/storage/README.md to understand the storage plugin pattern; tests: add tests adjacent to code (e.g., *_test.go files) and use integration scripts in build/ for end-to-end validation.

Privileged access & mounts required: cAdvisor must run with --privileged flag and have read-only mounts to /sys, /var/lib/docker/, /dev/disk/ and /dev/kmsg to collect kernel metrics—non-containerized deployments need equivalent raw filesystem access. Module structure: cmd/go.mod uses a relative replace directive (=> ../) pointing to the parent module; builds must be run from the cmd/ directory or Makefile, not arbitrary locations. Runtime detection: Container runtime (Docker, crio, containerd) is auto-detected at startup; misconfiguration silently degrades functionality. Boilerplate enforcement: All source files must include license headers (build/boilerplate/*.txt); check_boilerplate.sh validates this and can block CI. Go module housekeeping: check_gotidy.sh enforces 'go mod tidy' compliance; missing this step will fail CI. No local dev docs: see docs/development/build.md for build instructions, but it's referenced in README, not committed in the top-level file list—clone and check it.

• cgroup (control groups) — cAdvisor reads /sys cgroup hierarchy to extract CPU, memory, and network limits/usage; understanding cgroups v1 vs v2 is essential to debug metric collection and container isolation.
• Container runtime abstraction / OCI — cAdvisor supports Docker, containerd, crio, and lmctfy via a pluggable runtime layer; grasping this abstraction explains why build/config/*.sh configures different runtimes and how to add support for new ones.
• Metrics aggregation & histograms — cache/memory/memory.go maintains rolling histograms of resource usage over time; this is critical for the 'historical resource usage and histograms' feature mentioned in the README and for computing percentiles/trends.
• Time-series database integration patterns — cAdvisor exports to InfluxDB, Elasticsearch, BigQuery, and Kafka; understanding how docs/storage/README.md defines the exporter interface and how client/v2/client.go provides the data contract is crucial for adding new backends.
• Privileged containers & Linux capabilities — cAdvisor requires --privileged and raw access to /sys, /dev/kmsg, and /var/lib/docker/; understanding why (reading kernel metrics, observing all containers) helps troubleshoot permission errors and security model decisions.
• Go module workspaces & relative replaces — cmd/go.mod uses replace github.com/google/cadvisor => ../ to reference the parent module; this pattern is non-standard and requires building via Makefile or from cmd/; misunderstanding it causes 'module not found' errors.
• REST API versioning & backward compatibility — client/v1 and client/v2 coexist in the codebase; understanding API versioning strategy and how handler.go routes both endpoints is essential for maintaining compatibility and planning deprecations.

• prometheus/node_exporter — Host-level metrics exporter that complements cAdvisor; both often run together to provide machine-wide and container-specific metrics in Kubernetes monitoring stacks.
• kubernetes/kubernetes — cAdvisor runs as a daemonset in Kubernetes clusters; the deploy/kubernetes directory and k8s.io imports show tight integration for kubelet-side container observation.
• containerd/containerd — Alternative container runtime supported by cAdvisor; understanding containerd's metrics APIs helps extend cAdvisor support beyond Docker and crio.
• open-telemetry/opentelemetry-go — Modern observability framework that can consume cAdvisor metrics; users integrating with OpenTelemetry pipelines will bridge cAdvisor data via this or similar adapters.
• google/lmctfy — Predecessor to cAdvisor's container abstraction model; README explicitly mentions lmctfy's hierarchical container concept as the foundation for cAdvisor's design.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for cmd/internal/api/handler.go with multiple container runtimes

The repo supports multiple container runtimes (Docker, crio, containerd) as evidenced by build/config/*.sh files, but cmd/internal/api/handler.go likely lacks comprehensive integration tests covering different runtime scenarios. The existing test.yml workflow runs tests, but there's no dedicated integration test suite validating API responses across runtimes. This would catch runtime-specific bugs early.

• [ ] Create cmd/internal/api/handler_integration_test.go with test cases for Docker, crio, and containerd
• [ ] Add test fixtures in cmd/internal/api/testdata/ for mock container responses per runtime
• [ ] Update .github/workflows/test.yml to run integration tests with docker and crio containers
• [ ] Document runtime-specific API behavior differences in cmd/internal/api/README.md

Add unit tests for cmd/internal/http/handlers.go HTTP endpoint validation

The cmd/internal/http/handlers.go file exists but there's no visible cmd/internal/http/handlers_test.go in the file structure. HTTP handlers are critical for the daemon's external interface and need comprehensive test coverage for edge cases (malformed requests, missing parameters, concurrent access). This is a high-value security-sensitive component.

• [ ] Create cmd/internal/http/handlers_test.go with tests for each HTTP endpoint handler
• [ ] Add test cases for invalid inputs, missing query parameters, and concurrent requests
• [ ] Test error response codes and formats match API contract
• [ ] Add benchmark tests for hot path handlers using testing.B

Add specific CI workflow to validate boilerplate compliance in PRs

The repo has build/check_boilerplate.sh and build/boilerplate/ directory with language-specific headers (boilerplate.go.txt, boilerplate.py.txt, boilerplate.sh.txt), but no GitHub Actions workflow explicitly runs boilerplate checks. Currently contributors may not know about this requirement. Adding a dedicated workflow would catch violations before merge.

• [ ] Create .github/workflows/boilerplate-check.yml that runs build/check_boilerplate.sh on all PRs
• [ ] Fail the check on any files missing required boilerplate headers
• [ ] Add documentation in CONTRIBUTING.md referencing the boilerplate requirement and which file types need which headers
• [ ] Test the workflow with a sample commit adding a new .go file without boilerplate

• Add missing test coverage for client/v2/client.go: The file exists but client/v2/client_test.go structure is minimal; enhance it with integration tests for the real API contract, testing timeout behavior, retry logic, and unmarshaling of container stats JSON—this matters because v2 client is the programmatic interface users and exporters depend on.
• Document the storage plugin architecture with a worked example: docs/storage/README.md exists but is sparse; create a minimal plugin example (e.g., a simple file-based exporter) in a docs/examples/custom-storage/ directory showing how to implement the exporter interface, how to wire it into cmd/cadvisor.go, and how to test it—this unblocks custom backend integrations.
• Add per-container metrics labels to Prometheus exporter: The Prometheus client_golang v1.22.0 dependency is present but likely missing container-name and container-id labels on exported metrics; enhance cmd/internal/api/handler.go or create a new prometheus.go file to ensure metrics are properly labeled and can be correlated with container metadata—this is essential for Kubernetes users relying on Prometheus scraping.

• High · Outdated and Vulnerable Dependencies — cmd/go.mod - dependency declarations. Multiple dependencies in go.mod contain known vulnerabilities due to age and lack of updates. Notable concerns: gopkg.in/olivere/elastic.v2 (v2.0.61) is an old Elasticsearch client, github.com/Shopify/sarama (v1.38.1) is outdated Kafka client, and github.com/influxdb/influxdb (v1.7.9) is significantly outdated. These versions likely contain known CVEs. Fix: Update all dependencies to their latest stable versions. Run 'go get -u' and review security advisories at https://pkg.go.dev/advisories. Consider using Go 1.24 native vulnerability scanner via 'go list -json -m all | govulncheck'.
• High · HTTP Basic Authentication Without TLS Enforcement — cmd/internal/http/handlers.go, dependency: github.com/abbot/go-http-auth. The codebase includes github.com/abbot/go-http-auth (v0.4.0) which provides HTTP basic authentication. Without explicit TLS enforcement, credentials could be transmitted in plaintext, especially if cAdvisor is exposed without HTTPS. Fix: Enforce HTTPS/TLS for all endpoints handling authentication. Implement HTTP to HTTPS redirects. Add security headers like Strict-Transport-Security (HSTS). Consider OAuth2 as alternative (package is available: golang.org/x/oauth2).
• High · Potential Sensitive Data Exposure via Storage Backends — cmd/internal/storage/ - multiple storage implementations (bigquery, elasticsearch, influxdb, etc.). cAdvisor supports multiple storage backends (BigQuery, Elasticsearch, InfluxDB, Kafka, Redis) without clear indication of encryption in transit or at rest. Database credentials and API keys may be exposed if configuration is improperly handled. Fix: Implement encryption for credentials storage (use environment variables or secret management systems). Enforce TLS for all backend connections. Implement proper access controls and audit logging for storage operations. Use least-privilege credentials.
• Medium · Potential XSS Vulnerability in Web UI — cmd/internal/pages/containers.go, cmd/internal/pages/assets/html/containers.html, cmd/internal/pages/assets/js/containers.js. The web UI assets (cmd/internal/pages/assets/html/containers.html, cmd/internal/pages/assets/js/containers.js) may be vulnerable to XSS if container metrics or names are rendered without proper escaping. Fix: Ensure all user-controlled data (container names, metrics, labels) is properly HTML-escaped before rendering. Use a template engine with automatic escaping. Implement Content Security Policy (CSP) headers. Sanitize all dynamic content.
• Medium · Missing CORS and Security Headers Configuration — cmd/internal/api/handler.go, cmd/internal/http/handlers.go, cmd/internal/http/mux/mux.go. The API handlers in cmd/internal/api/handler.go and cmd/internal/http/handlers.go may not implement proper security headers (CSP, X-Frame-Options, X-Content-Type-Options, CORS restrictions). Fix: Add security middleware to set appropriate HTTP headers: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, X-XSS-Protection, Strict-Transport-Security. Implement restrictive CORS policies.
• Medium · Kubernetes Client Library Exposure Risk — cmd/go.mod - k8s.io/klog/v2, k8s.io/utils dependencies. The codebase uses k8s.io dependencies which may lead to exposure of Kubernetes API tokens or service account credentials if improperly configured. Fix: Ensure Kubernetes clients use in-cluster configuration securely. Never hardcode credentials. Use RBAC appropriately. Regularly audit and rotate service account tokens. Run with minimal required permissions.
• Medium · Public Port Exposure Without Authentication — cmd/internal/http/handlers.go, cmd/internal/api/handler.go. cAdvisor runs as a daemon exposing container metrics via HTTP. The default configuration may expose sensitive container information without proper authentication or authorization controls. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.