Quickstart

Watch our video on how to quickstart with OpenMeter.

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

#Launch OpenMeter

Launch OpenMeter and its dependencies locally via Docker Compose:

docker-compose up -d

#Ingest usage event(s)

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"
  }
}
'

To learn more about the event format, see the Event ingestion page.

Note how ID is different:

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:

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"
  }
}
'

#Configure additional meter(s)

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

# config.yaml
# ...
 
meters:
  - slug: api_requests_total
    description: API Requests Total
    eventType: request
    aggregation: COUNT
    groupBy:
      method: $.method
      route: $.route

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

#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"
      }
    }
  ]
}

#Cleanup

Once you are done, stop any running instances:

docker-compose down -v