Event listeners
A data listener follows one connection’s stream of business changes: rows changed in a transactional database, records produced to a Kafka topic. It counts them, meters them, and hands them to briefs that run when data changes, which run a fetch when the changes you ask for arrive.
The listener itself reads only each change’s coordinates (where, what kind, which key), never its values. The run it fires is a fetch like any other: it reads the connection’s tables with the connection’s own login, reads back the rows that changed, and reports which business rules those rows conform to or break. Nothing is installed in your source by FACE.
It is not the Metadata listener on a connection in Settings › Integrations › Systems, which watches a source for schema changes. The two are switched on separately.
Which sources
| Source | How it listens | What you install |
|---|---|---|
| PostgreSQL | LISTEN on a channel, then reads a change-event ledger table | the ledger, once, by your DBA (below) |
| Apache Kafka | reads every partition of the connection’s topics from the latest offsets | nothing |
Other source types have no data listener. A connection bound to a self-hosted runner is reported NOT LISTENING with that reason: listening runs on the managed runner only, and a connection bound to a runner is never moved to another one.
PostgreSQL: the change-event ledger
The listener needs your database to say what changed. It uses an ordinary trigger, a
ledger table and NOTIFY, not logical replication:
- Logical replication needs
wal_level=logical, a role withREPLICATIONthat streams every column of every published table, and a replication slot. A slot whose consumer is away keeps WAL without limit, which can fill the database’s disk. - The ledger costs one small row per change and keeps least privilege: the connection’s
login only needs
SELECTon one more table.NOTIFYis only a wake-up call; a listener that was disconnected reads every row after the last one it saw, so nothing is lost.
Your database administrator runs this once, adapting the table list to yours. Each
trigger names its table’s business-key column; the ledger records the schema-qualified
table and that column, so an event-fired run can read the changed row back. Grant the
connection’s login SELECT on the ledger and on the tables it reads.
CREATE TABLE ops.change_events (
seq bigserial PRIMARY KEY,
occurred_at timestamptz NOT NULL DEFAULT clock_timestamp(),
table_name text NOT NULL, -- schema.table
op text NOT NULL CHECK (op IN ('INSERT', 'UPDATE', 'DELETE')),
key_column text NOT NULL,
row_key text NOT NULL,
provenance text NOT NULL DEFAULT ''
);
-- TG_ARGV[0] names the table's business-key column.
CREATE FUNCTION ops.record_change() RETURNS trigger LANGUAGE plpgsql AS $$
DECLARE k text; s bigint;
BEGIN
IF TG_OP = 'DELETE' THEN k := to_jsonb(OLD) ->> TG_ARGV[0];
ELSE k := to_jsonb(NEW) ->> TG_ARGV[0]; END IF;
INSERT INTO ops.change_events (table_name, op, key_column, row_key)
VALUES (TG_TABLE_SCHEMA || '.' || TG_TABLE_NAME, TG_OP, TG_ARGV[0], COALESCE(k, ''))
RETURNING seq INTO s;
PERFORM pg_notify('face_ops_events', s::text);
RETURN NULL;
END;
$$;
CREATE TRIGGER shipments_change AFTER INSERT OR UPDATE OR DELETE ON ops.shipments
FOR EACH ROW EXECUTE FUNCTION ops.record_change('shipment_id');
GRANT SELECT ON ops.change_events TO face_reader;Table and column names must be lower case. The listener reads ops.change_events and
listens on face_ops_events by default. To use other names, set two properties on the
connection: face.events.ledger (schema.table, lower case) and face.events.channel.
The ledger grows by one row per change, so delete old rows on your own schedule; the
listener only reads rows newer than the last one it saw.
Apache Kafka
Nothing to install. The listener reads the connection’s topics (its Topics prefix filter, or every non-internal topic) without a consumer group, so it never moves an offset your own consumers depend on. It starts at each partition’s latest offset: it reports what is produced while it runs, not the topic’s history. A Kafka event carries its topic and record key; there is no row to read back, so the run’s rule results cite record keys.
Set up an event-triggered analysis
The listener has one switch: the briefs that run when its data changes. Saving an active brief of that kind turns the connection’s listener on; pausing or deleting the last one on that connection turns it off.
Check the connection
In Settings › Integrations › Systems, the PostgreSQL connection must test green with the login that will read it, and the ledger must be installed (above). A Kafka connection needs nothing more. Both must meet the security requirements.
Open a new brief
Open Briefs under Fetch in the rail and select CREATE NEW SCHEDULE. The editor is titled New brief. Under What to ask, type the question each run asks, for example one about freight billing, or pick one under Start from a common question.
Choose When data changes
Under When, select When data changes. The time options give way to the event settings.
Say which changes count
- Listen to: the PostgreSQL or Kafka connection. Only those types are listed.
- Run after this many events: for example
1to analyse every change, or5for a batch. - Wait for more events (seconds): so a burst of changes becomes one run.
- At most one run every (minutes): the cooldown; never less than one minute.
- Only tables or topics starting with: for example
ops.freight_invoices; empty means all. - Only this change: for example INSERT; Any change means all.
The note under these settings says what saving does: it turns the connection’s data listener on, on the managed runner, and installs nothing.
Under Where to look, tick the connections each run reads.
Save
Select Save brief. On Briefs, its card shows the EVENT chip beside ACTIVE, and NEXT RUN reads On the next matching event.
Watch the listener
DATA LISTENERS heads the Briefs page, one row per connection: the state the runner last reported (LISTENING, STARTING, DEGRADED, NOT LISTENING with the reason, or OFF), how it reads, the events and bytes it read, how long it has listened, and Metered to. Within about 15 seconds of saving, the row reads LISTENING.
Read what the run found
When matching events arrive, the card’s LAST TRIGGER shows how many events fired the run and the first five of them (table or topic, operation, key), how many of their rows were read back, the run’s transaction id and its outcome. When the run’s analysis finishes, a few minutes later, RULE RESULTS FROM THESE CHANGES lists each rule the triggering rows bear on: its verdict (Drift, Shadow, Missing or Aligned), its id and category, and Rows: the keys of the rows it is about. The same rules appear among the business rules on Why.
What an event-fired run reports
A brief that runs when data changes fires a fetch with the events that fired it (the first and the newest,
at most 25) and the connection that saw them. The runner reads back the rows those
events name, at most 50, with the connection’s own login: a parameterised SELECT by
key on each table, and a key whose row is gone (deleted, or pruned since) is reported as
gone, never guessed. The analysis receives them as the changes that triggered the run
and gives each rule it finds the keys of the triggering rows it is about.
Only keys that really fired the run are kept: a key the analysis cites that was not a triggering row is dropped, and a rule that cites none is not attributed to the run. Each result is shown with the rows it rests on, so you can check it against the source. An event-fired run never reuses an earlier answer to the same question: its subject is the rows that fired it.
Metering
A listener’s usage is recorded in FACE’s usage ledger, against the purchaser of the person who created the brief that switched it on:
| Metric | Quantity |
|---|---|
listener_events | events read |
listener_seconds | seconds spent listening |
Each record is written once: a repeated report or a restarted control plane never records the same usage twice. Someone not placed on a purchaser’s account is metered to the platform account, and Briefs says so next to Metered to. The bytes read are shown on Briefs and are not a billed metric. The fetch an event fires is metered as any fetch is.
These two metrics are recorded and shown; how they are priced on a bill is set by your plan.
The platform’s own estate
The quickstart PostgreSQL in the data-systems namespace of Runink’s platform cluster runs
with this ledger installed, and a transactional writer (the writer sidecar beside the
database) keeps the quickstart estate moving. Every row the writer produces carries its own ids (SO-9…, SHP-9…, SINV-9…,
CLM-9…) and a provenance column naming the quickstart estate.
| Table | Rule its rows exercise | How often the writer breaks it |
|---|---|---|
ops.freight_invoices | billed rate per mile equals the carrier’s contract rate (the MySQL estate’s freight.rate_contracts) | about 12% of invoices bill 8–18% over |
ops.shipments | delivered by the planned time | about 15% of deliveries are late |
ops.claims | filed within the contract’s claim window (60, 90 or 120 days) | about 15% of claims are filed on a July 2026 shipment, past its window |
ops.inventory_positions | on hand stays above the reorder point | order lines draw stock down and restocking lags, so a position sits below it for a while |
Every 20 seconds the writer creates orders and their lines, ships, delivers and invoices
shipments, files claims and restocks low positions; most rows conform. A brief that runs
when data changes, asking about freight billing, filtered to ops.freight_invoices and INSERT, has an
off-contract invoice to find within minutes.