Wikantik publishes a small set of Prometheus metrics covering structural index health, for-agent projection size, the dense side of hybrid retrieval, and retrieval quality. They are scraped at /metrics and all start with wikantik_.
When you have a /metrics scrape and want to convert numbers into verdicts: has retrieval quality regressed, are for-agent projections landing under budget, is the dense (embedding) side healthy?
wikantik_structural_index_{pages_total,clusters_total,tags_total,unclaimed_total,lag_seconds} — gauges. Plus wikantik_structural_index_rebuild_duration_seconds (timer) for rebuild cost. GET /api/health/structural-index gives a one-shot status.wikantik_for_agent_response_bytes — DistributionSummary with percentile histogram (_bucket, _count, _sum). Records every projection's serialised size against the 4 KB / 8 KB budget.wikantik_search_hybrid_embedder_{calls_total{result},cache_total{result},breaker_transitions_total{to},breaker_rejected_total,circuit_state,latency_seconds}, wikantik_search_hybrid_vector_index_size, wikantik_search_hybrid_vector_index_last_rebuild_millis (lucene-hnsw only) and wikantik_search_hybrid_bootstrap_{state,chunks_total}. A circuit_state of 2 (OPEN), a vector-index size of 0, or a bootstrap_state of 5 (FAILED) all mean the dense side is silent and retrieval is BM25-only.wikantik_retrieval_{ndcg_at_5,ndcg_at_10,recall_at_20,mrr}{set,mode} — gauges, plus wikantik_retrieval_run_duration_seconds (timer) and wikantik_retrieval_run_failed_total (counter). They are NaN until a nightly or on-demand run has completed — see RunningTheRetrievalQualityHarness.The frontmatter steps walk the metric set in priority order: index health first (the foundation), projection size second (the agent contract), dense-side health third, retrieval quality last (the headline signal). For quality, wikantik_retrieval_ndcg_at_5{set="core-agent-queries",mode="hybrid"} is the headline gauge. The design's alert is an absolute drop of more than 5 points against the previous run of the same (set, mode); docs/admin/RetrievalQuality.md also shows a floor rule (< 0.80) you can calibrate to your corpus.
To tell which retriever is at fault, compare the arms of GET /api/bundle?q=…: mode=lexical ranks by BM25 alone, mode=dense by vectors alone, and the default hybrid fuses them with weighted Reciprocal Rank Fusion. debug=rankings returns the raw dense and BM25 chunk rankings (ids and scores) when wikantik.bundle.bm25.enabled is on. BM25 wins on exact identifiers, class names and error codes; dense wins on paraphrase and synonym drift. Page-level search fuses with k = 60 and BM25 and dense weights of 1.5 each (wikantik.search.hybrid.rrf.*); the bundle uses its own wikantik.bundle.bm25.* weights — see HybridRetrieval. A hybrid row that matches the bm25 row in the nightly runner, or a bundle coverage block with topSimilarity: -1.0 and confidence: unknown, means the dense side contributed nothing — see HandlingEmbeddingServiceOutages.
The frontmatter pitfalls capture the recurring misreads. The "comparing absolute numbers across deploys" trap is especially common — agents take a snapshot of metrics, deploy a different corpus, then report that "retrieval got worse" when the page count just shifted.
Cluster Hub: Agent Cookbook (agent-cookbook)