The Metering & Billing plugin runs in the Kong Gateway request/response path and emits usage events in CloudEvents format.
These events are immutable once emitted and aren’t observability or analytics signals.
For each request, the plugin:
- Resolves the subject (the customer identity that gets billed) from the configured source (a Consumer, application, or request header).
- Captures standard Kong Gateway metadata on the event, including Route, Service, and response status.
- Attaches any configured custom attributes from request headers or query parameters, such as department, project, or priority tier.
- Buffers the event locally and delivers it in batches to the configured ingest endpoint, with automatic retries on failure:
Every usage event has a subject that identifies who is billed for the request. The subject is the most important configuration decision because it determines how usage is grouped and aggregated. You can set the subject to a Kong Gateway Consumer, Konnect Dev Portal application, or any request header value such as x-customer-id or x-tenant-id.
If the plugin can’t resolve a subject from the configured source (for example, if the expected header is missing), the event is dropped.
You can further narrow which traffic and dimensions the plugin will ingest as events.
The following table describes how you can configure the plugin to filter traffic or custom dimensions:
|
Use case
|
Description
|
Configuration example
|
|
Filtering on custom dimensions
|
You can use event attributes to capture custom properties for the usage event for pricing dimensions or reporting.
Event attributes allow you to filter based on criteria such as provider, department, priority, or project for tiered or per-dimension pricing.
You can define any attribute that is found in the header, query, or path of a request.
|
Set config.attributes with the source, what attribute to look up in the source, and which source value to use.
|
|
Filtering traffic in a control plane
|
Since plugins can be applied globally, to Routes, Gateway Services, or Consumers, you can apply the Metering & Billing plugin to these entities to further narrow down the traffic you want to meter from the control plane.
|
Scope the plugin to a Route, Service, or Consumer.
|
The plugin buffers events in a local queue before sending them to the ingest endpoint in batches. If delivery fails, the queue retries with exponential backoff up to the configured maximum retry duration. Events that can’t be delivered within that window are dropped. The plugin itself is stateless; it doesn’t persist events across Gateway restarts.
