Observers

Observers are the processing units that consume events from an event sequence and produce side effects or projections. Chronicle supports three kinds of observer: reactors (side effects), reducers (compute read model state), and projections (declarative read model builders). Each observer tracks its position in the event sequence and pauses a partition when it encounters a failure.

list

Lists all observers registered in the specified event store and namespace, including their current state, quarantine status, and sequence position.

cratis chronicle observers list

Options

Flag	Description
`-e, --event-store <NAME>`	Event store to inspect. Defaults to `default`.
`-n, --namespace <NAME>`	Namespace to inspect. Defaults to `Default`.
`-t, --type <TYPE>`	Filter by observer type: `all`, `reactor`, `reducer`, `projection`. Defaults to `all`.

Examples

List all observers:

cratis chronicle observers list

List only projection observers:

cratis chronicle observers list --type projection

List observers in plain format for scripting:

cratis chronicle observers list --output plain

Get observer IDs for piping:

cratis chronicle observers list -q

show

Shows detailed information about a single observer, including its event type subscriptions, current state, and sequence position.

cratis chronicle observers show <OBSERVER_ID>

Arguments

Argument	Description
`OBSERVER_ID`	The observer identifier. Use `observers list -q` to retrieve identifiers.

Options

Flag	Description
`-e, --event-store <NAME>`	Event store to inspect. Defaults to `default`.
`-n, --namespace <NAME>`	Namespace to inspect. Defaults to `Default`.
`--sequence <NAME>`	Event sequence the observer reads from. Defaults to the event log.

Examples

Show observer details in a table:

cratis chronicle observers show my-observer-id

Get full observer detail as JSON:

cratis chronicle observers show my-observer-id -o json

replay

Replays an observer from sequence number zero, re-processing every event it subscribes to. This is a destructive operation: the observer discards all accumulated state and rebuilds it from scratch.

Use replay only as a last resort — for example, when an observer’s read model is known to be corrupt and cannot be recovered by a partition retry.

cratis chronicle observers replay <OBSERVER_ID>

The command prompts for confirmation before proceeding. Pass --yes to skip the prompt in automated workflows.

Arguments

Argument	Description
`OBSERVER_ID`	The observer to replay.

Options

Flag	Description
`-e, --event-store <NAME>`	Event store. Defaults to `default`.
`-n, --namespace <NAME>`	Namespace. Defaults to `Default`.
`-y, --yes`	Skip confirmation prompt.

Examples

Replay an observer interactively:

cratis chronicle observers replay my-observer-id

Replay without prompting (automation):

cratis chronicle observers replay my-observer-id --yes

Replay all observers (use with caution):

cratis chronicle observers list -q | xargs -I {} cratis chronicle observers replay {} --yes

replay-partition

Replays a single partition of an observer from sequence number zero for that partition only. This is less disruptive than a full replay because it leaves all other partitions intact.

cratis chronicle observers replay-partition <OBSERVER_ID> <PARTITION>

The command prompts for confirmation before proceeding.

Arguments

Argument	Description
`OBSERVER_ID`	The observer whose partition to replay.
`PARTITION`	The event source ID identifying the partition.

Options

Flag	Description
`-e, --event-store <NAME>`	Event store. Defaults to `default`.
`-n, --namespace <NAME>`	Namespace. Defaults to `Default`.
`-y, --yes`	Skip confirmation prompt.

Examples

Replay a specific partition:

cratis chronicle observers replay-partition my-observer-id user-42

retry-partition

Retries a failed partition without replaying it from the beginning. The observer attempts to process the event that last caused the failure. Use this after fixing the underlying bug — it is the preferred recovery path for transient errors and corrected application bugs.

cratis chronicle observers retry-partition <OBSERVER_ID> <PARTITION>

Arguments

Argument	Description
`OBSERVER_ID`	The observer whose partition to retry.
`PARTITION`	The event source ID identifying the failed partition.

Options

Flag	Description
`-e, --event-store <NAME>`	Event store. Defaults to `default`.
`-n, --namespace <NAME>`	Namespace. Defaults to `Default`.
`-y, --yes`	Skip confirmation prompt.

Examples

Retry a failed partition:

cratis chronicle observers retry-partition my-observer-id user-42

retry-failed-partitions

Retries every failed partition of an observer in one operation, instead of retrying them one at a time with retry-partition. The kernel starts recovery a bounded batch of partitions at a time, so retrying many of them never overwhelms the observer or the event store. The command returns as soon as recovery is started and reports how many partitions were failed at that moment; it does not wait for recovery to finish. Check progress with failed-partitions list.

cratis chronicle observers retry-failed-partitions <OBSERVER_ID>

Arguments

Argument	Description
`OBSERVER_ID`	The observer whose failed partitions to retry.

Options

Flag	Description
`-e, --event-store <NAME>`	Event store. Defaults to `default`.
`-n, --namespace <NAME>`	Namespace. Defaults to `Default`.
`--sequence <ID>`	Event sequence name. Defaults to `event-log`.
`-y, --yes`	Skip confirmation prompt.

Examples

Retry all failed partitions of an observer:

cratis chronicle observers retry-failed-partitions my-observer-id

An observer with no failed partitions is reported as such and exits zero, because there was nothing to do. Requires Chronicle 19.80.0 or later.

clear-partition-quarantine

Clears the quarantine of one failed partition. A partition is quarantined after it exhausts its retry attempts; retry-partition refuses it until the quarantine is cleared. The command resets the partition’s retry budget, keeps its attempt history, and by default starts a retry from the failed sequence number.

cratis chronicle observers clear-partition-quarantine <OBSERVER_ID> <PARTITION>

Requires Chronicle 19.29.0 or later. The command prompts for confirmation before proceeding.

Arguments

Argument	Description
`OBSERVER_ID`	The observer whose partition to release.
`PARTITION`	The event source ID identifying the quarantined partition.

Options

Flag	Description
`--no-retry`	Only clear the quarantine; do not start a retry.
`-e, --event-store <NAME>`	Event store. Defaults to `default`.
`-n, --namespace <NAME>`	Namespace. Defaults to `Default`.
`--sequence <NAME>`	Event sequence. Defaults to `event-log`.
`-y, --yes`	Skip confirmation prompt.

The command exits non-zero when nothing was cleared: the partition is not found, it is not quarantined (use retry-partition), or the observer itself is quarantined so the retry did not start (run clear-quarantine on the observer, then retry-partition).

Examples

cratis chronicle observers clear-partition-quarantine my-observer-id user-42
cratis chronicle observers clear-partition-quarantine my-observer-id user-42 --no-retry

clear-quarantine

Clears quarantine for a quarantined observer so it can resume processing. This is observer-level only: partitions that are individually quarantined stay quarantined. Use clear-partition-quarantine for those.

cratis chronicle observers clear-quarantine <OBSERVER_ID>

The command prompts for confirmation before proceeding.

Arguments

Argument	Description
`OBSERVER_ID`	The observer whose quarantine should be cleared.

Options

Flag	Description
`-e, --event-store <NAME>`	Event store. Defaults to `default`.
`-n, --namespace <NAME>`	Namespace. Defaults to `Default`.
`--sequence <NAME>`	Event sequence. Defaults to `event-log`.
`-y, --yes`	Skip confirmation prompt.

Examples

Clear quarantine for an observer:

cratis chronicle observers clear-quarantine my-observer-id

Troubleshooting Workflow

Use this sequence when an observer appears stuck, behind, or failing:

Check the observer list for state and sequence numbers:
Terminal window
```
cratis chronicle observers list --output plain
```
Inspect the specific observer for detailed state:
Terminal window
```
cratis chronicle observers show my-observer-id -o json
```

Check for failed partitions:

cratis chronicle failed-partitions list --output plain

Inspect the specific failed partition and its error:

cratis chronicle failed-partitions show my-observer-id user-42

Fix the underlying application bug, then retry the partition:
Terminal window
```
cratis chronicle observers retry-partition my-observer-id user-42
```
If the read model state is known to be corrupt and cannot be recovered by retry, replay the partition:
Terminal window
```
cratis chronicle observers replay-partition my-observer-id user-42
```
Only as a final resort — if all partitions are corrupt or the observer schema changed incompatibly — replay the entire observer:
Terminal window
```
cratis chronicle observers replay my-observer-id
```