lago
Sends usage events to Lago for metering and billing.
lagoPriority 415What it does
lago sends a usage event to a Lago billing API for each request on the route. Each event counts against the billable metric under Event code and is billed to the subscription under Event subscription ID. The events go out in batches to Endpoint addresses.
The request goes on to the backend as usual, and the client gets the backend's answer, 200 in the example. The event follows in a batch posted to /api/v1/events/batch on the billing API.
When to use it
- An orders API sold by usage, where each partner pays per call and the invoice comes from Lago.
- Billing each caller on its own account: key-auth names the consumer, and
cus_${consumer_name}turns that name into its subscription. - A price that depends on the outcome, with the status of each answer sent along under Event properties.
- A Lago installation inside your own network, reached at its own address under Endpoint addresses.
Not for counting requests for dashboards and alerts — see prometheus (Exposes request metrics for Prometheus), a record of every request for later reading — see http-logger (Sends request logs to an HTTP endpoint in batches) or capping how many requests a consumer may send — see limit-count (Limits the number of requests in a time window, per key).
Set it up
Bill every request to the calling consumer's subscription
Needs an authentication plugin on the same route, which sets the consumer name; without one every event is billed to cus_.
Under Basics fill Endpoint addresses as in the JSON below, set Token to <secret>, set Event code to api_call, set Event subscription ID to cus_${consumer_name} and set Event transaction ID to req_${request_id}. Under Behavior fill Event properties as in the JSON below.
{
"endpoint_addrs": [
"https://billing.example.com"
],
"token": "<secret>",
"event_code": "api_call",
"event_subscription_id": "cus_${consumer_name}",
"event_transaction_id": "req_${request_id}",
"event_properties": {
"status": "${status}"
}
}
More scenarios
Let more events wait when the billing API is slow to answerenvironment-wide settings
Set Pending entry limit to 16384.
{
"max_pending_entries": 16384
}
Things to know
- Event subscription ID — With
cus_${consumer_name}, each event is billed to the subscription named after the consumer whose key signed the request. In the example the batch carriescus_followed by that consumer's username. - Event subscription ID — A variable the request does not carry becomes empty. On a route with no authentication plugin there is no consumer name, and
cus_${consumer_name}bills every event tocus_. - Endpoint addresses — Every address must accept the same records: each batch goes to one of them at random.
- Endpoint addresses — An address without its scheme,
127.0.0.1:3000for example, is refused when you save. - Event code — In the example every event in the batch carries the code
api_call. - Event code — Sent exactly as written: a ${variable} here is not resolved, the way it is in the transaction and the subscription id.
- Event properties — A value in which no variable resolves is sent as written, not emptied. Where some resolve, the missing ones become empty strings.
- Event properties — A value written as a number,
200without quotes for example, is refused when you save. - AdviceBuild Event transaction ID from the request's own ID,
req_${request_id}as in the example, so that no two requests share one.
Settings
The fields as the console shows them, section by section.
Basics
endpoint_addrsarray of stringsRequiredThe Lago API address, self-hosted or cloud, without the path the batch is posted to.
tokenstringRequiredThe Lago API key, sent as the bearer token of every batch. Stored on the engine and shown only to roles that manage this object.
event_codestringRequiredThe billable metric on Lago the events are counted against.
event_subscription_idstringRequiredThe Lago subscription ID the usage is billed to, as text or a request variable such as $http_x_subscription_id. Variables are replaced as in the transaction ID: a variable the request does not carry becomes an empty string.
event_transaction_idstringRequiredA unique ID for each event so Lago can drop duplicates, usually $request_id. Both $name and ${name} are replaced by the request variable, a variable the request does not carry becomes an empty string, and ${name ?? fallback} supplies a default.
Behavior
event_propertiesobjectExtra properties sent with each event as key and value pairs, where a value may carry request variables such as ${status}. A value in which no variable resolves is sent as written, not emptied. In a value where some resolve, the missing ones become empty strings. An object whose keys are any name, each with a string as its value.
endpoint_uristringdefault /api/v1/events/batchThe path added to the chosen address, which has to be Lago's batch endpoint and not the single-event one.
timeoutintegerdefault 3000One timeout for connecting, sending and reading the batch alike.
ssl_verifybooleandefault trueAdvanced
batch_max_sizeintegerdefault 100buffer_durationintegerdefault 60inactive_timeoutintegerdefault 5max_retry_countintegerdefault 0retry_delayintegerdefault 1keepalivebooleandefault trueReuses the connection to Lago between batches, and when off the pool and pool timeout below are ignored.
keepalive_poolintegerdefault 5keepalive_timeoutintegerdefault 60000namestringdefault lago loggerEnvironment-wide settings
Set once per environment, under Plugins › lago. Every lago in the environment uses these.
max_pending_entriesintegerdefault 8192How many log entries may wait to be sent. While the backlog is above this number, new entries are dropped rather than queued.