Usage event

Generated from schemas/usage-event.schema.json by scripts/gen-config-docs. Do not edit this page: edit the schema or the generator.

The flat event delivered to subscribed out-of-process plugins. No token, cookie, raw query string, email or username is present.

Fields

Field Type Required Description

Field	Type	Required	Description
`schemaVersion`	integer (fixed: `1`)	yes	Event schema version. Always 1 for this contract.
`type`	string (one of: `request`, `auth`, `error`, `billing`, `audit`)	yes	Event family. Only subscribed types are produced.
`ts`	string	yes	Event time, RFC 3339 UTC.
`instanceId`	string	yes	Stable Gate One node identifier (one WAL per node and type). Minimum length: 1. Maximum length: 256.
`epoch`	string	yes	Producer epoch, changed on restart/migration so consumers can detect a gap. Minimum length: 1. Maximum length: 128.
`tenant`	string	no	Auth provider id or logical tenant; empty for shared/public routes. Maximum length: 128.
`subjectId`	string	no	Opaque deployment-scoped user identifier: versioned HMAC. Never an email or a raw IdP sub. Pattern: `^v[0-9]\.[A-Za-z0-9_-]$`.
`route`	string	no	Normalized route pattern, never the raw URL/query. Maximum length: 512.
`host`	string	no	Request host, without port. Routes are keyed by (host, path): this disambiguates the same path served on several hosts. Maximum length: 256.
`method`	string	no	HTTP method for request/error events. Maximum length: 16.
`status`	integer	no	HTTP status for request/error events. Minimum: 0. Maximum: 599.
`durationMs`	integer	no	Backend or auth duration in milliseconds. Minimum: 0.
`bytes`	integer	no	Response/request size in bytes, as observed by the gateway. Minimum: 0.
`authResult`	string (one of: `ok`, `anonymous`, `denied`, `unavailable`, `failed`)	no	Authentication outcome for the request or auth action.
`action`	string	no	Auth action: login, login_failed, logout, backchannel_logout, revocation. Audit action: reload, reload_failed, plugin_load. Maximum length: 64.
`detail`	string	no	Free-text context for audit events (plugin name, reload error). Never PII. Maximum length: 256.
`attrs`	map of string to string	no	Bounded billing attributes captured from allow-listed query/body fields (or backend hints). Sensitive names are skipped; values are capped.
`attrsTruncated`	boolean	no	True when attrs were capped (too many keys, or a key/value/total exceeded the limit).
`sessionId`	string	no	Opaque RP session id for auth events. Maximum length: 128.
`mcpTool`	string	no	MCP tool or operation name, when the event comes from an MCP route. Maximum length: 256.
`units`	integer	no	Billable/metered units for billing events. Minimum: 0.
`unitType`	string (one of: `request`, `token`, `byte`, `mcp_call`)	no	Unit kind for billing events.
`requestId`	string	no	Gateway request id, for correlation with logs and traces. Maximum length: 128.
`idempotencyKey`	string	no	Caller-provided idempotency key, copied only for billing. Maximum length: 128.

schemaVersion

integer (fixed: 1)

yes

Event schema version. Always 1 for this contract.

type

string (one of: request, auth, error, billing, audit)

yes

Event family. Only subscribed types are produced.

ts

string

yes

Event time, RFC 3339 UTC.

instanceId

string

yes

Stable Gate One node identifier (one WAL per node and type). Minimum length: 1. Maximum length: 256.

epoch

string

yes

Producer epoch, changed on restart/migration so consumers can detect a gap. Minimum length: 1. Maximum length: 128.

tenant

string

Auth provider id or logical tenant; empty for shared/public routes. Maximum length: 128.

subjectId

string

Opaque deployment-scoped user identifier: versioned HMAC. Never an email or a raw IdP sub. Pattern: ^v[0-9]\.[A-Za-z0-9_-]$.

route

string

Normalized route pattern, never the raw URL/query. Maximum length: 512.

host

string

Request host, without port. Routes are keyed by (host, path): this disambiguates the same path served on several hosts. Maximum length: 256.

method

string

HTTP method for request/error events. Maximum length: 16.

status

integer

HTTP status for request/error events. Minimum: 0. Maximum: 599.

durationMs

integer

Backend or auth duration in milliseconds. Minimum: 0.

bytes

integer

Response/request size in bytes, as observed by the gateway. Minimum: 0.

authResult

string (one of: ok, anonymous, denied, unavailable, failed)

Authentication outcome for the request or auth action.

action

string

Auth action: login, login_failed, logout, backchannel_logout, revocation. Audit action: reload, reload_failed, plugin_load. Maximum length: 64.

detail

string

Free-text context for audit events (plugin name, reload error). Never PII. Maximum length: 256.

attrs

map of string to string

Bounded billing attributes captured from allow-listed query/body fields (or backend hints). Sensitive names are skipped; values are capped.

attrsTruncated

boolean

True when attrs were capped (too many keys, or a key/value/total exceeded the limit).

sessionId

string

Opaque RP session id for auth events. Maximum length: 128.

mcpTool

string

MCP tool or operation name, when the event comes from an MCP route. Maximum length: 256.

units

integer

Billable/metered units for billing events. Minimum: 0.

unitType

string (one of: request, token, byte, mcp_call)

Unit kind for billing events.

requestId

string

Gateway request id, for correlation with logs and traces. Maximum length: 128.

idempotencyKey

string

Caller-provided idempotency key, copied only for billing. Maximum length: 128.