Skip to content

About

A lightweight BuildKit metrics agent

Topics

Resources

Stars

15 stars

Watchers

0 watching

Forks

Repository files navigation

BuildKit Metrics Agent

codecov On PR

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]
Loading

Metrics

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]))

Grafana

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.

Config

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.

Dev Setup

  • Nix (recommended): nix develop then use cargo / make as below.
  • Otherwise: Rust 1.70+, cargo in 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 run

Image Build

Generated 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-multi

Demo

Docker Compose

Start BuildKit and the metrics agent (socket at /shared/buildkit, TCP on 1234 for buildx):

docker compose up -d

Use 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

Kubernetes

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.

About

A lightweight BuildKit metrics agent

Topics

Resources

Stars

15 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages