quickstart

Quickstart

Prerequisites

• Docker (with Compose)
• curl
• jq

Clone the repository:

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

1. Launch OpenMeter

Launch OpenMeter and its dependencies via:

docker compose up -d

2. Ingest usage event(s)

Ingest usage events in CloudEvents format:

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

Note how ID is different:

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

Note how ID and time are different:

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

3. Query Usage

Query the usage hourly:

curl 'http://localhost:8888/api/v1/meters/m1/query?windowSize=HOUR&groupBy=method&groupBy=path' | jq

{
  "windowSize": "HOUR",
  "data": [
    {
      "value": 2,
      "windowStart": "2023-01-01T00:00:00Z",
      "windowEnd": "2023-01-01T01:00:00Z",
      "subject": null,
      "groupBy": {
        "method": "GET",
        "path": "/hello"
      }
    },
    {
      "value": 1,
      "windowStart": "2023-01-02T00:00:00Z",
      "windowEnd": "2023-01-02T01:00:00Z",
      "subject": null,
      "groupBy": {
        "method": "GET",
        "path": "/hello"
      }
    }
  ]
}

Query the total usage for customer-1:

curl 'http://localhost:8888/api/v1/meters/m1/query?subject=customer-1' | jq

{
  "data": [
    {
      "value": 3,
      "windowStart": "2023-01-01T00:00:00Z",
      "windowEnd": "2023-01-02T00:01:00Z",
      "subject": "customer-1",
      "groupBy": {}
    }
  ]
}

4. Configure additional meter(s) (optional)

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

# ...

meters:
  - slug: m1
    eventType: api-calls
    valueProperty: $.duration_ms
    aggregation: SUM
    groupBy:
      method: $.method
      path: $.path

Cleanup

Once you are done, stop any running instances:

docker compose down -v