From 26284667e623c9442c248e26eab0bc7a3c032633 Mon Sep 17 00:00:00 2001 From: Gergely Tamas Kurucz Date: Mon, 3 Aug 2026 13:38:39 +0200 Subject: [PATCH 1/3] feat(docs): document Metering & Billing plugin event dimensions The plugin page said it "captures standard Kong Gateway metadata" but never listed the fields the plugin emits on its CloudEvents. Add a "Captured event dimensions" section under "How it works" with a table per event type (kong.api_request, kong.llm_request) plus the conditional portal/application fields, rendered from a new data file via an include (otel metric_tables pattern). Fields transcribed from the plugin source cloudevent.lua. --- app/_data/plugins/metering-and-billing.yaml | 116 ++++++++++++++++++ .../metering-and-billing/event_dimensions.md | 41 +++++++ .../metering-and-billing/index.md | 8 ++ 3 files changed, 165 insertions(+) create mode 100644 app/_data/plugins/metering-and-billing.yaml create mode 100644 app/_includes/plugins/metering-and-billing/event_dimensions.md diff --git a/app/_data/plugins/metering-and-billing.yaml b/app/_data/plugins/metering-and-billing.yaml new file mode 100644 index 00000000000..d0d910d2009 --- /dev/null +++ b/app/_data/plugins/metering-and-billing.yaml @@ -0,0 +1,116 @@ +# Event dimensions emitted by the Metering & Billing plugin. +# Source of truth: kong-ee/kong/plugins/metering-and-billing/cloudevent.lua +# Operator-configured `attributes` add custom fields that are not listed here. +events: + - type: kong.api_request + when: "Emitted for each proxied API request when `meter_api_requests` is enabled on the plugin." + fields: + - field: client_ip + type: string + description: "Client IP address that made the request." + - field: control_plane_id + type: string + description: "ID of the control plane that produced the event." + - field: request_host + type: string + description: "Host of the request." + - field: request_method + type: string + description: "HTTP method of the request." + - field: request_uri + type: string + description: "URI path of the request." + - field: request_size_bytes + type: integer + description: "Size of the request in bytes." + - field: request_user_agent + type: string + description: "User agent of the request." + - field: response_size_bytes + type: integer + description: "Size of the response in bytes." + - field: response_http_status + type: integer + description: "HTTP status code of the response." + - field: route_id + type: string + description: "ID of the matched Route." + - field: route_name + type: string + description: "Name of the matched Route." + - field: service_id + type: string + description: "ID of the Gateway Service." + - field: service_name + type: string + description: "Name of the Gateway Service." + - field: service_port + type: integer + description: "Port of the Gateway Service." + - field: service_protocol + type: string + description: "Protocol of the Gateway Service." + - field: subject_type + type: string + description: "Type of the resolved subject, for example consumer_id." + - field: upstream_status + type: integer + description: "HTTP status code returned by the upstream service." + - type: kong.llm_request + when: "Emitted for AI traffic when `meter_ai_token_usage` is enabled. A separate event is produced for the request and the response." + fields: + - field: type + type: string + description: "Phase of the interaction, either request or response." + - field: control_plane_id + type: string + description: "ID of the control plane that produced the event." + - field: service_id + type: string + description: "ID of the Gateway Service." + - field: route_id + type: string + description: "ID of the matched Route." + - field: http_status + type: integer + description: "HTTP status code of the response." + - field: api_request_id + type: string + description: "Identifier that correlates the request and response events." + - field: ai_plugin_id + type: string + description: "ID of the AI plugin that handled the request." + - field: ai_plugin_name + type: string + description: "Name of the AI plugin that handled the request." + - field: model + type: string + description: "LLM model name. Reflects the request or response model depending on the type." + - field: provider + type: string + description: "LLM provider name, for example openai." + - field: tokens + type: integer + description: "Token count. Prompt tokens for request events and completion tokens for response events." + - field: cache_status + type: string + description: "Cache status of the AI response." + - field: subject_type + type: string + description: "Type of the resolved subject, for example consumer_id." +portal_fields: + - field: application_id + type: string + description: "ID of the associated application." + - field: portal_id + type: string + description: "ID of the associated Dev Portal." + - field: api_product_version_id + type: string + description: "ID of the associated API product version." + - field: api_id + type: string + description: "ID of the associated API." + - field: api_package_id + type: string + description: "ID of the associated API package." diff --git a/app/_includes/plugins/metering-and-billing/event_dimensions.md b/app/_includes/plugins/metering-and-billing/event_dimensions.md new file mode 100644 index 00000000000..e71ec26dcf3 --- /dev/null +++ b/app/_includes/plugins/metering-and-billing/event_dimensions.md @@ -0,0 +1,41 @@ +{%- assign mb = site.data.plugins["metering-and-billing"] -%} +{% for event in mb.events %} +#### `{{ event.type }}` + +{{ event.when }} + +{% table %} +columns: + - title: Field + key: field + - title: Type + key: type + - title: Description + key: description +rows: +{% for f in event.fields %} + - field: "`{{ f.field }}`" + type: "{{ f.type }}" + description: "{{ f.description }}" +{% endfor %} +{% endtable %} +{% endfor %} +#### Portal and application fields + +The following fields are included only when the request is associated with a {{ site.konnect_short_name }} Dev Portal application or API product, and can appear on either event type. + +{% table %} +columns: + - title: Field + key: field + - title: Type + key: type + - title: Description + key: description +rows: +{% for f in mb.portal_fields %} + - field: "`{{ f.field }}`" + type: "{{ f.type }}" + description: "{{ f.description }}" +{% endfor %} +{% endtable %} diff --git a/app/_kong_plugins/metering-and-billing/index.md b/app/_kong_plugins/metering-and-billing/index.md index 220b379fb53..3bcd8739838 100644 --- a/app/_kong_plugins/metering-and-billing/index.md +++ b/app/_kong_plugins/metering-and-billing/index.md @@ -81,6 +81,14 @@ Every usage event has a subject that identifies who is billed for the request. T If the plugin can't resolve a subject from the configured source (for example, if the expected header is missing), the event is dropped. +### Captured event dimensions + +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: + +{% include plugins/metering-and-billing/event_dimensions.md %} + +In addition to these standard fields, you can attach operator-defined custom fields to events. See [Filtering traffic and custom dimensions](#filtering-traffic-and-custom-dimensions) below. + ### Filtering traffic and custom dimensions You can further narrow which traffic and dimensions the plugin will ingest as events. From e7b9c8fed070e4570145668c8cd528a66512c44e Mon Sep 17 00:00:00 2001 From: Gergely Tamas Kurucz Date: Mon, 3 Aug 2026 13:43:38 +0200 Subject: [PATCH 2/3] feat(docs): link M&B guides to the event dimensions reference The guides show a curated subset of meter dimensions. Add a line in each "Create a meter" step linking to the new event dimensions reference on the Metering & Billing plugin page for the complete list. --- app/_how-tos/ai-gateway/meter-llm-traffic.md | 2 ++ app/_how-tos/gateway/get-started-with-metering-and-billing.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/app/_how-tos/ai-gateway/meter-llm-traffic.md b/app/_how-tos/ai-gateway/meter-llm-traffic.md index 573a23c4c85..9c193aa9da7 100644 --- a/app/_how-tos/ai-gateway/meter-llm-traffic.md +++ b/app/_how-tos/ai-gateway/meter-llm-traffic.md @@ -146,6 +146,8 @@ body: {% endkonnect_api_request %} +This example meters a few representative dimensions. For every field the plugin can emit, see [Captured event dimensions](/plugins/metering-and-billing/#captured-event-dimensions). + ## Configure the Metering & Billing plugin Next, configure the [{{site.metering_and_billing}} plugin](/plugins/metering-and-billing/) to emit LLM token usage events from {{site.ai_gateway}} to {{site.metering_and_billing}}: diff --git a/app/_how-tos/gateway/get-started-with-metering-and-billing.md b/app/_how-tos/gateway/get-started-with-metering-and-billing.md index 4f8c15b4e7b..5ff2e288187 100644 --- a/app/_how-tos/gateway/get-started-with-metering-and-billing.md +++ b/app/_how-tos/gateway/get-started-with-metering-and-billing.md @@ -179,6 +179,8 @@ body: {% endkonnect_api_request %} +This example meters a few representative dimensions. For every field the plugin can emit, see [Captured event dimensions](/plugins/metering-and-billing/#captured-event-dimensions). + ## Enable the {{site.metering_and_billing}} plugin Next, configure the [{{site.metering_and_billing}} plugin](/plugins/metering-and-billing/) to emit API request events from {{site.base_gateway}} to {{site.metering_and_billing}} so that you can charge customers for API traffic usage: From d6ffe822b3ad4a836a0cfe72c6cb3288290f7238 Mon Sep 17 00:00:00 2001 From: lena-larionova <54370747+lena-larionova@users.noreply.github.com> Date: Wed, 5 Aug 2026 11:28:04 -0700 Subject: [PATCH 3/3] Adjust language --- app/_kong_plugins/metering-and-billing/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_kong_plugins/metering-and-billing/index.md b/app/_kong_plugins/metering-and-billing/index.md index 3bcd8739838..b0eb5914ac7 100644 --- a/app/_kong_plugins/metering-and-billing/index.md +++ b/app/_kong_plugins/metering-and-billing/index.md @@ -87,7 +87,7 @@ For each request it meters, the plugin captures a set of standard fields on the {% include plugins/metering-and-billing/event_dimensions.md %} -In addition to these standard fields, you can attach operator-defined custom fields to events. See [Filtering traffic and custom dimensions](#filtering-traffic-and-custom-dimensions) below. +In addition to these standard fields, you can attach operator-defined custom fields to events. See [Filtering traffic and custom dimensions](#filtering-traffic-and-custom-dimensions) for more information. ### Filtering traffic and custom dimensions