Best Practices

This document covers best practices for defining your meters and events.

#Defining Meters

In OpenMeter, meters define how you want to meter your resource usage. Check out the Meter documentation for more details.

The slug is used to identify the meter in your account uniquely. It is used to query usage and cannot be changed later. Slugs can only contain small letters, numbers, and underscore characters with a maximum length of 63.

✅ We recommend:

Use prefixes to set contexts like http_server_ and task_
Use suffixes to include the unit in your meter, like _total and _seconds
Use SI units like _seconds
Use plural like requests and seconds

⛔ Avoid:

Avoid putting group bys to the slug, like http_server_requests_by_method_total
Avoid ambiguous suffixes like _s (seconds)
Avoid numbers like meter123

Following best practices, here are a couple of slug examples:

tokens_total
http_server_requests_total
http_server_requests_duration_seconds

#Group By

API Property: meter.groupBy

Group bys help to meter similar things—for example, token usage of multiple LLM models. We recommend using groups instead of creating multiple meters.

✅ We recommend:

Use groups instead of creating meters

⛔ Avoid:

Dynamic groups that are hard to manage

For example, instead of reporting HTTP Paths like (/products/123), report route (/products/:id)

#Event Type

API Property: meter.eventType

Event types are used to filter the incoming events. Multiple meters can listen to the same event type. This is useful, for example, if you want to meter various aspects of an HTTP request, like total count, duration, network used, etc.

Read more about moving multiple meters with one event.

#Value Property

API Property: meter.valueProperty

Defining event property is necessary for all aggregations except COUNT. This is the value in the data object that will be aggregated over time. OpenMeter uses JSONPath to extract this value from the data; this is useful if you report a nested object. In cases where you have control over what event format you report to OpenMeter, we recommend the following.

✅ We recommend:

Always use valid JSONPath like $.tokens_total
Use suffixes to include the unit in your meter, like _total, _seconds, and _ms
Use plurals like requests and seconds
Report in the same unit as meter; unit conversion is currently not supported

⛔ Avoid:

Avoid ambiguous suffixes like _s (seconds)
Avoid numbers like $.property123

Following best practices, here are a couple of event property examples:

$.duration_seconds
$.tokens_total

#Event Ingestion

OpenMeter uses the CloudEvents format for event ingestion. As CloudEvents is generic, here are some best practices for defining events in OpenMeter.

#Subject

API Property: event.subject

Subjects in OpenMeter are entities that consume resources you wish to meter. These can range from users, servers, and services to devices. The design of subjects is intentionally generic, enabling flexible application across various metering scenarios. Typically, a subject acts as a unique identifier within your system for a user or customer.

Example subjects:

Customer ID or User ID
Hostname or IP address
Service or Application name
Device ID

#Source Property

API Property: event.source

The event's source (e.g. the service name). As events are unique by id and source, set different sources if you report the same transaction in multiple applications.

Here are some examples of sources:

my-service-name
my-application-name
Choosing Event ID

Events are unique by id and source properties for idempotency. OpenMeter deduplicates events by uniqueness. Therefore, picking an ID that makes the event unique and resilient to retries is important. For example, in the case of a metering API call, this can be the request ID. You can generate a new UUID if your application doesn't have a unique identifier.

Here are some examples of ID:

HTTP Request ID, typically in headers: Request-ID, X-Request-ID
LLM Chat Completion ID: id field in ChatGPT response
Workflow ID: like activity ID in Temporal
Generate UUID: Node.js, Python, Go

#Data Property

API Property: event.data

OpenMeter uses CloudEvents format's data property to ingest values and group bys. Be sure to always include in this data property what the meter requires, like value property and group bys.

✅ We recommend:

Always include value property for non-COUNT aggregations
Always include group by properties
Use string quotation for numbers to preserve precision like "123"

⛔ Avoid:

Avoid nesting if you can
Avoid sending additional fields if you can