A lightweight Rust application that scrapes and exposes BuildKit metrics.
flowchart LR
subgraph host
BK[BuildKit daemon]
A[buildkit-metrics-agent]
end
BK -->|"gRPC (unix socket)"| A
A -->|"GET /metrics"| P[Prometheus]
| Metric | Type | Labels | Description |
|---|---|---|---|
buildkit_info |
gauge | version, revision |
BuildKit version info (always 1) |
buildkit_workers_total |
gauge | Number of active workers | |
buildkit_cache_records_total |
gauge | Number of cache records | |
buildkit_cache_size_bytes |
gauge | Total cache size in bytes | |
buildkit_cache_size_by_type_bytes |
gauge | record_type |
Cache size in bytes by record type |
buildkit_builds_total |
counter | Total builds observed | |
buildkit_builds_succeeded_total |
counter | Builds that completed successfully | |
buildkit_builds_failed_total |
counter | Builds that failed | |
buildkit_builds_cached_steps_total |
counter | target, image (opt-in) |
Total cache-hit build steps |
buildkit_builds_total_steps_total |
counter | target, image (opt-in) |
Total build steps |
buildkit_build_duration_seconds |
histogram | Build duration from created to completed | |
buildkit_scrape_failures_total |
counter | source |
Failed Control API fetches by source |
The step counters are unlabeled by default. Opt in with
--labels.build-steps (env LABELS_BUILD_STEPS): a comma-separated list of
target and/or image. Both counters always share the same labels so a
cache-hit ratio query stays aligned. Unknown names are rejected at startup.
target is the Dockerfile target. image is the repository of the exported
image, with tag and digest stripped. Either falls back to unknown when a
build reports none. image still grows with each distinct repository; only
enable it if you need that breakdown.
With --labels.build-steps target,image:
sum by (image, target) (rate(buildkit_builds_cached_steps_total[1h]))
/ sum by (image, target) (rate(buildkit_builds_total_steps_total[1h]))
A pre-built dashboard is provided at examples/grafana/buildkit-metrics-dashboard.json.
Import: In Grafana, go to Dashboards → Import, upload the JSON file, and select your Prometheus datasource when prompted.
The dashboard includes:
- Overview stats — total builds, succeeded, failed, and success rate over the selected time range; current cache size and worker count.
- Rates & trends — build and failure rate over time; step throughput broken down by total vs. cache-hit steps.
- Per-pod breakdown — top-K pods ranked by builds, failures, cache size, and cached steps; a summary table with all key metrics per pod.
- Cache breakdown — cache size by type over time.
Filters for namespace, pod, and top-K limit are available as dashboard variables.
Flags or the matching environment variable.
| Flag | Env | Default | Description |
|---|---|---|---|
--addr |
BUILDKIT_ADDR |
unix:///run/buildkit/buildkitd.sock |
BuildKit gRPC endpoint (unix socket path or unix:///path) |
--metrics-addr |
METRICS_ADDR |
0.0.0.0:9090 |
Prometheus /metrics listen address |
--scrape-interval-secs |
SCRAPE_INTERVAL_SECS |
15 |
How often to scrape the Control API |
--labels.build-steps |
LABELS_BUILD_STEPS |
empty | Extra labels on both step counters. Comma-separated target and/or image. |
- Nix (recommended):
nix developthen usecargo/makeas below. - Otherwise: Rust 1.70+,
cargoin PATH.
Refresh BuildKit proto snapshots before regenerating proto-derived code:
make update-protos # refreshes proto/ from pinned BuildKit ref
make generate # writes src/generated/Then build and run:
cargo build --release
cargo run --release -- # or: make runGenerated code must exist in src/generated/ (run make generate and commit, or run codegen in CI before docker build). The Dockerfile is multi-arch: it builds for the target platform (linux/amd64 or linux/arm64) via BuildKit TARGETPLATFORM.
Single arch (current host):
docker build -t buildkit-metrics-agent .Both linux/amd64 and linux/arm64 (manifest list):
docker buildx build --platform linux/amd64,linux/arm64 -t buildkit-metrics-agent .
# or: make docker-multiStart BuildKit and the metrics agent (socket at /shared/buildkit, TCP on 1234 for buildx):
docker compose up -dUse the remote builder and run a build (optional):
docker buildx create --driver remote tcp://localhost:1234 --use
docker buildx build --load -t myimage:latest -f Dockerfile .Metrics in browser: http://localhost:9090/metrics
Deploy as a sidecar next to BuildKit using the provided example:
kubectl apply -f 'examples/kubernetes/rootless+service.yaml'See examples/kubernetes/rootless+service.yaml for the full Pod + Service manifest.
Scrape http://<pod-ip>:9090/metrics or use the buildkit-metrics-agent Service for in-cluster Prometheus scraping.