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"},
	)

	// FlushLag is the age of the oldest un-flushed WAL segment, by kind
	// (usage/payload). RecordsLost fires only when data is already gone
	// and emit_queue_depth watches the in-memory channel — but a sink
	// outage (ClickHouse down) grows the on-disk WAL for hours with both
	// of those green. This gauge answers "how stale is my usage/billing
	// data": 0 = fully drained; rising = the sink is not accepting.
	FlushLag = prometheus.NewGaugeVec(
		prometheus.GaugeOpts{
			Namespace: Namespace,
			Name:      "flush_lag_seconds",
			Help:      "Age in seconds of the oldest un-flushed WAL segment, by kind (usage/payload). 0 = drained; rising = the sink is not accepting data.",
		},
		[]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"},
	)

	// InflightLimit is the configured admission cap — the denominator that
	// turns InflightRequests into headroom ("how close am I to shedding").
	// Without it the cap lives only in an env var and no dashboard can
	// plot inflight/limit or alert on approach. Constant after boot.
	InflightLimit = prometheus.NewGauge(
		prometheus.GaugeOpts{
			Namespace: Namespace,
			Name:      "inflight_limit",
			Help:      "Configured per-pod in-flight admission cap. Compare against relay_inflight_requests for shed headroom.",
		},
	)

	// 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 detached post-flight
	// goroutine — token extraction, the observer fan-out (Registry.Finalize),
	// and the rate-limit / host-health commit phase that runs after it. Same
	// Q5 question ("how long does relay's bookkeeping run after a request"),
	// now including the Valkey commit RTTs that dominate it.
	PostFlightSeconds = prometheus.NewHistogram(
		prometheus.HistogramOpts{
			Namespace: Namespace,
			Name:      "post_flight_seconds",
			Help:      "Duration of the detached post-flight goroutine (token extraction + observer fan-out + rate-limit/host-health commits) per request.",
			Buckets:   []float64{0.0001, 0.0005, 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5},
		},
	)
)

var UpstreamConnections = prometheus.NewCounterVec(
	prometheus.CounterOpts{
		Namespace: Namespace,
		Name:      "upstream_connections_total",
		Help:      "Upstream connections obtained per attempt, by kind (new = dialed, reused = keep-alive pool). new ≈ request rate means connection churn.",
	},
	[]string{"kind"},
)