docs(monitoring): correct the metric reference against Weaviate v1.39

[dudanogueira]

Important

Do not merge before the dashboards PR. The rewritten Sample Dashboards section points at weaviate/grafana-dashboard-weaviate, whose main does not yet hold the revamped dashboards.

What's being changed:

The monitoring page had drifted far enough from the code to be actively misleading. Four whole metric families were documented without the weaviate_ prefix Prometheus actually exposes, so any query copied from the page returned no data: async replication (21 rows), LSM bucket (35), LSM memtable flush (5), replication coordinator and read repair (11). A further 141 metrics a v1.39 node exposes had no row at all — object TTL, the replication engine, the HTTP and gRPC servers, query admission control, batch streaming, export, tenants and offload, incremental backups, the cluster store, and the RAFT and memberlist internals. Five rows described metrics that are declared in the source but never written.

This comes out of the Sept 2026 metrics audit, which checked every Prometheus metric in the Weaviate source three ways: emitted by a running cluster, present on this page, and charted on a dashboard.

	Before	After
Metric rows	210	346
Names Prometheus never exposes	67	0
Live metrics with no row	141	0

Rather than spot-fixing, every table was checked against a metric catalog built from a live /metrics scrape of a 3-node v1.39.5 cluster plus a sweep of the Weaviate source.

Also on the page:

• Published the What to alert on and OpenTelemetry tracing sections, which were written but left inside an HTML comment. The latter links to the OTel env-var reference, which was commented out too, so both were unblocked together.
• Rewrote Sample Dashboards around weaviate/grafana-dashboard-weaviate (the maintained home) in place of weaviate/weaviate's tools/dev/grafana, adding how to load them (Grafana UI, file provisioning, kube-prometheus-stack) and which are portable across Docker, bare metal and Kubernetes. The eight screenshots of the replaced dashboards are deleted.
• Replaced the stale five-file source list with curl -s localhost:2112/metrics | grep '^# HELP' as the definitive answer for a given version, plus a note that which metrics appear depends on which modules are enabled.
• Said what PROMETHEUS_MONITORING_GROUP actually does (labels collapse to n/a; per-segment LSM and vector-dimension metrics are dropped), and that weaviate_schema_shards reports an empty status for collections without multi-tenancy.
• Fixed the type of weaviate_internal_counter_raft_state_follower and the labels on weaviate_build_info, weaviate_schema_collections, queue_paused and queue_count.
• Added TRACK_VECTOR_DIMENSIONS and TRACK_VECTOR_DIMENSIONS_INTERVAL to the env-var reference, and corrected PROMETHEUS_MONITORING_METRIC_NAMESPACE, which described a prefix that is reserved rather than applied.

Two deliberate choices worth a reviewer's attention:

1. Metrics that are declared but never written are removed, not annotated. concurrent_goroutines, lsm_segment_objects, backup_restore_init_ms, backup_restore_from_backend_ms and tokenizer_requests_total promise data that never arrives. They are listed in EXPECTED_ABSENT in the new checker, so a release that starts writing them fails the check and gets documented.
2. The audit is repeatable, not one-off. tools/check_metrics_docs.py parses the page's tables and diffs them against the catalog JSON from the dashboards repo. It is not wired into CI — the catalog lives in another repo and needs a live cluster — but it turns "re-audit the metrics page" into one command each release.

Type of change:

• Documentation content updates (non-breaking change to fix/update documentation )

How has this been tested?

• Local build — yarn build-dev clean; yarn validate-links-dev shows no new breakage (the two quickstart links and the Google Tag Manager id=None tag are pre-existing and unrelated).
• Against a live cluster — 3-node Weaviate v1.39.5 with Prometheus and Grafana, plus the coverage workload. 306 of the 346 documented metrics were confirmed in a live scrape, and every non-runtime metric that cluster exposed has a row. The other 40 belong to modules or code paths the stack does not exercise (vectorizer providers, backup backends, usage and offload modules, replica movement).
• Checker — tools/check_metrics_docs.py --labels passes against the v1.39 catalog: no unknown names, no missing Weaviate-owned metrics, no duplicate rows, no type or label mismatches.

Risks

• Renamed metrics break saved queries. The new names are the real ones, so anyone affected had a query that already returned nothing. Headings are unchanged apart from the new subsections, so no redirects are needed and inbound anchors (#mcp-server, #sample-dashboards) still resolve.
• Version skew. The page is correct against v1.39; metrics remain explicitly outside semver, and the existing versioning admonition stays. Re-running the checker against a fresh catalog each release is the mitigation.
• Out of scope. The code bugs the audit turned up (tenant-offload byte accounting, the doubled weaviate_weaviate_grpc_conn_* prefix, _ms timers recording seconds, unusable backup labels) are being filed separately on weaviate/weaviate. This PR documents metrics under the names actually exposed without commenting on why.

🤖 Generated with Claude Code

[orca-security-eu]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Infrastructure as Code	0   0   0   0	View in Orca
Passed	SAST	0   0   0   0	View in Orca
Passed	Secrets	0   0   0   0	View in Orca
Passed	Vulnerabilities	0   0   0   0	View in Orca