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)

	// ContactDuePublished / ContactDueFailed count outreach wake-ups by
	// outcome. A failed publish means the agent was not woken for a schedule
	// that has already been consumed, so it will not retry.
	ContactDuePublished(count int)
	ContactDueFailed(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, rejected_line_too_long}.
	// Units differ by stage: accepted/accepted_dedup/tempfail are per DATA
	// transaction; rejected_line_too_long is per DATA transaction aborted
	// mid-read (line over MaxLineLength); the other 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)

	// ThreadHeaderParseFailure counts an inbound RFC threading header that
	// failed strict parsing. header is one of {in_reply_to, references}.
	ThreadHeaderParseFailure(header string)

	// 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)

	// OutboundTerminalLatency records acceptance→terminal latency for
	// one outbound message (the terminal write's occurred_at −
	// messages.created_at). Observed exactly once per message,
	// co-located with the OutboundTerminal emission so the two share
	// their exactly-once contract (the SNS-feedback settle path stays
	// uninstrumented for both — see the guard comment at the worker's
	// MarkSent emit in internal/outboundsend).
	OutboundTerminalLatency(seconds float64)

	// 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)

	// OutboundRateDeferred records one outbound submission deferred by the
	// per-agent fire-time rate limiter (internal/sendrate): the job snoozes
	// and re-fires when the agent's sliding window frees capacity — it is
	// NOT an attempt, NOT a terminal outcome, and is never metered. A
	// sustained high rate means agents are queueing behind their own
	// 60/min budget.
	OutboundRateDeferred()

	// 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)

	// WebhookTerminal records terminal delivery outcomes after the terminal
	// database transition succeeds. outcome ∈ {delivered, e2a_failure,
	// endpoint_failure, excluded}; scope ∈ {initial, replay, test, unknown}.
	// The hosted SLO uses initial + unknown and excludes endpoint_failure:
	// customer endpoint behavior must not burn e2a's error budget.
	WebhookTerminal(outcome, scope string, count int)

	// WebhookExpiredPending counts delivery rows that reached their
	// retention TTL while still 'pending' and were marked terminally
	// failed ("expired before delivery") by the janitor instead of being
	// silently deleted. With the dead-job reconciler rescuing strands,
	// a sustained non-zero rate means deliveries are aging out
	// un-attempted — in practice rows snoozing behind a webhook disabled
	// for longer than the TTL.
	WebhookExpiredPending(count int)

	// WebhookFanOutRescued / WebhookDeliveryRescued count rows the
	// reconcilers' dead-job arm re-drove: a pending webhook_events /
	// webhook_subscriber_deliveries row whose stamped River job was
	// terminal or pruned, given a fresh job. Occasional blips are normal
	// (crash windows, lost terminal writes); a monotonically climbing
	// rate is the poison-row signal — a deterministically failing row
	// burning a fresh job envelope per rescue, forever. These counters
	// are the observability half of the deliberate
	// retry-forever-with-observability design.
	WebhookFanOutRescued(count int)
	WebhookDeliveryRescued(count int)
	// WebhookFirstAttemptLatency records event→first-attempt latency
	// for one subscriber delivery (attempt start − the webhook_events
	// row's created_at). Observed only on a delivery's FIRST HTTP
	// attempt — retries and the no-POST outcomes (webhook_deleted,
	// skipped_disabled) never observe.
	WebhookFirstAttemptLatency(seconds float64)

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

	// WSHandshakeRejected counts pre-upgrade WebSocket handshake
	// rejections. reason ∈ {unauthorized, not_found, forbidden,
	// upgrade_failed, internal_error}. Never label with emails or tokens.
	WSHandshakeRejected(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)

	// ThreadResolution counts thread-identity decisions by bounded source.
	// The lazy_legacy_anchor source is the adoption counter; use rate() over
	// a one-hour range to monitor the compatibility tail.
	ThreadResolution(source string, count int)

	// SetThreadNullMessages samples recent messages that still have no
	// materialized thread ID. ageBucket ∈ {lt_1h, 1h_6h, 6h_24h}.
	SetThreadNullMessages(ageBucket string, count int)

	// SetThreadInvariantViolations publishes the bounded audit's current
	// findings. kind ∈ {dangling_parent, cross_agent_parent,
	// thread_mismatch, cycle, cycle_depth_limit}.
	SetThreadInvariantViolations(kind string, count int)

	// SetThreadRelationshipPercent publishes sampled mailbox-local topology
	// ratios. kind ∈ {threads_multi_conversation,
	// conversations_multi_thread}; percent is clamped to [0,100].
	SetThreadRelationshipPercent(kind string, percent float64)
}

type NoOp struct{}

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