Skip to content
oto
Menu
Overview
IntroductionConceptsArchitectureContributingReleasing
Design
oto — System Design ProposalDomain Research: Prometheus Alertmanager + Slackoto — Red-Team Memooto — SCOPE BOUNDARY (the doctrine)oto — BINDING SPECIFICATION v1
ADRs
0001 — PostgreSQL is the sole datastore; River is the job queue0002 — `internal/<domain>/{api,service,repository,domain}` with three model sets0003 — Alert, AlertOccurrence and AlertEvent are three distinct entities0004 — oto owns alert identity; Alertmanager's fingerprint is recomputed, not trusted0005 — A durable group key, and the AlertGroup generation owns the Slack thread0006 — The Alertmanager API v2 reconciler is mandatory, not optional0007 — Webhook response contract: 202 or 503. Never 4xx, never 429.0008 — Slack: `chat.update` in place is primary; threads are secondary; one colour attachment0009 — Rule definitions are snapshotted and versioned at fire time0010 — Server-Sent Events with durable resume, not WebSocket0011 — Validation is seven layers with two opposite trust models0012 — Pastel product chrome, saturated colour reserved exclusively for state0013 — oto is alert-first: the Flight Recorder Test defines the scope boundary0014 — Postgres is the only store; no TSDB or column store in v10015 — No stream processor; River in Postgres is the pipeline0016 — Cluster context arrives via MCP, on demand; never the Kubernetes event firehose0017 — Alertmanager-style matchers, not CEL; and a filter AST that keeps the door open0018 — Slack distribution: a customer-built internal app, credentials in config0019 — MIT licence0020 — Broadcast the transitions that must be seen0021 — Correctness and testing strategy0022 — Length-prefixed identity pre-images0023 — Terminal thread states are decided first, and the send is three phases0024 — Retention defaults, what each boundary destroys, and cold storage0025 — The alert list resolves rule snapshots in a batch, not per row0026 — `refire_grace` and the flap thresholds, derived from a real rule corpus0027 — Delivery drills: a synthetic alert through the real pipeline, and the mark that keeps it out of the numbers0028 — Non-urgency motion: one-shot events, honest activity loops, and nothing else0029 — Type and radius scales, read off the product rather than drawn for it0030 — Tier A repainted as Washi & Ink / Konshi Sutra; accent moves to beni0031 — Sharp corners and higher-contrast grid lines within Washi & Ink; colours unchanged0032 — Dark-theme accent moves from beni to plum-blossom blue-and-white; light untouched0033 — The alert filters are a toolbar above the table, not a panel in the rail0034 — Notifications is a destination, and the record it keeps is readable0035 — Decorative ink as a masked wash: one primitive, four motifs, and the placements it is refused0036 — AlertOccurrence becomes AlertCase, and `case` is argued against FR-1 by name0037 — A Wording is Liquid, and the structure around it stays oto's0038 — The group key is derived from the alert's own labels0039 — Group close stays activity-driven0040 — A Case is `open` or `closed`, and it is never reopened0041 — The Alert/Case allocation, and the one rule that decides it0042 — Storm damping is removed, because the defence was built before its object0043 — The Slack action row renders five elements, and the fifth is the snooze pair0044 — A count condition is a silence the operator asked for, and `below_threshold` is how oto says so0045 — A Case is a conversation, and one Slack thread per alert is the accepted cost0046 — Corners round again: ADR 0031's radius override is reversed0047 — A channel answers to a connection, and Slack gets two scopes back0048 — A Wording is spelled by its channel, and the marks in between are oto's0049 — A Wording is selected by its own clause, not by a route0050 — A NotificationTemplate is one whole message, and its policy says which one0051 — A `raw` template owns the whole message, and a template may carry its replies0052 — An Incident is drawn over Cases, and its response is handed off0053 — An Investigator reads, proposes, and never decides delivery0054 — A Remedy earns the write path0055 — An incident-tool integration is data or a bridge, never code inside oto0056 — A Case the upstream stopped speaking about expires, and says why
Setup
Configuration referenceReaching an incident tool: the envelope, a mapping, or a bridgeInvestigatorsRemediesConnecting oto to SlackThe live Slack verification runTuning otoConnecting oto to VictoriaMetrics (vmalert)The generic webhook and `oto.notification.v1`
Runbooks
oto runbooksAlert search — optional partial/substring matching on alert namesoto_clock_skew_secondsoto_delivery_claim_lost_totaloto_ingest_accepted_totaloto_ingest_alerts_totaloto_ingest_duplicate_totaloto_ingest_duration_secondsoto_ingest_fingerprint_mismatch_totaloto_ingest_process_duration_secondsoto_ingest_rejected_totaloto_ingest_shed_totaloto_job_duration_secondsoto_job_queue_depthoto_jobs_dead_totaloto_jobs_enqueued_totaloto_jobs_failed_totaloto_jobs_panics_totaloto_jobs_snoozed_totaloto_jobs_started_totaloto_jobs_succeeded_totaloto_jobs_unknown_version_totaloto_render_invalid_totaloto_slack_unknown_action_totaloto_stream_connectionsoto_stream_events_coalesced_totaloto_stream_events_dropped_totaloto_stream_events_fetched_totaloto_stream_events_published_totaloto_stream_fetch_errors_totaloto_stream_listener_reconnects_totaloto_stream_notify_malformed_totaloto_stream_notify_received_totaloto_stream_poll_recovered_totaloto_stream_resync_totaloto_thread_gap_recovered_totaloto_thread_head_wait_secondsoto_thread_order_decisions_total

oto_ingest_rejected_total
Type counter
Labels reason — the closed ingest_rejections_reason_ck enum
Registered in internal/ingestion/service/metrics.go
Alertable yes
Rule OtoIngestRejecting in deploy/prometheus/oto-rules.yaml

What it counts

Section titled “What it counts”

Observations oto refused to normalise. Every increment has a row behind it in ingest_rejections, carrying the offending element post-redaction. oto never silently drops (§C.9.1) — that row is what makes answering 202 for a partially bad payload legitimate.

The reasons, and what each one means

Section titled “The reasons, and what each one means”
reason Meaning Alert kept?
too_many_labels more than MaxLabelsPerAlert labels (B3) no
label_name_too_large a label name over cap (B4) no
label_value_too_large a label value, or alertname, over cap (B5, B11) no
labelset_too_large the whole serialised set over cap (B6) no
too_many_annotations excess annotations (B7) yes, excess dropped
annotation_too_large one annotation over cap (B8) yes, value truncated
annotation_unstorable an annotation carrying U+0000 or invalid UTF-8 (B19) yes, value’s bad code points replaced with U+FFFD; an annotation with an unstorable name is dropped
invalid_label_name not a valid Prometheus label name (B9) no
invalid_label_value a label value Postgres cannot store — U+0000 or invalid UTF-8 (B18) no
missing_alertname no alertname (B10) no
timestamp_out_of_window upstream clock disagrees past what oto will model (B12 drops, B13 clamps) mixed
too_many_alerts batch truncated at MaxAlertsPerBatch (B2) partly
body_too_large the only rejection answering 413 (B1) no
undecodable not the webhook envelope at all — the only rejection answering 400 (B16) no
unknown_source soft-deleted source, or push_enabled = false no

What to check

Section titled “What to check”
  1. GET /api/v1/sources/{id} rejection feed, or ingest_rejections directly, filtered to reason and the partition for the hour in question — received_at is the partition key, so “what happened at 02:14” touches one partition.
  2. The raw column: the actual element that was refused, already redacted. This is the evidence; read it before theorising.

What to do, by shape

Section titled “What to do, by shape”
  • undecodable or body_too_large climbing: somebody put a custom payload: template on the webhook receiver, or is posting something other than Alertmanager v4. Remove the template — oto requires the stock envelope.
  • unknown_source: the receiver is pointed at a source id that oto will not serve. Re-enable push_enabled, or repoint Alertmanager at a live source.
  • too_many_alerts: raise group_by cardinality upstream or accept truncation; check docs/setup/tuning.md before changing the cap.
  • timestamp_out_of_window: this is a clock problem, not a payload problem — see oto_clock_skew_seconds.
  • Label/annotation caps: usually one noisy rule attaching a stack trace as a label. Fix the rule; the caps exist so one rule cannot make the store unqueryable.
  • invalid_label_value or annotation_unstorable: an upstream is putting raw bytes into a label or annotation — almost always label_replace over log-, exporter- or command-output-derived text, where a U+0000 or a byte-wise truncation of a multi-byte character survived. These are not decoding problems: the payload parsed fine, and one field carried bytes Postgres cannot store in a UTF8 database. Fix the rule that builds the value. Note the two are not interchangeable — invalid_label_value means an alert is missing from the timeline (a label value is identity, and oto will not rewrite an identity in order to store it), while annotation_unstorable means the alert is there with one altered sentence.