Best Practices

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

#Defining Meters

In OpenMeter, meters describe how you meter resource usage.

#Slug

API Property: meter.slug

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

Read more about JSONPath parsing.

#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

Read more about JSONPath parsing.