frigate_camera_events is typed as a counter but decreases as events are pruned — gauge or proper counter?

[Kohei-Wada]

Hi, I think there's a discrepancy between the documentation and the actual behavior of the frigate_camera_events Prometheus metric, and I'd like to check the intended direction before opening a PR.

frigate_camera_events is declared as a counter, but in practice it behaves like a gauge — it decreases when events are pruned from the database. Because it's typed as a counter, Prometheus treats each drop as a counter reset, so increase()/rate() massively over-count. In my setup ~26 events/day showed up as several thousand.

Root cause: the /api/metrics handler runs SELECT camera, label, COUNT(*) ... GROUP BY camera, label on the events table (a live snapshot that shrinks on pruning), and frigate/stats/prometheus.py exposes it via CounterMetricFamily. The value is really a gauge but is typed as a counter.

How to reproduce:

1. Run Frigate with Prometheus scraping /api/metrics.
2. Let events accumulate past the retention window so old events start getting pruned.
3. Watch frigate_camera_events over time — the raw value decreases (e.g. 344 -> 342), which is impossible for a real counter.
4. increase(frigate_camera_events[1h]) then inflates massively because each drop is read as a reset.

I see two ways to fix it:

1. Change it to a gauge — simple, but honestly not a very useful metric this way (you can't derive an event rate from it).
2. Implement it as a proper counter (cumulative since process start; no DB migration needed, but the count would need to be tracked across Frigate's multiple processes).

Which direction would you prefer? If a gauge is acceptable, I already have it implemented and can open a PR right away.

Version: 0.17.1 (same code on dev)

[inkeep-ai-assistant[bot]]

---

The documentation confirms that frigate_camera_events{camera="", label=""} is documented as a Counter type metric described as "Count of camera events since exporter started"(1). The metric types section explicitly states that Counter metrics are "Cumulative values that only increase"(1).

Your analysis is correct — if the implementation queries the database with SELECT ... COUNT(*) and the value decreases when events are pruned, that violates Counter semantics. A true counter should only increase (or reset to zero on process restart).

I don't have information in the available sources about which direction the maintainers would prefer for a fix. This would be a good question to raise directly with the maintainers.

You can reach out via GitHub to discuss whether they prefer:

1. Changing to a gauge (simpler but less useful for rate calculations)
2. Implementing as a proper cumulative counter tracked since process start

Would you like me to try to provide a general answer about the tradeoffs between these approaches?

📚 Sources:

1. Metrics

---

Have another question? Just tag @inkeep.

[NickM-27]

The Prometheus metrics are effectively community maintained, so I'm not sure what the direction of the original implementation was intended but what you describe does not sound correct behavior