Skip to content

feat(proxy-metrics): document outbound policy routing metrics #2069

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kflynn merged 2 commits into from
Nov 20, 2025
Merged

feat(proxy-metrics): document outbound policy routing metrics #2069

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b4fe32c
feat(proxy-metrics): document outbound policy routing metrics
cratelyn Nov 13, 2025
adb9096
chore(markdownlint): allow duplicate "labels" headers
cratelyn Nov 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 50 additions & 12 deletions linkerd.io/content/2-edge/reference/proxy-metrics.md
View file
Open in desktop
Copy link
Member Author

@cratelyn cratelyn Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

note for review: this should be copied over to the 2.19 docs, but i'd like to hold off until these proposed changes have been reviewed before i handle that.

Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,9 @@ layer.
* `inbound_tcp_authz_deny_total`: A counter of the total number of TCP
connections that were denied

<!-- markdownlint-disable MD024 -->
### Labels
<!-- markdownlint-enable MD024 -->

Each of these metrics has the following labels:

Expand Down Expand Up @@ -268,21 +270,57 @@ connection closes (`tcp_close_total`):
* `identity_cert_refresh_count`: A counter of the total number of times the
proxy's mTLS identity certificate has been refreshed by the Identity service.

## Outbound `xRoute` Metrics
## Endpoint Metrics

When performing policy-based routing, proxies may dispatch requests through
per-route backend configurations. In order to record how routing rules
apply and how backend distributions are applied, the outbound proxy records the
following metrics:

* `outbound_http_route_backend_requests_total`: A counter of the total number of
outbound HTTP requests dispatched to a route-backend.
* `outbound_grpc_route_backend_requests_total`: A counter of the total number of
outbound gRPC requests dispatched to a route-backend.
* `outbound_http_balancer_endpoints`: A gauge of the number of endpoints in an
outbound load balancer.

per-route backend configurations. See the Authorization Policy
[overview](../features/server-policy.md) and
[reference](./authorization-policy.md) pages for more information on how to
configure policy-based routing.

The Linkerd proxy emits metrics that provide visibility into authorized HTTP
and gRPC traffic. Route-level metrics measure traffic for all of a policy's
associated backends, while backend-level metrics measure the traffic
distributed to individual endpoints.

The outbound proxy records the following metrics:

* `outbound_http_route_request_duration_seconds`: A histogram measuring the
time between HTTP request initialization and HTTP response completion.
* `outbound_http_route_request_statuses_total`: A counter tracking HTTP
response status codes for HTTP traffic sent to a route.
* `outbound_http_route_request_frame_size_bytes`: A histogram measuring the
sizes of `DATA` frames in HTTP response bodies for a route.
* `outbound_grpc_route_request_duration_seconds`: A histogram measuring the
time between gRPC request initialization and gRPC response completion.
* `outbound_grpc_route_request_statuses_total`: A counter tracking gRPC
response status codes for gRPC traffic sent to a GRPCRoute.
* `outbound_grpc_route_request_frame_size_bytes`: A histogram measuring the
sizes of `DATA` frames in gRPC response bodies for a route.
* `outbound_http_route_backend_requests_total`: A counter tracking the total
number of outbound HTTP requests dispatched to a particular backend.
* `outbound_http_route_backend_response_duration_seconds`: A histogram
measuring the time in seconds between the HTTP request completing and HTTP
response completing, for a particular backend.
* `outbound_http_route_backend_response_statuses_total`: A counter tracking
HTTP responses from a particular backend, labeled by status code.
* `outbound_http_route_backend_response_frame_size_bytes`: A histogram
measuring the sizes of `DATA` frames in HTTP response bodies from a particular
backend.
* `outbound_grpc_route_backend_requests_total`: A counter tracking the total
number of outbound gRPC requests dispatched to a particular backend.
* `outbound_grpc_route_backend_response_duration_seconds`: A histogram
measuring the time in seconds between the gRPC request completing and gRPC
response completing, for traffic dispatched to a particular backend.
* `outbound_grpc_route_backend_response_statuses_total`: A counter tracking
gRPC responses from a particular backend, labeled by the `grpc-status` code.
* `outbound_grpc_route_backend_response_frame_size_bytes`: A histogram
measuring the sizes of `DATA` frames in gRPC response bodies from a particular
backend.

<!-- markdownlint-disable MD024 -->
### Labels
<!-- markdownlint-enable MD024 -->

Each of these metrics has the following common labels, which describe the
Kubernetes resources to which traffic is routed by the proxy:
Expand Down