Local Development
Watch how to quickstart with OpenMeter Open-Source in development environments.
Quickstart With Open-Source
A step-by-step guide to getting started with OpenMeter Open-Source.
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"
}
}
'
To learn more about the event format, see the Event ingestion page.
4. Send more usage events
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