Observer eventsCopy page

Types are exported from okmodel/observe. How to attach observers is Observability. The contract is additive inside okm.observe/1. Postgres only in this train.

A process crash yields no event: outcomes are only those this process observed. Anything that must survive a crash is an outbox table plus a relay.

Vocabulary

No event carries row values or bound parameters. keys carries only the primary-key columns of a table that opted in.

Registry

Postgres: native. Cost: transaction | batch. Proof passes (proof:writeObserver.unit).

Postgres: native. Cost: returning. Proof passes (proof:writeObserver.keys).

Postgres: native. Cost: mixed. Proof passes (proof:writeObserver.rowCount).

QueryEvent

One event per call after it settles, reads and writes. The connection prelude (set_config), BEGIN, COMMIT, and RESET ALL are library statements. They are part of the call and are not reported as their own events. With no observer the client does not build an event and does not read the clock.

type QueryEvent = {
  id: string;
  unit?: string; // inside a transaction, a batch, or an autocommit write
  seq?: number;
  dialect: "postgres";
  table: string | null;
  op: string;
  summary: string; // library-built, low cardinality, e.g. "SELECT tasks"
  fingerprint: string; // plan.fingerprint, the value inspect() already reports
  text: string; // parameterised; unsanitisable text becomes summary
  durationMs: number;
  queueMs: number | null; // null: Postgres does not report pool-queue wait
  queryMs: number;
  decodeMs: number | null; // null for a write whose SQL has no RETURNING
  rowCount: number | null;
  rowCountMode: "changed" | "matched" | "returned" | "unknown";
  route: { endpoint: string; role: "primary" | "replica" };
  error?: { kind: string; category: string; code: string; sqlstate?: string };
  tag?: string;
  limit?: { value: number; source: string };
  params?: readonly unknown[]; // only when queryObserver({ params: true })
  stack?: string; // only when queryObserver({ stack: true })
};

params and stack are omitted unless the observer opts in. No event carries row values. Tenant ids are not a separate field on QueryEvent.

Postgres: native. Cost: query|decode. Proof passes (proof:queryObserver.timing).

WriteEvent

Delivered to onWrite for each surviving write in a unit. Values never appear: settings is names only.

type WriteEvent = {
  type: "write";
  unit: string;
  seq: number;
  dialect: "postgres";
  table: string | null;
  op: "insert" | "update" | "delete" | "upsert" | "archive" | "restore" | "raw";
  rowCount: number | null;
  rowCountMode: "changed" | "matched" | "returned" | "unknown";
  keys?: readonly Record<string, unknown>[]; // primary key, only when that table opted in
  tenant: Readonly<Record<string, unknown>> | null;
  settings: readonly string[]; // names only, never values
  durationMs: number;
  tag?: string;
  source: "client" | "raw";
};

sql(), inspect(), and describe() plan a write and do not emit an event. That plan path builds observe metadata with settings: [] — it does not receive the client's with() pairs.

A typed raw(db, sql, params) write emits source: "raw", op: "raw", and table: null. A typed raw read emits no write event. onQuery sees a typed raw read or write as op: "raw" and table: null.

keys names schema tables. For each of those tables the write planner appends RETURNING of the primary key when the statement is a simple INSERT, UPDATE, or DELETE. The extra columns show in sql() and inspect(). describe() labels caller columns "caller" and appended primary-key columns "observer". A successful statement that opted in and could return the key sets keys (an empty array when no row came back). A failure omits keys. A table with no primary key, or a name that is not in the schema, is OKM1890 at connect and again when the write is planned.

Statements whose RETURNING is not terminal (a parent guard, a versioned close, an archive CTE) are not rewritten. They fill keys only when the caller already returns every primary-key column. A sortable lock statement is not a key statement. A first-or-create lookup does not attach keys.

SavepointEvent

type SavepointEvent = {
  type: "savepoint";
  unit: string;
  name: string;
  state: "released" | "rolled_back";
  depth: number;
};

OutcomeEvent

type OutcomeEvent = {
  type: "outcome";
  unit: string;
  outcome: "committed" | "rolled_back" | "unknown";
  writes: number; // surviving savepoint rollbacks
  dbTxId?: string;
};

Delivery

1. A unit's events are delivered after its COMMIT or ROLLBACK returns, in seq order, then the outcome event last. No statement-time delivery.
2. Writes inside a rolled-back savepoint are removed from the unit's surviving writes before outcome; a savepoint event with rolled_back is emitted so tooling can follow. Those writes are never delivered.
3. Outcome is tri-state: committed (COMMIT acknowledged), rolled_back (explicit rollback, or a failed statement that ended the unit), unknown (COMMIT sent and the connection lost: outcome_unknown, OKM1401). Consumers treat unknown as "maybe committed" and must be idempotent. The writes of an unknown unit keep the counts their statements reported before COMMIT. A connection lost before COMMIT is sent is rolled_back, never unknown.
4. Autocommit: a single statement is a unit of one write; outcome follows its result.
5. batch() on a driver with no per-statement signal: one unit, one outcome for the whole batch; seq still orders the statements.
6. A process crash yields no event.
7. No global order across units. Units are per transaction or batch, not per client: two units running at once on one client keep their own events, seq, and outcome.
8. A handler that throws or rejects is caught and sent to onObserverError(err, event); it never reaches the write path and never changes an outcome. Handlers are not awaited on the write path; returned promises are tracked; await observer.flush() (from writeObserver()) resolves when all tracked handler promises have settled and never throws on handler errors. The helper owns flush.
9. Backpressure: the buffer is bounded per client (default 10,000 pending events). See Buffer overflow.

writeObserver({ ... }) buffers per unit and calls exactly one of committed | rolledBack | unknown once per unit. A unit with zero surviving writes calls nothing. An observer cannot veto or alter a write. tag is 1–64 characters from [A-Za-z0-9_.:/-]. Anything else is invalid at helper construction.

Row counts

rowCount is the command-tag count the driver reported. A missing or null tag is unknown with rowCount: null. An upsert stays changed even when RETURNING ran. Every other op is returned when the statement's SQL contained RETURNING, otherwise changed.

Buffer overflow

The per-client pending-event buffer defaults to 10,000. When it overflows, the oldest unit's events are dropped and onObserverError receives OKM2200. The write path never waits on that delivery. Raise maxPending on writeObserver, or drain handlers with flush() more often.

For onQuery, the pending ceiling also defaults to 10,000 in-flight promises. Past that, the handler is not called and onObserverError receives the same OKM2200.

toOtel

toOtel(event) returns { name, attributes } and imports nothing from OpenTelemetry. name is summary. Attributes use the same names as okmodel/otel:

Parameters, tenant ids, and stacks are never attributes.