Events and metrics
A single usage event sent to Orb typically corresponds to either a user-triggered action or an axis of measurement, depending on your business. Each event is labeled with anevent_name, which conceptually identifies the action taken, as well as a user-defined dictionary of properties. Metrics are assembled by querying over events (of potentially different event_name), and can flexibly filter and aggregate on any property of the underlying events.
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.
Event volume and concurrency
Orb’s ingestion API is designed to manage high-volume, real-time use cases. Each individual call supports sending a batch of events. Individual ingestion requests can also be sent concurrently, which is useful in environments with multiple distributed reporters sending data to Orb that don’t require coordination. Orb provides per-event idempotency through the API to guarantee that duplicates are never processed within the account grace period. By default, Orb limits the request size to 500 events per batch. By default, the ingestion API is rate limited to 10,000 events per minute, but this is a default rather than a hard ceiling—please give our team a heads up if you plan to continuously send higher volumes, so that we may raise your limit and provision dedicated throughput capacity. The ingestion API (regardless of the integration mechanism) is designed to scale to tens of millions of events per day, and as your volume grows into the thousands of events per second, see the guide on high throughput ingestion for best practices, including when it’s worth considering Orb’s hosted rollups product for pre-aggregating extremely high-volume event streams while still providing the same idempotency and real-time guarantees. To ensure that test mode workloads do not affect live mode availability or performance, the ingestion API will be limited to 2000 events per minute and 10 requests per second for test mode events. Note that significantly higher throughput, by orders of magnitude, is available in production environments.Determining event schema
Metadata passed in viaproperties to Orb does not have to conform to an up-front decided schema, and you can specify any number of tags or labels that might be relevant to billing. Each event should include properties required to compute an aggregate on the basis of those events.
You’re encouraged to send additional metadata, even if it’s not immediately useful for billing in the short-term. Additional event properties may be used for future metrics you want to build, or formatting invoices (e.g. if you provide a region property that doesn’t affect prices, your invoices may still employ it for grouping line items). Sending those properties in your initial integration will help avoid backfills and amendments.
Property values should be primitives: strings, booleans, or numbers. Numeric property values must be between -9223372036854775808 and 9223372036854775807; events with numbers outside this range are rejected during ingestion validation.
In the Financial APIs use case above, the entirety of the event might look like:
Tracing ingested events
Events themselves can be inspected in Orb via a trace view. This can be helpful for understanding how events are being processed, or in order to test your integration. The Events usage view also shows account-wide counts for preset time ranges, including events ingested, events filtered as duplicates, and events filtered due to idempotency key reuse. Use these cards to spot ingestion-volume changes or duplicate-event patterns before drilling into individual event traces. This view includes:-
A full view of the event, including the
propertiesthat were sent with the original payload - Attribution information to the Orb Customer
- Information about whether the event contributed to an active subscription, and if it led to a deduction for pre-paid plans
- How the event contributed to the invoicing cycle, past or upcoming
Integrations for event ingestion
Orb supports multiple different ingestion strategies to maximize the ease and efficiency of your integration. In addition to the primary ingestion endpoint, events can also be ingested via the following integrations.
Please reach out to the Orb team in order to provision these connections for your account.