Quick Start | OpenMeter

A step-by-step guide to getting started with OpenMeter.

#1. Clone the repository

First, clone the repository from Github:

git clone [email protected]:openmeterio/openmeter.git
cd openmeter/quickstart

#2. Launch OpenMeter

Launch OpenMeter and its dependencies locally via Docker Compose:

docker-compose up -d

#3. Send your first usage event

Ingest usage events in CloudEvents format:

curl -X POST http://localhost:8888/api/v1/events \
-H "Expect:" \
-H 'Content-Type: application/cloudevents+json' \
--data-raw '
{
  "specversion": "1.0",
  "type": "request",
  "id": "00001",
  "time": "2023-01-01T00:00:00.001Z",
  "source": "service-0",
  "subject": "customer-1",
  "data": {
    "method": "GET",
    "route": "/hello"
  }
}
'

Event format

#4. Send more usage events

Use Unique ID(s)

Ensure that the id field is unique for each event to avoid duplication.

Note how id is different for the second event:

curl -X POST http://localhost:8888/api/v1/events \
-H "Expect:" \
-H 'Content-Type: application/cloudevents+json' \
--data-raw '
{
  "specversion": "1.0",
  "type": "request",
  "id": "00002",
  "time": "2023-01-01T00:00:00.001Z",
  "source": "service-0",
  "subject": "customer-1",
  "data": {
    "method": "GET",
    "route": "/hello"
  }
}
'

Note how id and time are different for the third event:

curl -X POST http://localhost:8888/api/v1/events \
-H "Expect:" \
-H 'Content-Type: application/cloudevents+json' \
--data-raw '
{
  "specversion": "1.0",
  "type": "request",
  "id": "00003",
  "time": "2023-01-02T00:00:00.001Z",
  "source": "service-0",
  "subject": "customer-1",
  "data": {
    "method": "GET",
    "route": "/hello"
  }
}
'

#5. Query Usage

Query the usage hourly (jq is used to format the JSON output.):

curl http://localhost:8888/api/v1/meters/api_requests_total/query?windowSize=HOUR | jq

{
  "values": [
    {
      "subject": "customer-1",
      "windowStart": "2023-01-01T00:00:00Z",
      "windowEnd": "2023-01-01T01:00:00Z",
      "value": 2,
      "groupBy": {
        "method": "GET",
        "route": "/hello"
      }
    },
    {
      "subject": "customer-1",
      "windowStart": "2023-01-02T00:00:00Z",
      "windowEnd": "2023-01-02T01:00:00Z",
      "value": 1,
      "groupBy": {
        "method": "GET",
        "route": "/hello"
      }
    }
  ]
}

#Configure additional meter(s)

Configure how OpenMeter should process your usage events. In this example, we will meter the execution duration per API invocation, grouped by method and route. You can think about how AWS Lambda charges by execution duration on a millisecond level.

config.yaml

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

The events will be processed and aggregated by OpenMeter using the duration_seconds property, grouped by method and route properties.

#Cleanup

Once you are done, stop any running instances:

docker-compose down -v