Best Practices

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

#Defining Meters

In OpenMeter, a meter defines how you track resource usage.

#Slug

API Property: meter.slug

The slug uniquely identifies the meter in your account. You use it to query usage, and you can't change it later. Slugs can contain only lowercase letters, numbers, and underscores, with a maximum length of 64 characters. They must start and end with a letter or number, and can't contain consecutive underscores.

✅ 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 plurals, like requests and seconds

⛔ Avoid:

• Avoid putting group bys in 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 the HTTP path /products/123, report the route template /products/:id.

#Event Type

API Property: meter.eventType

Meters use event types to filter incoming events. Multiple meters can listen to the same event type. This is useful, for example, if you want to meter several aspects of an HTTP request, such as total count, duration, and network usage.

Read more about moving multiple meters with one event.

#Value Property

API Property: meter.valueProperty

Defining a value property is necessary for all aggregations except COUNT. This is the value in the data object that OpenMeter aggregates over time. OpenMeter uses JSONPath to extract this value from the data. This is useful if you report a nested object. Only basic scalar paths like $.property or $.nested.property are supported. If you control the event format you report to OpenMeter, we recommend the following.

✅ We recommend:

• Always use a valid basic 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 values in the same unit as the 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

Read more about JSONPath parsing.

#Event Ingestion

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

#Subject

API Property: event.subject

The subject is the key that identifies the consumer of the resources you want to meter, ranging from users, servers, and services to devices. Subjects are not managed entities — the value you send in the subject field is the subject. The design is intentionally generic, so it works flexibly across various metering scenarios. Typically, a subject is 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). Because 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 their id and source properties, which OpenMeter uses to deduplicate them. Therefore, picking an ID that's 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 IDs:

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

#Data Property

API Property: event.data

OpenMeter uses the CloudEvents format's data property to ingest values and group bys. Always include what the meter requires in this property, such as the value property and group bys.

✅ We recommend:

• Always include the value property for non-COUNT aggregations
• Always include group by properties
• Quote numbers as strings to preserve precision, like "123"

⛔ Avoid:

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

Read more about JSONPath parsing.