Versioning

Every change to a published rule or analysis 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.

The mechanics are the same in both cases: a published version is immutable, editing starts from it into a draft, and publishing replaces what is live. What differs for an analysis is covered in Analysis versions.

Status

Each version can be in one of the following states:

• Draft: can be modified freely. Only takes effect 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. 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 or an analysis allows at most one active version and one version in observation at the same time. A published version shows the New version from this one button in place of the edit button, and states that it cannot be edited.

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.

In an analysis, each row corresponds to a cell, with the previous and the new value of each changed setting.

Conditions met

Each condition of a rule version records how many times it was met on each day, shown on the condition itself alongside the period’s total runs. The reading distinguishes three situations: the day the rule received no traffic, the day it ran without the condition being met, and the day it was met at least once.

The count locates the condition that is never met, whether because the expression does not match real traffic or because an earlier condition already filled the field it tests. A condition that is not met even once since publication is a candidate for review before the next version.

The count starts at the version’s publication and considers only real events: simulations are left out. A newly published version therefore starts with no reading.

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, such that 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.

Analysis versions

An analysis follows the same cycle as a rule, with three particularities.

Every edit to a published analysis, whether a cell or the order of the cascade, creates a draft, and publishing takes the whole set live at once. There is no publishing of an isolated cell: the cascade is published as a whole, so the cells never sit in different versions from one another.

An analysis allows several drafts at the same time, each starting from the version it came from. The analysis page shows the open drafts and the path to each one.

Changing what a cell measures or the window in which it accumulates discards the history already accumulated by that cell, which starts empty again and needs a full retention of traffic before it means anything again. The comparison flags this consequence before publishing, and confirmation is requested at the moment of the change. The analysis’s remaining cells keep their windows.

History

Each rule and each analysis 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 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.

The version of the analysis that decided an event is recorded by the run analysis action, in the Version target.