Creating Meters

OpenMeter provides a flexible way to define and manage meters, offering multiple aggregation methods you can adapt to your needs.

#Meter Definition

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

Each meter has the following attributes:

• slug: A unique identifier for the meter. You use it to reference the meter in the OpenMeter API.
• description: A human-readable description of the meter.
• eventType: The event type the meter tracks. OpenMeter uses it to filter which events count toward the meter.
• valueProperty: The JSON path to the property that contains the value to meter. Optional when the aggregation is COUNT.
• aggregation: The aggregation type the meter uses. See Aggregation Types for more information.
• groupBy: A map of JSON paths to group the metered data by. Optional.

Note that the time window is not part of the meter definition: windowSize is a parameter of the meter query API. When omitted at query time, the query returns a single aggregated value for the whole period.

#Example

Counting API requests per method and path:

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

#Aggregation Types

OpenMeter supports several aggregation types, making it suitable for a wide range of applications.

#SUM

The SUM aggregation type calculates the 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.

#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.

#LATEST

The LATEST aggregation type returns the latest value for a specific time window. This is useful when you track a resource's size yourself and periodically report its value to OpenMeter — for example, disk size or the number of resources or seats. The latest aggregation takes the last value reported for the period.

#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.

#AVG

The AVG aggregation type calculates the average of the metered values within a specific time window. This is useful for metrics like average request duration or average payload size.

#Updating Meters

Once a meter is created, the slug, aggregation, eventType, and valueProperty are immutable, because changing them would redefine what the already-collected usage means. The name, description, groupBy, and metadata properties can be updated.

#Parsing With JSONPath

A CloudEvents data payload can be any valid JSON object. OpenMeter lets you use JSONPath to extract the data you want to meter or group by. This is useful for metering nested or complex events in cases where you can only pre-process the data after sending it to OpenMeter.

Note that only basic scalar paths like $.property or $.nested.property are supported; advanced JSONPath features such as filters, wildcards, and script expressions are not.

#Value Property

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

The following table shows 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 are parsed as strings. Complex group by values that the JSONPath returns are dropped and replaced with an empty string.

The following table shows how OpenMeter parses types returned by the group by JSONPath: