external_metering
Integrates with an external metering service for pre-request balance checks and post-response token usage reporting.
On this page
Integrates with an external metering service for pre-request balance checks and post-response token usage reporting.
Configuration Notes
Tenant identity is resolved from the highest-trust source available: verified {prefix}* metadata written by an authentication filter, then the identity_header_guard filter’s namespaced {namespace}.{prefix}* metadata, then raw {prefix}* request headers. A higher tier always wins, so forged client headers can never override verified claims, and identity headers plus client credentials are always stripped before the request is forwarded.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
metering_url | string | yes | Base URL of the external metering service (required). |
allow_private_endpoint | bool | no | Allow the metering endpoint to resolve to non-public addresses (loopback, private, link-local). Defaults to false, so callouts are rejected before connecting unless the operator opts in. |
timeout_seconds | integer | no | HTTP timeout in seconds for all metering calls. |
feature_key | string | no | Entitlement feature key used in balance check URL path. |
source | string | no | CloudEvents source field value. |
fail_open | bool | no | When true (default), requests proceed if the metering service is unavailable. When false, requests are rejected with 503. |
identity_header_prefix | string | no | Prefix for tenant identity headers to capture and strip. Expected headers: {prefix}username, {prefix}group, {prefix}subscription, {prefix}model. |
identity_metadata_namespace | string | no | Metadata namespace the identity_header_guard filter writes captured identity headers under. Must match that filter’s metadata_namespace setting when both run in one pipeline. |
default_username | string | no | Fallback username when no identity header is present. If set, requests without {prefix}username are still metered under this name. If unset, metering is skipped entirely. |
default_model | string | no | Fallback model name when no identity model header is present. |
Example
filter: external_metering
metering_url: "http://metering-service:8080"
timeout_seconds: 5
feature_key: "inference-tokens"
source: "ai-gateway"
fail_open: true
identity_header_prefix: "x-tenant-"
identity_metadata_namespace: "identity"
default_username: "anonymous"
default_model: "unknown"