metrics

type Metrics struct {
	// ── Ingestor ─────────────────────────────────────────────────────────────
	// IngestorBytesTotal counts raw bytes received from each input source.
	IngestorBytesTotal *prometheus.CounterVec
	// IngestorPacketsTotal counts MPEG-TS packets written to the buffer.
	IngestorPacketsTotal *prometheus.CounterVec
	// IngestorErrorsTotal counts transient read/reconnect errors per stream.
	IngestorErrorsTotal *prometheus.CounterVec

	// ── Stream Manager ────────────────────────────────────────────────────────
	// ManagerFailoversTotal counts input source switches (primary → backup).
	ManagerFailoversTotal *prometheus.CounterVec
	// ManagerInputHealth is 1 when an input is delivering packets, 0 when degraded.
	ManagerInputHealth *prometheus.GaugeVec

	// ── Transcoder ────────────────────────────────────────────────────────────
	// TranscoderWorkersActive is the number of active FFmpeg processes per stream.
	TranscoderWorkersActive *prometheus.GaugeVec
	// TranscoderRestartsTotal counts FFmpeg crash-restarts per stream.
	TranscoderRestartsTotal *prometheus.CounterVec
	// TranscoderQualitiesActive is the number of active ABR renditions per stream.
	TranscoderQualitiesActive *prometheus.GaugeVec

	// ── DVR ───────────────────────────────────────────────────────────────────
	// DVRSegmentsWrittenTotal counts TS segments flushed to disk per stream.
	DVRSegmentsWrittenTotal *prometheus.CounterVec
	// DVRBytesWrittenTotal counts bytes written to disk per stream.
	DVRBytesWrittenTotal *prometheus.CounterVec

	// ── Stream lifecycle ──────────────────────────────────────────────────────
	// StreamStartTimeSeconds is the Unix timestamp when a stream pipeline was
	// last started. 0 / absent means the stream is not currently running.
	// Uptime in Grafana: time() - open_streamer_stream_start_time_seconds
	StreamStartTimeSeconds *prometheus.GaugeVec

	// ── Buffer Hub ────────────────────────────────────────────────────────────
	// BufferDropsTotal counts MPEG-TS packets dropped at the Buffer Hub
	// fan-out because a subscriber's channel was full. This is the canonical
	// signal that the "write never blocks" invariant is shielding the writer
	// from a slow consumer — alert on `rate(...) > 0` to catch quality
	// regressions before users complain.
	BufferDropsTotal *prometheus.CounterVec

	// ── Publisher ─────────────────────────────────────────────────────────────
	// PublisherSegmentsTotal counts HLS / DASH media segments successfully
	// packaged. format=hls|dash; profile is the rendition slug (track_1…) or
	// "main" for single-rendition streams. Rate sanity-checks output bitrate.
	PublisherSegmentsTotal *prometheus.CounterVec
	// PublisherPushState reports the state of each RTMP/RTMPS push destination
	// as a small enum cast to int: 0=failed, 1=reconnecting, 2=starting, 3=active.
	// Per-destination labels let alerts target individual sinks.
	PublisherPushState *prometheus.GaugeVec

	// ── Sessions ──────────────────────────────────────────────────────────────
	// SessionsActive is the number of currently-tracked play sessions per
	// stream and protocol. Reset to 0 on restart (in-memory tracker), but
	// converges back as viewers reconnect — Prometheus gauge semantics
	// match this exactly.
	SessionsActive *prometheus.GaugeVec
	// SessionsOpenedTotal counts every session creation per stream and proto.
	// Pair with rate() / increase() over a window for "viewer churn".
	SessionsOpenedTotal *prometheus.CounterVec
	// SessionsClosedTotal counts session terminations per stream, proto and
	// reason (idle, client_gone, kicked, shutdown). Pair with opened_total
	// to compute average session lifetime; spike of `kicked` could indicate
	// abuse mitigation kicking in.
	SessionsClosedTotal *prometheus.CounterVec

	// ── Hooks ─────────────────────────────────────────────────────────────────
	// HooksDeliveryTotal counts hook deliveries per hook, type and outcome
	// (success / failure). For HTTP hooks each batch counts as ONE delivery
	// regardless of batch size — divide events_dropped_total by this to
	// derive lost-event rate.
	HooksDeliveryTotal *prometheus.CounterVec
	// HooksEventsDroppedTotal counts events evicted from the per-hook batch
	// queue when it overflowed `BatchMaxQueueItems`. Non-zero rate means a
	// downstream HTTP target is stalled long enough to threaten data loss —
	// alert immediately.
	HooksEventsDroppedTotal *prometheus.CounterVec
	// HooksBatchQueueDepth is the current per-hook in-memory queue depth.
	// Together with HooksEventsDroppedTotal this gives the early-warning
	// signal: queue rising → target back-pressuring; queue at cap → drops imminent.
	HooksBatchQueueDepth *prometheus.GaugeVec

	// ── DVR ───────────────────────────────────────────────────────────────────
	// DVRRecordingActive is 1 while a DVR recording is being written for a
	// stream, 0 otherwise. Combine with rate(DVRSegmentsWrittenTotal) to
	// alert on "DVR enabled but no segments flowing".
	DVRRecordingActive *prometheus.GaugeVec
	// DVRRetentionPrunedBytes counts bytes deleted by the retention loop
	// per stream. Useful for capacity planning (how much churn the
	// retention policy is creating) and as the canonical signal that
	// retention is actually running. Pair with the rate of incoming
	// DVRBytesWrittenTotal to verify steady-state behaviour.
	DVRRetentionPrunedBytes *prometheus.CounterVec

	// ── Buffer Hub (capacity + fan-out visibility) ────────────────────────────
	// BufferCapacityUsed reports the MAX subscriber-channel depth on a
	// stream's ring buffer, as a fraction of capacity (0.0 — 1.0). We
	// emit max-across-subscribers (not per-consumer) because the buffer
	// API doesn't know which consumer attached — operators get the
	// leading-indicator signal (something is back-pressuring) without
	// the label-cardinality blowup of one series per anonymous consumer.
	// Refreshed by a sampler goroutine every BufferSampleInterval.
	BufferCapacityUsed *prometheus.GaugeVec
	// BufferSubscribers reports the number of active subscribers (consumer
	// channels) on a stream's buffer. Visibility into fan-out density —
	// confirms that publisher / transcoder / DVR have all attached, and
	// catches "stream registered but no consumers" misconfigurations.
	BufferSubscribers *prometheus.GaugeVec

	// ── HTTP API (request observability) ──────────────────────────────────────
	// HTTPRequestDuration is the standard request-latency histogram per
	// route + method + status. Use route TEMPLATES (e.g. "/streams/{code}")
	// not full paths to keep label cardinality bounded. Buckets cover the
	// fast hot-path APIs (List, Get) and slow long-poll / sweep endpoints.
	HTTPRequestDuration *prometheus.HistogramVec

	// ── Publisher (segment write timing + push bytes) ─────────────────────────
	// PublisherSegmentWriteDuration is the wall-clock time to write one
	// HLS / DASH segment to disk. Sustained tail-latency growth signals
	// disk I/O backpressure before BufferDropsTotal reflects it. Buckets
	// cover the fast (single-rendition local SSD) and slow (network FS)
	// regimes.
	PublisherSegmentWriteDuration *prometheus.HistogramVec
	// PublisherPushBytes counts bytes shipped per push destination. Useful
	// for egress-cost dashboards (CDN bandwidth attribution per dest_url)
	// and as the canonical "is push actually delivering data" signal.
	PublisherPushBytes *prometheus.CounterVec

	// ── Stream rollup (top-level operator dashboard) ──────────────────────────
	// StreamsTotal reports the count of streams in each top-level status
	// bucket. Reconciler refreshes this once per tick so a Grafana panel
	// can show the system-wide health summary without scraping per-stream
	// gauges and reducing client-side.
	StreamsTotal *prometheus.GaugeVec

	// ── Hooks (delivery error categorisation + batch sizing) ──────────────────
	// HooksBatchSize is the per-delivery batch size histogram. Tunes
	// `BatchMaxItems` — small batches = wasted HTTP overhead, large
	// batches = stale data. Pair with HooksDeliveryTotal to see whether
	// flushes are size-driven or interval-driven.
	HooksBatchSize *prometheus.HistogramVec

	// ── Manager (probe loop visibility) ───────────────────────────────────────
	// ManagerProbeAttemptsTotal counts failback probe runs against
	// degraded inputs, labelled by outcome (`success`/`failure`). Alert
	// on absence of probes (`absent_over_time(...[5m]) > 0`) — silent
	// probe loop means the manager never re-checks degraded inputs.
	ManagerProbeAttemptsTotal *prometheus.CounterVec

	// ── Reconciler (safety-net liveness) ──────────────────────────────────────
	// ReconcilerLastRunSeconds is the Unix timestamp of the last
	// successful reconciler tick. Should advance every 10s; an unchanged
	// value across multiple scrapes means the reconciler goroutine has
	// died — the safety net is gone.
	ReconcilerLastRunSeconds prometheus.Gauge
}