​
Step 1: What Are Billable Metrics?

Billable metrics in Orb help you measure and calculate usage data based on the events you send into the platform. For example:
  • If you’re tracking API calls, the events for those API calls are sent to Orb, and the billable metric counts them.
  • Beyond simple examples, billable metrics can handle more complex use cases, such as:
    • Measuring storage used by a customer on a VM.
    • Tracking input and output tokens for an AI model.

​
Step 2: Creating a Billable Metric

To create your first metric, follow these steps:
  1. Navigate to the Billable Metrics Page in test mode.
  2. Click on Create a New Metric: You’ll have two options for how to define your metric:
    1. Simple Event Filter: Use this to quickly match events based on properties such as event name (e.g., API call).
    2. Custom SQL Query: For more advanced use cases, you can use SQL queries to define how your events should be processed.

​
Step 3: Simple Event Filter

If you choose the simple event filter option:
  • You can match events by their event name, such as api_call.
  • This filter allows you to match additional fields within the event’s properties. For instance, if the event includes a key-value pair like source, you can add that to your filter.
    • Orb will autofill values into the input based on previous events you’ve sent, making it easier to set up the filter.
Previewing Events: Once the filter is set, you can preview past events to confirm the metric captures the correct data.

​
Step 4: Defining the Calculation

After filtering the events, decide what type of calculation you want to perform:
  • For example, if you’re counting API calls, you can set up a count of events where the event name is api_call .
  • For more advanced calculations, you can define your property with a “Computed Property” expression.

​
Step 5: Finalizing the Metric

Once you’ve defined the calculation, follow these steps:
  1. Name the Metric: Give it a clear, descriptive name (e.g., “Count API Calls”).
  2. Define an Item: The item is the sellable entity for this metric. For instance, if you’re selling API calls, you can create an item called “API Calls.”
  3. Publish the Metric: You can add an optional description before publishing the metric.

​
Step 6: Debugging Your Metric

Orb provides tools for debugging your billable metrics:
  • In the debugging tab, you can filter by customer or date range to test your metric against existing events.
  • This allows you to confirm that the metric produces the expected results before deploying it live.

​
Step 7: Managing Billable Metrics

  • Duplicate Metrics: If you need to create a similar metric, you can duplicate an existing one instead of starting from scratch.
  • Edit or Archive Metrics: You can edit the metric’s name and description or archive metrics that are no longer in use.
  • Copy to Live Mode: Once you’ve tested and validated the metric in test mode, you can easily copy it to live mode for production use.

​
Step 8: Using Custom SQL Queries

For more complex use cases, you can use Custom SQL to build highly tailored metrics. Custom SQL allows for powerful extensions, making it suitable for various unique usage patterns. You can see some sample SQL expressions here. By following this guide, you can create and configure billable metrics in Orb to track customer usage, power your pricing models, and ensure accurate billing for your services.