Research-Stack/4-Infrastructure/NoDupeLabs/docs/reference/TELEMETRY.md

Telemetry — QueryCache metrics

This document explains how to collect Prometheus-format metrics emitted by the in-process QueryCache and the lightweight telemetry helper included in NoDupeLabs.

Key points

• QueryCache.export_metrics_prometheus() emits counters and gauges in Prometheus text format.
• nodupe.tools.telemetry provides a tiny registry + collect_metrics() that aggregates metrics from registered QueryCache instances and adds a cache="<name>" label.

Usage

• Register a cache in your application:

from nodupe.tools.databases.query_cache import QueryCache
from nodupe.tools.telemetry import register_query_cache

qc = QueryCache(max_size=100, ttl_seconds=3600)
register_query_cache("main-cache", qc)

• Collect metrics (programmatic):

from nodupe.tools.telemetry import collect_metrics
print(collect_metrics())

• CLI (manual scrape):

python -m nodupe.tools.telemetry

Metric names

• nodupe_query_cache_hits_total (counter)
• nodupe_query_cache_misses_total (counter)
• nodupe_query_cache_insertions_total (counter)
• nodupe_query_cache_evictions_total (counter)
• nodupe_query_cache_ttl_expiries_total (counter)
• nodupe_query_cache_size (gauge)
• nodupe_query_cache_capacity (gauge)
• nodupe_query_cache_hit_rate (gauge)

All metrics emitted via collect_metrics() include a cache label so you can run a single Prometheus scrape to capture multiple cache instances.

Example Prometheus line

nodupe_query_cache_hits_total{cache="main-cache"} 42

Testing

• Unit tests validate the Prometheus-format output and numeric values.
• Integration tests simulate cache hits/misses/TTL expiries and assert correctness of exported metrics.