Common Examples

This page provides examples for common metering use cases, including the meter config and related usage event example. If you are new to OpenMeter, we recommend you to read the Meter Overview guide first.

#AI Use Cases

Examples for common AI metering use-cases for LLMs and GPUs.

#LLM Token Usage

In most cases, AI applications want to count token usage for billing or cost control purposes. As a single AI interaction involves consuming multiple tokens, we define our meter with the SUM aggregation and report token usage in the data's tokens property. As most LLMs charge differantly for input, output and system prompts and different models it makes sense to add model and prompt type to the group by.

Meter Definition

Note that valueProperty and groupBy use JSONPath to parse out specific fields from the event.

Create Meter in Cloud

meters:
  - slug: tokens_total
    description: AI Token Usage
    # Filter events by type
    eventType: prompt
    aggregation: SUM
    # JSONPath to parse usage value
    valueProperty: $.tokens
    groupBy:
      # Model used: gpt4-turbo, etc.
      model: $.model
      # Prompt type: input, output, system
      type: $.type

Example Usage Event

Example usage event for the meter definition above.

{
  "specversion": "1.0",
  "type": "prompt",
  "id": "00001",
  "time": "2024-01-01T00:00:00.001Z",
  "source": "chat-app",
  "subject": "customer-1",
  "data": {
    "tokens": "123456",
    "model": "gpt4-turbo",
    "type": "output"
  }
}

#GPU Time

Metering GPUs is a common use-case for customer billing, internal chargeback and cost control use-cases.

Meter Definition

Create Meter in Cloud

meters:
  - slug: gpu_execution_duration_seconds
    description: GPU Time
    eventType: gpu_time
    aggregation: SUM
    valueProperty: $.duration_seconds
    groupBy:
     	hostname: $.hostname
     	region: $.region
      # Type of GPU: e.g. nvidia_A100
 	    gpu_type: $.gpu_type

Example Usage Event

{
  "specversion": "1.0",
  "type": "gpu_time",
  "id": "00001",
  "time": "2024-01-01T00:00:00.001Z",
  "source": "my-image-generator",
  "subject": "customer-1",
  "data": {
    "duration_seconds": "12345",
    "hostname": "my-hostname",
    "region": "us-east-1",
    "gpu_type": "nvidia_A100"
  }
}

#API Use Cases

Examples for common API metering use-cases.

#API Request Count

Products monetizing API usage may want to count the number of requests. With choosing the COUNT aggregation each event will increase the meter by one. For grouping we can add method and route. Note how we report the route template not the actual HTTP path to avoid differences around IDs and dynamic routes.

Meter Definition

Note that COUNT aggregation doesn't have a valueProperty.

Create Meter in Cloud

meters:
  - slug: api_requests_total
    description: API Requests
    # Filter events by type
    eventType: request
    aggregation: COUNT
    groupBy:
      # HTTP Method: GET, POST, etc.
      method: $.method
      # Route: /products/:product_id
      route: $.route

Example Usage Event

Example usage event for the meter definition above.

{
  "specversion": "1.0",
  "type": "request",
  "id": "00001",
  "time": "2024-01-01T00:00:00.001Z",
  "source": "api-service",
  "subject": "customer-1",
  "data": {
    "method": "GET",
    "route": "/products/:product_id"
  }
}

#API Request Duration

Similar to the API request, you can decide to track the request duration. This is basically how serverless products like AWS Lambda charge their customers. If you want to track both the request count and duration, you can check out our advanced example.

#Meter Definition

Create Meter in Cloud

meters:
  - slug: api_request_duration
    description: API Request Duration
    # Filter events by type
    eventType: request
    aggregation: SUM
    # JSONPath to parse duration value
    valueProperty: $.duration_seconds
    groupBy:
      # HTTP Method: GET, POST, etc.
      method: $.method
      # Route: /products/:product_id
      route: $.route

Example Usage Event

{
  "specversion": "1.0",
  "type": "request",
  "id": "00001",
  "time": "2024-01-01T00:00:00.001Z",
  "source": "api-service",
  "subject": "customer-1",
  "data": {
    "method": "GET",
    "route": "/products/:product_id",
    "duration_seconds": "12345"
  }
}

#Kubernetes Pod Execution Duration

To track Kubernetes pod execution duration, check out our native Kubernetes collector that already reports usage events in this format.

Meter Definition

Create Meter in Cloud

meters:
  - slug: pod_execution_time
    description: Pod Execution Time
    eventType: kube-pod-exec-time
    aggregation: SUM
    valueProperty: $.duration_seconds
    groupBy:
      pod_name: $.pod_name
      pod_namespace: $.pod_namespace

Example Usage Event

{
  "specversion": "1.0",
  "type": "kube-pod-exec-time",
  "id": "f7f11c82-c415-4325-aec7-572606681817",
  "time": "2024-01-01T00:00:00.001Z",
  "source": "my-app",
  "subject": "customer-1",
  "data": {
    "duration_seconds": "123",
    "pod_name": "pod_name",
    "pod_namespace": "pod_namespace"
  }
}

#Advanced Examples

Common metering use cases with more complex requirements.

#Moving multiple meters with one event

In OpenMeter, a single event can move multiple meters if the event type matches. Let's see an example of tracking an API request's occurrence, execution duration, and network usage.

Meter Definition

Note how we define three meters with the same eventType.

meters:
  - slug: api_requests_total
    description: API Requests
    eventType: request
    aggregation: COUNT
    groupBy:
      method: $.method
      route: $.route
  - slug: api_request_duration_seconds
    description: API Request Duration
    eventType: request
    aggregation: SUM
    valueProperty: $.duration_seconds
    groupBy:
      method: $.method
      route: $.route
  - slug: api_request_ingress_bytes
    description: Request Ingress Bytes
    eventType: request
    aggregation: SUM
    valueProperty: $.ingress_bytes
    groupBy:
      method: $.method
      route: $.route

Example Usage Event

Note how the data payload contains the union of values and group bys of all three meters.

{
  "specversion": "1.0",
  "type": "request",
  "id": "00001",
  "time": "2024-01-01T00:00:00.001Z",
  "source": "api-service",
  "subject": "customer-1",
  "data": {
    "method": "GET",
    "route": "/products/:product_id",
    "duration_seconds": "123",
    "ingress_bytes": "456",
    "egress_bytes": "789"
  }
}

#Counting state changes

In some cases you want to count how many states a workflow or task went through as it progresses for example from created to in_progress and success. The challenge is that if you report a usage event for every state change and track state as a group by answering simple questions like how many workflows were in total would always require filtering by states like created, which is easy to forget and error-prone.

The recommended way to model states is to create separate meters per state.

Meter Definition

meters:
  - slug: workflow_created
    description: Workflows Created
    eventType: workflow_create
    aggregation: COUNT
    groupBy:
      task_type: $.task_type
  - slug: workflow_succeeded
    description: Workflow Succeeded
    eventType: workflow_success
    aggregation: COUNT
    groupBy:
      task_type: $.task_type
  - slug: workflow_failed
    description: Workflow Failed
    eventType: workflow_fail
    aggregation: COUNT
    groupBy:
      task_type: $.task_type

Example Usage Event

Demonstrates workflow creation and success events.

[
  {
    "specversion": "1.0",
    "type": "workflow_create",
    "id": "00001",
    "time": "2024-01-01T00:00:00.001Z",
    "source": "task-queue",
    "subject": "task-1",
    "data": {
      "type": "image-generate"
    }
  },
  {
    "specversion": "1.0",
    "type": "workflow_success",
    "id": "00001",
    "time": "2024-01-01T00:00:00.001Z",
    "source": "task-queue",
    "subject": "task-1",
    "data": {
      "task_type": "image-generate"
    }
  }
]