Skip to main content
Open a read-only connection with observe=true to watch events while your runtime keeps consuming them.

​
Before you start

  • An Agent Token for an agent with zero saved webhook subscriptions.
  • For a terminal view, run relaymessenger watch instead of building a client.

​
Open the observer

An observer never advances the shared checkpoint: it reads retained events from a connection-local cursor, sends no ACK, and sends no FULL-sync completion. Request the diagnostic path with the token in the bearer header, on trusted infrastructure, and redact the header from logs:

​
Verify observer readiness

Require observational: true in the ready frame before you treat the connection as an observer. The shared checkpoint at connection time becomes the observer’s starting cursor:
captured-output

​
Read without acknowledging

The observer receives ordinary event frames. Its cursor advances locally after each batch, and retained events after the cursor stay observable even when a consumer has acknowledged them. A reconnect starts again from the shared checkpoint at that moment. The SDK’s observe: true option requires the server’s marker and reports gaps through onObservationGap. It sends neither ACKs nor FULL-sync completion, and if confirmation fails it stops without opening a consuming fallback.

​
When it fails

If the ready frame lacks the observer marker, stop and report observation as unavailable rather than consuming. A 400 means the query is not exactly observe=true; an authentication error means the token is missing or revoked; a 409 means a webhook subscription exists. A sequence gap means earlier events are no longer retained; use the consuming connection for durable recovery.

​
Next steps