Observability

Observability provides real-time and historical insight into every interaction passing through the system and the current state of your users.

Events

An event is a record of a single interaction that passed through the system. Events are immutable, capturing exactly what happened at that moment along with the full context of the interaction.

What generates an event

Any interaction that passes through MonetizationOS produces an event. This includes HTTP requests such as access checks, surface decisions, and offer redemptions, workflow actions triggered by custom logic, and incoming data from external sources such as Stripe webhooks.

Event user

Events produced by user-initiated requests, such as access checks, surface decisions, and offer redemptions, are recorded against a user identity that is either provided explicitly by the caller or resolved by middleware.

For workflows that do not have access to an identity, such as endpoint workflows, the user associated with an event can be set explicitly using the utils.identity.setForObservability() utility function.

Workflow executions and logs

When a workflow runs as part of an event, each execution is tracked and attached to it. This records which workflows ran, the order they executed in, how long each took, and whether they succeeded, produced a warning, or failed.

Workflows can emit log output during execution using console.log or other console.* calls. These logs are captured automatically and attached to the event, making it possible to trace the internal behavior of a workflow for any specific event without needing external logging infrastructure. Logs can be inspected in the workflow execution details of the corresponding event.

Event details

Each event exposes additional data relevant to the interaction. This includes the input and output payloads, request context such as the subject identity, geographic origin, and device information, and the outcome of the event.

Certain event types carry contextual data specific to what occurred. A surface decision, for example, will include the experiences that were generated and the offers resolved for each slot.

Lineage

Events are connected through a shared lineage when one interaction triggers further events. For example, an incoming webhook may trigger a workflow action, which in turn produces its own event. All events in that chain share a lineage identifier, allowing you to trace the full sequence from origin to final outcome.

Users

Each user observed across your organization accumulates a record of everything associated with them over time.

Each user record includes:

• Identity information: authentication type, identifier, and temporal metadata such as when they were first seen and last active
• Events: a full history of every event triggered by that user
• Plans: the plans currently active for the user and a history of how they have changed over time
• Counters: usage tracked against metered feature properties
• Custom Data: arbitrary data written against the user by your workflows
• Links: connections to other identities written from workflows, such as an anonymous session linked to an authenticated account

Data retention

Anonymous user data expires after 50 days of inactivity, and authenticated user data is retained for 365 days. Events are retained for a period determined by the plan your organization is on.

Usage metrics

Metrics provides an aggregated view of usage across your organization over selectable time periods, covering read and write operation counts and the total number of authenticated users and anonymous sessions.

Learn More

Getting Started guides

Admin Guides

References

Workflow references

API references