Rule

#What is a Rule?

The rule specifies what conditions should trigger an event. Given that OpenMeter can handle millions of ingested events per day, it is not a good practice to send notifications to the customer's backend system at this rate.

Rules solve this issue by allowing our customers to specify the events they are interested in.

#Example

Let's say we have a feature called llm_tokens that measures token usage for our large language models.

Each end user is allowed to use 10,000 of those tokens per month. They have a metered entitlement with this hard limit.

Our backend needs to be notified when users reach 80% of their quota so that we can send them a notification email to buy more tokens.

In this example, the backend is not interested in always getting an updated balance; it would just need to be notified when it reaches the 80% mark. By defining a Rule with an 80% threshold, we achieve this behavior.

#Rule types

Each rule has a type to support multiple event types. For now, OpenMeter only supports the entitlements.balance.threshold, which allows the end users to get notified about Entitlement Balance changes.

#Entitlement Balance Change Rules

Type: entitlements.balance.threshold

This event type can be used to notify you if a certain amount of the available credits are used for an Entitlement.

These rules only work for Metered entitlements, as only those have balances. They work by considering all the activities that change the balance of an Entitlement (such as entitlement creation, granting and ingested events), and if the predefined threshold or feature filter conditions match, they trigger a new event.

We guarantee that only one event is triggered per Entitlement per threshold.

#Thresholds

The threshold can be specified as a percentage of the total grants or as an exact usage number.

Percentage thresholds state that the notification should be sent if the subject has used a given percent of its available quota.

These two options allow for the following use-cases:

Balance Change Rules allow multiple thresholds to be set in the same rule, so the notification settings can be centralized.

#Filtering by features

If multiple features are defined in OpenMeter, it might be practical to receive notifications only for one or more Feature or have different Thresholds per Feature.

An Entitlement Balance Change Rule has an optional Feature filter:

• If the filter is not specified OpenMeter evaluates the rule for all metered entitlements
• If the filter is specified, OpenMeter only evaluates the rule for metered entitlements defined on the specific Features

#Balance changes by granting, voiding grants, and resets

If any activity (granting, entitlement reset) changes the available balance, the thresholds are reevaluated.

The total available credit balance of the subject can increase in case of a grant operation or decrease in case of a grant being voided.

When granting additional credits to an entitlement, the system reevaluates all the thresholds, and if the currently hit threshold changes, a new notification is sent for the lower threshold.

A notification message will be sent if voiding grants push the Entitlement to a higher threshold.

Resetting an entitlement resets the usage. When the usage reaches the first threshold, a new notification is sent.