Tracking Event Publisher Versions

When sending events to Retraced, consumers of the Publisher API may send event metadata like the name and version of the vendor component that is sending the events. A minimal event payload that includes this metadata might look like

{
  "action": "user.login",
  "crud": "c",
  "group": {
    "id": "7890123",
    "name": "some.customer"
  },
  "actor": {
    "id": "123456",
    "name": "user@example.com"
  },
  "component": "authentication-api",
  "version": "ae242df"
}

Where component describes a single versioned piece of a architecture like authentication-api or spreadsheet-processor and version is usually one of

• A git SHA of the component’s source code as in ae242df
• A semantic version for the component as in 1.0.3
• A build number of the component as in 129

Sending this information to Retraced will allow Retraced to give better guarantees about time windows during which an event did not occur.

Example

To better understand how this works, consider the following stream of events, in which the password.change action at 12:35 is the very first password.change event seen in Retraced, because a recent new release of the vendor app is the first to start tracking password.change events.

Without any info about app versions, we can still say for certain that

• no password.change events occured between 12:35 and 12:52.

We cannot say anything about whether or not any password.change events occurred before 12:35, because we have to assume that the vendor application was not publishing these events until we see the first one at 12:35.

Since we know the version of the component sending each event, we can know for sure that the app version that sends password.change events was sending email.change events as early as 12:01. In addition to what we knew before, that

• no password.change events occured between 12:35 and 12:52

we now can also guarantee that

• no password.change events occurred between 12:01 and 12:35.

Note: Being able to make these guarantees relies on an assumption that application versions change at the same time, and that there are never multiple versions of a single component running in parallel for significant periods of time. If Publisher API consumers rely on canary deploys or staged rollouts over several days, then component names will need to be rotated during the rollout.

Using SDKs

If you are using one of the official Retraced SDKs, you can provide the version and component fields when the client is initialized, and they will be sent for every event.