Alerts

.Alerts() on the system, a stream, or a consumer handle returns that scope’s alerts handle: no I/O, no failure. An alert is a retained message on __system.alerts about one resource, keyed by the alert’s name and its owner, and it takes the metrics grammar: Latest reads the newest retained one, History reads retained ones newest first, Definitions says what SQLStreams can raise.

stream := client.Stream[PaymentRequestedV1]("payments.requested")
current, err := stream.Alerts().PartitionCount().Latest(ctx) // *sqlstreams.Alert; nil before the first
if err != nil {
	return err
}
history, err := stream.Alerts().WorkerLiveness().History(ctx, 20)
if err != nil {
	return err
}
snapshot, err := stream.Alerts().PartitionCount().Snapshot(ctx)
if err != nil {
	return err
}
all, err := client.System().Alerts().Latest(ctx) // every current alert, active or resolved

Verbs

On every scope:

verb	returns	notes
Definitions()	[]AlertDefinition	the built-ins owned by the scope; in-memory
Latest(ctx)	[]*Alert	the newest retained alert per name and owner in the scope, active or resolved, ordered by message key; the system list is every alert
Alert(name)	*AlertHandle	no I/O; the alert named name whose owner is this resource, which is where a user-produced alert on it is read

On the stream handle, one selector per built-in: PartitionCount(), CompactionReadCost(), WorkerLiveness(). Each is Alert(name) with the name filled in.

On the system handle, MetricCollectorProgress() selects the installation’s collector-progress alert.

On an AlertHandle:

verb	returns	notes
Latest(ctx)	*Alert	(nil, nil) when the owner exists and nothing is retained under the key
History(ctx, limit)	[]*Alert	newest first; limit must be positive
Snapshot(ctx)	*AlertEvaluationSnapshot	read-only evaluation of a built-in under its current declared schedule policy; returns ErrScheduleNotFound for a missing schedule, ErrStreamNotFound or ErrConsumerNotFound for a missing owner; unsupported names/scopes and malformed policies return errors

A definition is metadata, never a value: Code, Name, Description, Scope, Severity. Severity is fixed per built-in; message, detail, hint, data, and At, the time the check observed the condition, change per finding and stay on the Alert.

scope	owner
MetricScopeSystem	the system
MetricScopeStream	the stream
MetricScopeConsumerGroup	the stream and group

Three built-ins are owned by a stream: partition_count, compaction_read_cost, worker_liveness. The system owns metrics_collector_progress. Each has a SQL code, so sqlstreams explain SQL0094 and its page say what an active one means. The group handle has no built-in selector: its Definitions() is empty and Alert(name) is its whole read.

CLI

sqlstreams alert latest partition_count --stream orders --output json returns the alert object, or null when no alert is retained. sqlstreams alert history partition_count --stream orders --limit 10 --output json returns an array, newest first, or [] when none are retained. Both commands exit 1 when no alert is retained. A missing owner returns its error on stderr.

Consuming the alert stream

__system.alerts is a stream like any other, and a consumer group on it is the push side: a Slack or PagerDuty hook hangs off Consume, the Latest reads are the pull side.

pager, err := client.Stream[sqlstreams.Alert](sqlstreams.AlertStreamName).Consumer("alert-pager").Register(ctx, nil)

A new group starts at the beginning of retained history, so it replays what retention holds. Declare Start: sqlstreams.Head() to hear only alerts raised after it registered, and read Latest once at startup for what is already active.

Gotchas

• The three stream alerts require two minutes of consecutive unhealthy measurements by default. Each alert config exposes the same direct fields: PendingDuration and MaximumGap default to two minutes; DisablePending: true allows immediate activation but still requires fresh evidence. Missing or stale evidence leaves recorded alerts unchanged and increments the check’s failed stream count. The rule: the newest collected sample must be younger than MaximumGap, and the alert activates once consecutive unhealthy samples with no gap wider than MaximumGap span PendingDuration. A restart gap earns no duration; a single sample never activates by waiting.
• Collector progress requires two minutes of overdue or absent completion during continuous manager lease coverage. A coverage gap restarts pending; insufficient evidence leaves the recorded alert unchanged and logs a warning. Coverage is read from worker_instance_log, so a released or crashed manager counts until its last recorded expiry (0700).
• An alert’s key is its owner’s id, so the read resolves the name first. Destroy the stream and stream.Alerts().PartitionCount().Latest(ctx) returns ErrStreamNotFound rather than the last alert; a missing group is ErrConsumerNotFound the same way. The id is also what makes an alert follow its stream through Rename.
• Nothing raises a test alert. To watch the pipeline on a healthy system, declare PartitionCountAlert: &sqlstreams.PartitionCountAlertConfig{Threshold: 1}, which alerts after a sustained count on every stream with a partition, and put the real threshold back on the next register.
• Snapshot evaluates current evidence even when the schedule is suspended. Queued checks retain their consumed policy. Its State is one of AlertEvaluationStateHealthy, AlertEvaluationStatePending, AlertEvaluationStateActive, or AlertEvaluationStateInsufficientEvidence. Finding accompanies pending/active states; Reason explains insufficient evidence for display. EvaluatedAt, ObservedAt, UnhealthySince, and ObservedDuration carry the timing, and the resolved PendingDuration, MaximumGap, and MaximumAge the policy it ran under. Nothing is persisted. Latest and History still read recorded alerts, so their results can differ.