From d3a2eb62b0f56f1b4e6a4f91d049cc7c65627a76 Mon Sep 17 00:00:00 2001 From: Ava Barron Date: Tue, 21 Jul 2026 09:43:09 -0400 Subject: [PATCH] docs: add metrics.md operator guide Adds docs/metrics.md documenting the OpenTelemetry metric instruments exported by buildkitd (the build-completion metrics from #6736) and how to scrape them over Prometheus (--debugaddr /metrics) or OTLP, linked from the README. Refs #1544 Signed-off-by: Ava Barron --- README.md | 4 ++++ docs/metrics.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 docs/metrics.md diff --git a/README.md b/README.md index 9699db6d1c62..6f7f241dda55 100644 --- a/README.md +++ b/README.md @@ -823,6 +823,10 @@ export JAEGER_TRACE=0.0.0.0:6831 > set the environment variable `setx -m JAEGER_TRACE "0.0.0.0:6831"`, > restart `buildkitd` in a new terminal and the traces will be collected automatically. +BuildKit also exports metrics through OpenTelemetry. See +[`docs/metrics.md`](docs/metrics.md) for the available instruments and how to +scrape them. + ## Running BuildKit without root privileges Please refer to [`docs/rootless.md`](docs/rootless.md). diff --git a/docs/metrics.md b/docs/metrics.md new file mode 100644 index 000000000000..dbd6c8875a67 --- /dev/null +++ b/docs/metrics.md @@ -0,0 +1,53 @@ +# Metrics + +buildkitd exports metrics through its OpenTelemetry `MeterProvider`. The same +provider drives both a Prometheus pull endpoint and, when configured, an OTLP +push exporter, so the instruments below are available through either transport. + +## Enabling metrics + +### Prometheus (pull) + +buildkitd registers a Prometheus exporter on its debug HTTP server. Start the +daemon with a debug address and scrape `/metrics`: + +```bash +buildkitd --debugaddr 127.0.0.1:6060 +curl http://127.0.0.1:6060/metrics +``` + +The debug endpoint also exposes Go runtime and profiling handlers, so bind it +to a trusted interface and put it behind your own access controls. + +OpenTelemetry instrument names are mangled to Prometheus conventions on this +endpoint: dots become underscores, monotonic counters gain a `_total` suffix, +and the unit is appended (for example `buildkit.build.duration` with unit `s` +is exported as `buildkit_build_duration_seconds`). The build duration is an +exponential histogram and is exported as a Prometheus native histogram, which +requires a scraper that negotiates the Prometheus protobuf format. + +### OTLP (push) + +Set the standard OpenTelemetry environment variables to push metrics to a +collector, for example: + +```bash +export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://collector:4317 +``` + +Set `OTEL_METRICS_EXPORTER=none` to disable metrics export entirely. + +## Instruments + +| Name | Type | Unit | Attributes | Description | +| --- | --- | --- | --- | --- | +| `buildkit.builds` | counter | | `status`, `error_code` | Builds completed. `status` is `success` or `failure`; `error_code` carries the gRPC status code string and is present only on failure. | +| `buildkit.builds.steps` | counter | | `kind` | Build steps observed, partitioned by `kind`: `completed`, `cached`, `total`, `warnings`. | +| `buildkit.build.duration` | histogram | `s` | `status` | Wall-clock duration of build solves, from creation to completion. Exported as an exponential (native) histogram. | + +## Attributes and cardinality + +Attributes are restricted to bounded, enumerated values so that the number of +exported time series stays finite. Free-form values such as error messages, +frontend identifiers, or per-build identifiers are intentionally not used as +attributes.