Understanding events in Orb

Last updated: September 13, 2024

What are events in Orb?

In Orb, an event represents a usage action or measurement within your system that can be tracked and used for billing. Events are the foundation of Orb’s usage-based billing system, allowing you to monitor, quantify, and bill for your platform’s usage.

How are events used in billing?

Events in Orb are collected and aggregated to calculate billable metrics. These metrics are created by filtering and aggregating events to determine the quantity of usage to bill your customers.

Deciding on your event structure

When determining your event structure, consider the following:

  • Key actions or metrics that reflect how customers use your product

  • Properties that will be useful for reporting, billing, or auditing

  • Additional properties that could be helpful for future use cases

Examples of events​

Typically, events map to one of the following:

  1. User action: When a user triggers an action in your application, you may want to send an event to record it. Depending on your use case, this might capture a user log in, file download, triggered verification, or a refreshed dashboard.

  2. Background task: In many cases, a user action will trigger an asynchronous task that executes in the background. For example, you might log an event every time a job finishes, an image is processed, or a model is trained.

  3. Regular heartbeat: Especially if you’re an infrastructure provider, you may want to send an event over a regular time interval that indicates that a resource is active alongside any metadata over that timeframe.

The following table provides some examples of events you might send to Orb based on the nature of your business to illustrate how broadly an event can vary. In each case, the properties that you send alongside these names will determine your event's full semantics.

Business DomainEvent examples

Financial APIs

transaction_processed
payment_authorized
account_linked

Cloud & Data Infrastructure

cluster_compute
offline_storage
network_ingress

Communications

message_transmitted
call_processed
recording_uploaded

Developer Tooling

async_job_run
container_uptime
pipeline_execution

Integrations

source_connected
batch_events_synced
connection_health_refreshed

Analytics

active_user_login
event_ingested
query_compute_job

Can I view events in Orb?

Yes, events ingested in Orb can be viewed on the Events page within your Orb account. Each event can be clicked on to see its properties, associated billable metrics, and any invoices to which it has been attributed.

To begin ingesting events into Orb, check out our ingestion quickstart guide. For additional details on event ingestion, refer to our documentation.