Versioning

Every change to a published rule generates a new version. Versioning ensures traceability, recording who changed it, when, and what changed, and allows you to revert to previous versions when needed.

Status

Each version can be in one of the following states:

• Draft: can be modified freely. Only takes effect on the API after being published.
• In observation: published in parallel with the active version, deciding nothing. Described in Observation.
• Active: published version in use by the API. Only one active version per rule. Cannot be modified: changes generate a new version.
• Inactive: was active at some point. Kept for traceability and can be reactivated at any time.
• Removed: hidden in the panel but preserved in the history. Still visible when inspecting older events that used it.

A rule allows at most one active version and one version in observation at the same time.

Comparison and publishing

Publishing a version requires reviewing the changes against the active version beforehand. The comparison screen opens positioned between the active version and the version to be published, and the publish button is in the comparison itself, after the review. A rule with no published version is flagged as such and only takes effect after the first publication.

The comparison covers the conditions and the actions. Each row corresponds to a condition: colored rows indicate the ones that changed, and a label identifies the change (added, removed, reordered, or altered). In the actions column, a struck-through action no longer applies and the one that replaces it appears after the arrow; an action marked with + is new. The comparison exposes the exact effect of publishing before the version takes effect.

Observation

A version can be published in observation (shadow) before taking effect. In this state it runs in parallel with the active version, over the same real events, and nothing it produces changes the event’s outcome: the decision remains the active version’s. The lifecycle becomes draft, observation and active.

An inactive version can also be put in observation, which allows evaluating a version already replaced without putting it back in charge of decisions. The active version is the only one that cannot be observed, since it is already deciding.

A version in observation is immutable, like the active one: editing it creates a new draft. The version promoted is exactly the one that was observed, with no rewriting of the actions.

Observed outputs

Observation is selective. When publishing, you mark which outputs you want to track. Each marked output is written to the same event, in a field with the _shadow suffix, next to the value the active version wrote. Unmarked outputs are discarded along with the rest of the run.

Since both values sit on the same event, the comparison uses the existing screens: filters in Explore, metrics and dashboards compare the field and its observed twin with no extra configuration.

Observed outputs can be changed at any time, without republishing the version. A version that fills no field has no outputs to observe and cannot be published in observation.

Every processed event also records the version in observation that processed it, besides the name and version of the active rule. Without that record it would not be possible to attribute an observed value to the version that wrote it, since every revision is a new version.

What observation does not run

A version in observation does not change the shared state that other runs read:

• Actions that write to lists are suppressed. Conditions that consult lists keep reading the real list, so a rule whose behavior is to feed a list and then consult it is observed approximately, not exactly.
• The analyses recorded by the version in observation sit in windows of their own, separate from those the active version feeds and consults.

The observation’s windows start empty and need a full retention of traffic before they mean anything. When the version is promoted to active, the windows start over from zero for the same reason.

In an event type with a version in observation, the event becomes visible in queries some moments after being received, rather than immediately, because the write waits for the observed run so both values travel in the same record.

History

Each rule has a history of the actions performed on its versions: creation, editing, publishing, publishing in observation, withdrawal from observation, replacement, unpublishing and archiving. Each entry records the version, the author and the moment.

The history shows the most recent actions and keeps the rest collapsed. The rule’s version list is the full record.

Traceability in events

Every event processed by a rule records the rule’s name and the number of the version that processed it, plus the version in observation, when there is one. This makes it possible to reconstruct later which logic produced each value, even when the version has since been replaced or removed.