How-to guide
Observability — metrics and dashboards
Expose Prometheus metrics from the unified deployment and use the two ready-made Grafana dashboards to watch analysis runs, Insight enrichment, and documentation retrieval.
The unified Elevarq deployment can expose Prometheus metrics about analysis runs, Insight enrichment, snapshot delivery, and per-database documentation retrieval, together with two ready-made Grafana dashboards. Everything here is opt-in: with no metrics address set, no listener is opened and there is zero overhead.
Metrics describe Elevarq's own processing — how many runs succeeded, how long they took, how many findings by severity. They do not carry the contents of your database or any credential.
Enable the metrics endpoint
Set ELEVARQ_METRICS_ADDR to a listen address. When it is empty (the
default) no metrics listener is started.
| Value | Effect |
|---|---|
| unset (default) | No /metrics listener. |
127.0.0.1:9187 | Serves /metrics on loopback only (recommended). |
:9187 | Serves /metrics on all interfaces — only behind a firewall. |
Metrics are served at http://<addr>/metrics.
The endpoint is unauthenticated in this release. There is no
bearer token or per-scrape auth. Bind it to loopback or a private
interface and control access at the network layer (firewall,
network policy, or a scraping sidecar). Do not expose /metrics
publicly.
What you can monitor
The metrics below are the customer-relevant subset. All names are
prefixed elevarq_.
| Metric | Type | Key labels | Meaning |
|---|---|---|---|
elevarq_analysis_runs_total | counter | status (succeeded/failed/partial/skipped) | Analysis runs by terminal status. |
elevarq_analysis_duration_seconds | histogram | — | Wall-clock duration of an analysis run. |
elevarq_analysis_stage_duration_seconds | histogram | stage | Duration of each stage — the long-pole view. |
elevarq_analysis_findings_total | counter | severity (critical/high/medium/low/info) | Findings produced, by severity. |
elevarq_analysis_active | gauge | — | 1 while a run is in flight, else 0. |
elevarq_analysis_current_stage_index | gauge | — | 1-based stage index of the in-flight run (0 when idle). |
elevarq_insight_enrichment_hits_total | counter | result (succeeded/fallback) | Insight enrichment attempts by result. |
elevarq_insight_enrichment_fallback_total | counter | reason | Enrichment fall-backs by bounded reason (timeout, budget exhausted, …). |
elevarq_insight_enrichment_hit_duration_seconds | histogram | — | Per-enrichment latency. |
elevarq_docs_retrieval_total | counter | database, source, result | Documentation-retrieval hits/misses/fallbacks, per database. |
elevarq_docs_retrieval_fallback_total | counter | database, reason | Retrieval fall-backs, per database, by bounded reason. |
elevarq_docs_retrieval_snippets | histogram | database | Accepted documentation snippets per retrieval. |
elevarq_delivery_total | counter | outcome (delivered/failed/skipped) | Outcomes of pushing results to Workbench. |
elevarq_database_info | gauge (=1) | database, alias, environment | Maps a database handle to its friendly alias + environment, for label-joins in the dashboards. Refreshed about once a minute from Workbench. |
elevarq_build_info | gauge (=1) | version, model_tier, runtime, profile | Build and served-model identity, set once at startup. |
Enrichment budget-used ratio and GPU utilisation are not exported in this release.
A note on labels and sensitivity
Most labels are bounded enumerations (status, severity, outcome,
reason, stage) — safe to chart and alert on.
Two things are worth knowing:
elevarq_database_infocarriesaliasandenvironment. Thedatabasehandle itself is opaque, but the alias and environment are the human-meaningful names you gave the database in Workbench, and they are visible to anyone with access to the dashboards. If that matters in your environment, restrict who can view Grafana.- The
databaselabel is per-database. The docs-retrieval metrics carry one series per observed database, keyed by the opaque handle. That is intentional; the other metrics stay low-cardinality.
Run the bundled Prometheus + Grafana
The release ships an example stack and both dashboards under
observability/. From the release directory:
docker compose -f observability/examples/docker-compose.yml up- Grafana →
http://localhost:3000(default loginadmin/admin— change it on first sign-in). - Prometheus →
http://localhost:9090.
Point Prometheus at the deployment's metrics address (the example
config scrapes host.docker.internal:9187; adjust it to your
ELEVARQ_METRICS_ADDR). A 15–30s scrape interval is plenty —
analysis runs are infrequent, so faster scraping adds no detail.
Two dashboards are provisioned automatically into the Elevarq Analysis folder:
| Dashboard | Shows |
|---|---|
| Elevarq — Analysis Overview | Runs by status, duration percentiles, findings by severity, delivery outcomes, the live in-flight stage, and build/model identity. |
| Elevarq — Insight Enrichment | Enrichment hits by result, fall-backs by reason, per-hit latency, and per-stage duration. |
Using your own Grafana
If you already run Grafana (10.4 or newer), skip the bundled stack:
- Add a Prometheus data source pointing at the Prometheus that scrapes the deployment.
- Dashboards → New → Import, and upload
observability/grafana/dashboards/analysis-overview.jsonandanalysis-enrichment.json. - Select your Prometheus data source when prompted.
The dashboards use only stable panel types and need no Enterprise features or plugins.
Related
- Insight enrichment on large databases — what the enrichment metrics are measuring.