metrics

var (
	// RecordsLost counts background records dropped because a bounded
	// emitter queue was full (usage rows, payload captures). The async
	// contract mandates this counter: a drop you can't see is a billing
	// or audit hole. `kind` is the emitter: "usage" | "payload".
	RecordsLost = prometheus.NewCounterVec(
		prometheus.CounterOpts{
			Namespace: Namespace,
			Name:      "records_lost_total",
			Help:      "Background records dropped due to a full emitter queue, by kind (usage/payload).",
		},
		[]string{"kind"},
	)

	// ProviderKeysDown counts the times a pooled provider key was placed
	// into cooldown by a failure — the leading indicator of heading
	// toward "no healthy keys in pool". `reason` is the failure class
	// (auth/rate_limit/server_error/network/local_rl).
	//
	// A counter, not a gauge: breaker state lives in shared kv, so a
	// per-pod gauge of "keys down right now" would be inconsistent across
	// the fleet. Trip counts sum cleanly. A faithful global gauge is
	// deferred (would need a kv scan — not lightweight).
	ProviderKeysDown = prometheus.NewCounterVec(
		prometheus.CounterOpts{
			Namespace: Namespace,
			Name:      "provider_keys_down_total",
			Help:      "Times a pooled provider key was put into cooldown by a failure, by reason.",
		},
		[]string{"reason"},
	)
)

var (
	// RequestsTotal answers "how much traffic, how many errors" (Q1/Q2).
	// `status` is a bounded class (2xx/4xx/5xx), never the raw code.
	RequestsTotal = prometheus.NewCounterVec(
		prometheus.CounterOpts{
			Namespace: Namespace,
			Name:      "requests_total",
			Help:      "Total requests handled, by source runner and status class (2xx/4xx/5xx).",
		},
		[]string{"source", "status"},
	)

	// RequestSeconds is total end-to-end time (Q2 — the "whose time is
	// it" numerator). Wide buckets span cached/error responses through
	// long generation runs.
	RequestSeconds = prometheus.NewHistogramVec(
		prometheus.HistogramOpts{
			Namespace: Namespace,
			Name:      "request_seconds",
			Help:      "End-to-end request latency (handler entry to response closed).",
			Buckets: []float64{
				0.001, 0.005, 0.01, 0.05, 0.1,
				0.25, 0.5, 1, 2, 5, 10, 30, 60, 120,
			},
		},
		[]string{"source"},
	)

	// OverheadSeconds is THE wedge metric (Q1): Relay's own time, total
	// minus the upstream call. The performance contract puts a hard SLO
	// here (p99 < 10ms live). Tight sub-second buckets: 100µs → 500ms.
	OverheadSeconds = prometheus.NewHistogramVec(
		prometheus.HistogramOpts{
			Namespace: Namespace,
			Name:      "overhead_seconds",
			Help:      "Relay overhead = total handler time minus the upstream call. Observed only when upstream was reached.",
			Buckets:   []float64{0.0001, 0.0002, 0.0005, 0.001, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.25, 0.5},
		},
		[]string{"source"},
	)

	// InflightRequests answers "how many streams are open right now /
	// where does concurrency plateau" (Q5). A streamed request counts
	// until its body closes (post-flight fires at Close).
	InflightRequests = prometheus.NewGaugeVec(
		prometheus.GaugeOpts{
			Namespace: Namespace,
			Name:      "inflight_requests",
			Help:      "Currently-open requests, by source runner. Streams count until body close.",
		},
		[]string{"source"},
	)

	// AdmissionSeconds is Timing.Start → upstream handoff: auth +
	// rate-limit reserve + key selection — the Redis-contention proxy
	// (Q5). Skipped when the request never reached upstream. Same
	// sub-second bucket style as OverheadSeconds: 100µs → 250ms.
	AdmissionSeconds = prometheus.NewHistogramVec(
		prometheus.HistogramOpts{
			Namespace: Namespace,
			Name:      "admission_seconds",
			Help:      "Time from request accept to upstream handoff (auth + rate-limit reserve + key selection). Observed only when upstream was reached.",
			Buckets:   []float64{0.0001, 0.0002, 0.0005, 0.001, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.25},
		},
		[]string{"source"},
	)

	// PostFlightSeconds is the duration of one full post-flight fan-out
	// (Registry.Finalize): is post-flight keeping up with stream closes,
	// or building a goroutine backlog (Q5)?
	PostFlightSeconds = prometheus.NewHistogram(
		prometheus.HistogramOpts{
			Namespace: Namespace,
			Name:      "post_flight_seconds",
			Help:      "Duration of the post-flight observer fan-out (hooks + collectors) per request.",
			Buckets:   []float64{0.0001, 0.0005, 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5},
		},
	)
)