Overview

The OpenMeter provides a robust and flexible way to define and manage meters. This configuration is designed to offer multiple aggregation methods and window sizes, making it highly adaptable to your specific needs.

#Meter Definition

Meters in OpenMeter are defined in the meters section of the configuration file.

Each meter comprises the following attributes:

• slug: A unique identifier for the meter. This is used to reference the meter in the OpenMeter API.
• description: A human-readable description of the meter.
• eventType: The event type that the meter is tracking. This is used to filter the events that are used to calculate the meter.
• valueProperty: The JSON path to the property that contains the value to be metered. This is optional when the aggregation is COUNT.
• aggregation: The aggregation type to use for the meter. See Aggregation Types for more information.
• groupBy: A map of JSON paths to group the metered data by. This is optional.
• windowSize: The size of the time window to use for the meter. This is optional and defaults to MINUTE.

Check out the best practices to learn more.

#Example

Counting API requests per method and path:

Open Source config:

meters:
  - slug: api_requests_total
    description: API Requests
    eventType: request
    aggregation: COUNT
    groupBy:
      method: $.method
      route: $.route

See most common examples of meter definitions here.

#Aggregation Types

OpenMeter allows various aggregations, making it suitable for a wide range of applications.

#SUM

The SUM aggregation type calculates the total sum of the metered values for a specific time window. This is useful for accumulating metrics like total API calls made, total data transferred, LLM tokens used or total time spent on a service.

#COUNT

The COUNT aggregation type counts the number of events that occur within a specific time window. This is often used for metrics that are inherently countable, such as the number of transactions processed. The COUNT aggregation type does not require a valueProperty to be defined.

#MIN

The MIN aggregation type identifies the minimum value among the metered data points within a specific time window. This is useful for metrics where the lowest value is of interest, such as minimum available storage or minimum response time.

#MAX

The MAX aggregation type identifies the maximum value among the metered data points within a specific time window. This is useful for metrics where the highest value is of interest, such as maximum load on a server or maximum transaction value.

#UNIQUE COUNT

The UNIQUE_COUNT aggregation type counts the number of unique events. This is useful when events are unique by a specific field. The valueProperty defines the field that makes the ingested event unique. The property's value in the ingested event must be a string or number.

Note: OpenMeter always deduplicates events based on id and source fields by default.

Note: For accurate results, avoid grouping by window size in queries, as OpenMeter counts events spanning multiple windows in each window.

#Parsing With JSONPath

CloudEvents's data payload can be any valid JSON object, which then OpenMeter allows you to use JSONPath to extract the data you want to meter or group based on it. This is handy for meter nested and complex events where you can only pre-process the data after sending it to OpenMeter.

You can use this playground to test your JSONPath expressions: JSONPath Online Evaluator

#Value Property

Value property will be parsed as a number. The extracted value property has to be number or string holding a number for the SUM, AVG, MIN, and MAX aggregations. For UNIQUE_COUNT, the value property has to be a string or number. We recommend sending float numbers as strings to avoid precision issues. For the COUNT aggregation, the value property is omitted.

Here is a mapping about how OpenMeter parses types returned by the value property JSONPath:

For example, if you send the following JSON payload for the openai_token_usage above:

{
  "specversion": "1.0",
  "type": "tokens",
  "id": "00001",
  "time": "2023-01-01T00:00:00.001Z",
  "source": "service-0",
  "subject": "customer-1",
  "data": {
    "total_tokens": "123",
    "model": "gpt-4",
    "type": "output"
  }
}

The valueProperty (usage) would be 123 because of the "valueProperty": "$.total_tokens" meter config. While the groupBy would be gpt-4 because of the "groupBy": { "model": "$.model" } meter config.

#Group By Properties

Group by properties will be parsed as strings. Complex group by values returned by the JSONPath will be dropped and replaced by an empty string.

Here is a mapping about how OpenMeter parses types returned by the group by JSONPath: