telemetry

type Log struct {
	// contains filtered or unexported fields
}

type Metrics interface {
	// OutboxEventsPublished is incremented each time PublishTx or
	// PublishBestEffortTx successfully writes a webhook_events row.
	OutboxEventsPublished(eventType string)

	// OutboxEventsFanOut is incremented each time the worker finishes
	// fanning an event out to its matched webhooks. matched is the
	// number of webhook_subscriber_deliveries rows written.
	OutboxEventsFanOut(eventType string, matched int)

	// OutboxEventsNoMatch is incremented each time the worker
	// transitions an event to status='no_match' because zero
	// subscribers matched. Useful for spotting "why didn't my
	// webhook fire?"
	OutboxEventsNoMatch(eventType string)

	// OutboxFailures is incremented on any outbox failure — worker-side
	// (stage in {"lease", "list_webhooks", "insert_delivery", "update_status"})
	// or emit-side when a fire-and-forget producer's PublishTx fails and the
	// event is DROPPED (stage "publish" — today only the outbound
	// email.blocked producer; other producers either surface the error to
	// the caller or log via PublishBestEffortTx). A non-zero "publish" rate
	// means contract events are silently missing from the log.
	OutboxFailures(stage string)

	// RedeliverRequests is incremented on each customer-driven replay.
	// scope in {"single", "since"}.
	RedeliverRequests(scope string)

	// JanitorRowsDeleted is incremented by the cleanup tick.
	// table in {"webhook_events", "webhook_subscriber_deliveries", "webhook_deliveries", "messages", "user_sessions", "oauth"}.
	JanitorRowsDeleted(table string, count int)

	// NotifyMissed is incremented when the 1-second fallback poll
	// finds work that LISTEN/NOTIFY didn't wake us for. A non-zero
	// rate indicates reconnect churn or a dropped notification.
	NotifyMissed()

	// SetPublisherLag is a gauge: the age in seconds of the oldest
	// pending webhook_events row. Should be set on every Tick. Alert
	// if it stays > 30s.
	SetPublisherLag(seconds float64)

	// HTTPRequest records one served HTTP request. route is the chi
	// route pattern (e.g. "/v1/agents/{email}"), NEVER the raw path.
	// statusClass is "1xx".."5xx". A negative seconds means "count the
	// request but record no duration sample" — used for hijacked
	// (WebSocket) connections, whose handler runtime is the connection
	// lifetime, not a request latency.
	HTTPRequest(method, route, statusClass string, seconds float64)

	// SMTPInbound records one SMTP intake decision. outcome ∈
	// {accepted, accepted_dedup, tempfail, rejected_unknown_recipient,
	// rejected_unverified_domain, rejected_quota}. Units differ by
	// stage: accepted/accepted_dedup/tempfail are per DATA transaction;
	// rejected_* are per rejected RCPT command (one transaction can
	// emit several rejections and still accept). seconds is DATA
	// processing time (0 for RCPT-stage rejections).
	SMTPInbound(outcome string, seconds float64)

	// OutboundQueueWait records due→pickup latency for one outbound
	// send attempt (River attempted_at − scheduled_at; created_at would
	// count each retry's full backoff as queue wait).
	OutboundQueueWait(seconds float64)

	// OutboundTerminal records a terminal outcome for an outbound
	// message. outcome ∈ {sent, failed_suppressed, failed_provider,
	// failed_local_retries, failed_cancelled}. Exactly one per message:
	// a deferred final attempt is counted by the terminal reconciler
	// when it settles.
	OutboundTerminal(outcome string)

	// OutboundAttempt records one submission attempt to the upstream
	// relay. outcome ∈ {success, temporary_failure, permanent_failure}.
	// seconds is the submission duration.
	OutboundAttempt(outcome string, seconds float64)

	// WebhookAttempt records one webhook delivery attempt. outcome ∈
	// {delivered, retryable_failure, exhausted, webhook_deleted,
	// skipped_disabled}. statusClass is the HTTP status class of the
	// endpoint's response, or "none" when no response was received
	// (connect/DNS/SSRF-blocked).
	WebhookAttempt(outcome, statusClass string, seconds float64)

	// WSConnected / WSDisconnected count WebSocket connection
	// lifecycle events. reason ∈ {replaced, ping_timeout,
	// client_close, error, shutdown}.
	WSConnected()
	WSDisconnected(reason string)

	// WSDrained counts unread messages pushed during connect-drain.
	WSDrained(count int)

	// WSSendFailure counts failed pushes to a registered connection.
	WSSendFailure()

	// SetWSActive is a gauge: current registered WS connections.
	SetWSActive(n int)

	// InboundProcess records an async inbound-worker outcome. outcome
	// ∈ {processed, noop, failed_recipient_gone, failed_exhausted,
	// retryable}.
	InboundProcess(outcome string, seconds float64)

	// SetQueueDepth / SetQueueOldestAge are gauges sampled by the
	// queue-stats maintenance job. queue ∈ jobs.Queue* names; state ∈
	// {available, running, retryable, scheduled}. Oldest age is for
	// runnable (available) jobs only — a growing value means workers
	// are not keeping up.
	SetQueueDepth(queue, state string, n int)
	SetQueueOldestAge(queue string, seconds float64)
}

type NoOp struct{}

type Prom struct {
	// contains filtered or unexported fields
}