Understand metric prefixes and recording rules

Use this reference to map OpenBao source metrics to the normalized recording rules used by this project. It is for operators who need to configure metric prefixes, read generated alerts, or adapt the dashboards to an existing Prometheus-compatible backend.

Prefix strategy

OpenBao still documents vault as the default telemetry prefix. This project therefore treats vault_* as the default source metric family and supports openbao_* when you explicitly configure metrics_prefix = "openbao".

Use source metrics for capture and validation. Use recording rules for dashboards and critical alerts when a rule exists.

Choose a prefix

Set the prefix in the OpenBao telemetry stanza.

telemetry {
  prometheus_retention_time = "30s"
  disable_hostname          = true
  metrics_prefix            = "vault"
}

If you use prefix_filter, write filters for the configured OpenBao prefix. For example, use +openbao.core only when you also set metrics_prefix = "openbao".

Use normalized rules

The generated recording rules use the openbao: namespace even when the source metric prefix is vault. This keeps Grafana dashboards and alert expressions stable across deployments.

The repository ships generated rule variants for both supported source prefixes. Use the variant that matches the metrics your OpenBao deployment emits.

The top-level generated/prometheus/openbao-recording-rules.yaml and generated/prometheusrules/openbao-recording-rules.yaml files remain the default vault variant for the local Docker Compose stack.

Regenerate all variants after you change the metric contract, alert contracts, or generator code.

make generate

You can still generate a single custom output with --source-prefix when you need a one-off path.

go run ./cmd/openbao-observability generate prometheus-rules \
  --contract contracts/metrics/openbao-core.yaml \
  --source-prefix openbao \
  --output /tmp/openbao-recording-rules.yaml \
  --rule-output /tmp/openbao-native-rules.yaml

Query source metrics during validation

Use source metrics when you need to confirm what OpenBao emits.

vault_core_active
vault_core_unsealed
vault_audit_log_request_failure
vault_runtime_num_goroutines
vault_barrier_get
vault_cache_hit

For an openbao-prefixed deployment, replace vault_ with openbao_.

Use compatibility queries only during migration or discovery. Regex selectors over metric names are useful for exploration, but generated dashboards and alerts should use direct source metrics or normalized recording rules.

{__name__=~"^(vault|openbao)_core_active$"}

Account for label differences

Raw OpenBao metrics do not expose one uniform label set. Some core metrics include an OpenBao cluster label, some development and fixture profiles emit an empty cluster="" series, and some runtime or lease metrics rely on scrape labels instead.

Recording rules in this project normalize the signals that dashboards need. When you write custom queries, check the live label set before grouping by cluster, namespace, pod, or instance.

Raft peer count behavior

The HA/Raft dashboard uses openbao:raft_peers:max instead of raw vault_raft_peers. The normalized rule prefers the raw Raft peer metric when OpenBao exposes it and falls back to counting *_raft_storage_stats_commit_index by peer_id in all-node scrape profiles.

This fallback exists because the current OpenBao 2.5.4 HA/Raft fixture observed vault_raft_peers on the active node, while the live Docker Compose all-node scrape exposed Raft storage stats without vault_raft_peers.

Validate generated artifacts

Run the repository verification target after you change metric prefixes, recording rules, alert contracts, or dashboard contracts.

make verify

When the Docker Compose stack is already running, validate dashboard queries against Prometheus and Loki.

make verify-live

Related files

What’s next

• Use OpenBao observability model to understand why the project separates source and derived signals.
• Use Understanding OpenBao metrics to understand metric types, labels, scrape profiles, and validation.
• Use High-cardinality and label safety before you group source metrics by optional OpenBao labels.
• Use Configure a secure metrics scrape to configure the authenticated active-node profile.
• Use Configure an all-node metrics scrape when you need standby and Raft follower visibility.
• Use Configure declarative audit devices when you need repeatable audit stream setup.
• Use Run the Docker Compose stack to inspect live source metrics and normalized rules locally.

Source: OpenBao documents metrics_prefix, disable_hostname, prometheus_retention_time, prefix_filter, and Prometheus scrape behavior in the OpenBao telemetry documentation . OpenBao documents the /sys/metrics endpoint and Prometheus output examples in the OpenBao metrics API documentation .