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
}