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.
For each request it meters, the plugin captures a set of standard fields on the event’s data payload. The available fields depend on the event type:
Emitted for each proxied API request when meter_api_requests is enabled on the plugin.
|
Field
|
Type
|
Description
|
client_ip
|
string
|
Client IP address that made the request.
|
control_plane_id
|
string
|
ID of the control plane that produced the event.
|
request_host
|
string
|
Host of the request.
|
request_method
|
string
|
HTTP method of the request.
|
request_uri
|
string
|
URI path of the request.
|
request_size_bytes
|
integer
|
Size of the request in bytes.
|
request_user_agent
|
string
|
User agent of the request.
|
response_size_bytes
|
integer
|
Size of the response in bytes.
|
response_http_status
|
integer
|
HTTP status code of the response.
|
route_id
|
string
|
ID of the matched Route.
|
route_name
|
string
|
Name of the matched Route.
|
service_id
|
string
|
ID of the Gateway Service.
|
service_name
|
string
|
Name of the Gateway Service.
|
service_port
|
integer
|
Port of the Gateway Service.
|
service_protocol
|
string
|
Protocol of the Gateway Service.
|
subject_type
|
string
|
Type of the resolved subject, for example consumer_id.
|
upstream_status
|
string
|
HTTP status code returned by the upstream service.
|
Emitted for AI traffic when meter_ai_token_usage is enabled. A separate event is produced for the request and the response.
|
Field
|
Type
|
Description
|
type
|
string
|
Phase of the interaction, either request or response.
|
control_plane_id
|
string
|
ID of the control plane that produced the event.
|
service_id
|
string
|
ID of the Gateway Service.
|
route_id
|
string
|
ID of the matched Route.
|
http_status
|
integer
|
HTTP status code of the response.
|
api_request_id
|
string
|
Identifier that correlates the request and response events.
|
ai_plugin_id
|
string
|
ID of the AI plugin that handled the request.
|
ai_plugin_name
|
string
|
Name of the AI plugin that handled the request.
|
model
|
string
|
LLM model name. Reflects the request or response model depending on the type.
|
provider
|
string
|
LLM provider name, for example openai.
|
tokens
|
integer
|
Token count. Prompt tokens for request events and completion tokens for response events.
|
cache_status
|
string
|
Cache status of the AI response.
|
subject_type
|
string
|
Type of the resolved subject, for example consumer_id.
|
The following fields are included only when the request is associated with a Konnect Dev Portal application or API product, and can appear on either event type.
|
Field
|
Type
|
Description
|
application_id
|
string
|
ID of the associated application.
|
portal_id
|
string
|
ID of the associated Dev Portal.
|
api_product_version_id
|
string
|
ID of the associated API product version.
|
api_id
|
string
|
ID of the associated API.
|
api_package_id
|
string
|
ID of the associated API package.
|
In addition to these standard fields, you can attach operator-defined custom fields to events. See Filtering traffic and custom dimensions for more information.
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.
