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

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.

1.7 KiB Raw Blame History

Telemetry — QueryCache metrics

1.7 KiB

Raw Blame History