Metrics reference

Field-level reference for the ConnectionMetric record emitted by the Agent Gateway for every surface request.

The Agent Gateway records a ConnectionMetric entry for every request processed by a surface and exports these records via the configured metrics backend (OTLP, CloudWatch, or file). Use this reference to interpret the fields in your metrics receiver or export files. The status field distinguishes policy-level rejections (failed) from errors in the target service (gatewayfault), and the trace_id and correlation_id fields let administrators correlate a specific request across distributed systems.

Core fields

Present on every metric record, regardless of metric type.

Field	Type	Description
`timestamp`	`datetime` (UTC)	When the request was processed.
`channel_config_id`	`string`	Identifier of the surface configuration that processed the request.
`source`	`string`	Source address or agent identifier. For surface requests, typically the caller’s IP address.
`destination`	`string`	Upstream target address the gateway forwarded the request to.
`status`	`string`	Request outcome. See Status values.
`latency_ms`	`integer` (optional)	Latency of the single measured hop for this record, typically the round-trip time to the upstream target. On a request rejected before it reaches the target, this holds the same value as `total_latency_ms`. Use `total_latency_ms` for end-to-end latency.
`identity_hash`	`string` (optional)	Hash of the agent identity (DID) associated with this request. Present when Identity Management is enabled and a DID was derived.
`direction`	`string`	Whether this record captures a `request` or `response` event. See Direction values.
`trace_id`	`string`	W3C-compatible trace identifier. Links this metric to the corresponding distributed trace span.
`ucp_operation`	`string` (optional)	Universal Commerce Protocol (UCP) operation detected on the request, such as `discovery`, `checkout`, or `payment`. UCP is an A2A protocol extension for commerce transactions. Present only when the surface carries UCP traffic.
`transit_point`	`string` (optional)	Alias of the Transit Point that emitted this record, for an outbound hop from the gateway to another gateway or target. Absent when the record was emitted by the inbound Access Point instead.
`variant_alias`	`string` (optional)	Alias of the Surface Variant that handled this request, letting you filter metrics per variant. Absent for surfaces with no variants, or when the component that recorded the metric does not supply one.
`metric_type`	`string`	Record classification. See Metric type values.
`channel_request_latency_ms`	`integer` (optional)	Time the gateway itself spent on inbound processing before forwarding the request, such as authentication, policy evaluation, and extension handling.
`channel_response_latency_ms`	`integer` (optional)	Time the gateway itself spent on outbound processing after receiving the target’s response, such as URL rewriting, verifiable presentation injection, and response validation.
`total_latency_ms`	`integer`	Total latency for the whole request-response cycle, from when the gateway received the request to when it returned the response. This is the field to use for end-to-end latency; it always includes any gateway-side processing time captured separately in `channel_request_latency_ms` and `channel_response_latency_ms`.
`correlation_id`	`string` (optional)	Caller-provided correlation identifier propagated from the inbound request.
`agent_identity`	`string` (optional)	Resolved agent DID string, when available. Distinct from `identity_hash` in that it holds the full DID.
`request_bytes`	`integer` (optional)	Size of the inbound request body in bytes.
`response_bytes`	`integer` (optional)	Size of the outbound response body in bytes.
`retry_count`	`integer` (optional)	Number of retries the gateway performed before the request succeeded or was abandoned. Present when retry is configured and at least one retry occurred.

Status values

Value	Meaning
`success`	Request was forwarded and a valid response was received from the target.
`failed`	Request was rejected before forwarding (for example, authentication failure, policy denial, or rate limit).
`gatewayfault`	Gateway encountered an error after forwarding the request (for example, target unreachable, timeout, or circuit breaker open).

Direction values

Value	Meaning
`request`	Record captures metrics for the inbound leg of the request, from caller to gateway.
`response`	Record captures metrics for the outbound leg, from gateway to caller.

Metric type values

Value	Meaning
`channel`	Record originates from a surface request (A2A or MCP protocol).
`mcpproxy`	Record originates from an MCP proxy interaction.

OpenTelemetry configuration changes apply without a restart

Saving a change to the OpenTelemetry export settings, such as the transport protocol or the collector endpoint, applies immediately and does not require a gateway restart. The one exception is the trace filter’s allow-list of instrumented components, which is fixed when the gateway process starts and only picks up a change on the next restart.

OTLP export health

An /api/v1/metrics/otlp-status endpoint reports the current OpenTelemetry export configuration and the live per-signal export health for traces, metrics, and logs, including whether each signal is currently healthy, its consecutive failure count, and its last error. This endpoint is API-only. It is not surfaced anywhere in the dashboard, so use it if you need to check OTLP export health programmatically, for example from an external monitoring script.

Health check endpoint

An /api/v1/alive endpoint reports whether the gateway process is running. It always returns a 200 response with no further checks, so it is suited to a liveness probe in a load balancer or container orchestrator. A separate /api/v1/health endpoint performs a deeper readiness check: in a failover deployment, it returns a non-200 response when the instance is not the current leader, so it is suited to a readiness probe that should only route traffic to the active instance.

Observability: Overview of traces, metrics, and logs, including what is exported via OTLP and how the management dashboard visualises per-surface traffic data.

Was this page helpful?

Glad to hear it! Please tell us how we can improve more.

Sorry to hear that. Please tell us how we can improve.

Thank you for sharing your feedback so we can improve your experience.