mirror of
https://github.com/allaunthefox/Research-Stack.git
synced 2026-07-31 03:05:21 +00:00
61 lines
1.7 KiB
Markdown
61 lines
1.7 KiB
Markdown
# 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:
|
|
|
|
```py
|
|
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):
|
|
|
|
```py
|
|
from nodupe.tools.telemetry import collect_metrics
|
|
print(collect_metrics())
|
|
```
|
|
|
|
- CLI (manual scrape):
|
|
|
|
```sh
|
|
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.
|