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

* feat(proxy-metrics): document outbound policy routing metrics

the documentation of our proxy metrics has not kept pace with all of the
exciting telemetry that has been introduced since
#1599 documented the state of our
authorization policy metrics.

this commit reworks the documentation to exhaustively document the
families of metrics exported by the proxy. this commit does not
introduce mention of the _inbound_ metrics that have been added, but
does rename this section to "_Endpoint Metrics_" in order to be
compatible with the future addition of `inbound_http_route_*`,
`inbound_http_route_backend_*`, `inbound_grpc_route*`, and
`inbound_grpc_route_backend_*` metrics.

see:
* linkerd/linkerd2-proxy#2377
* linkerd/linkerd2-proxy#2380
* linkerd/linkerd2-proxy#3086
* linkerd/linkerd2-proxy#3308
* linkerd/linkerd2-proxy#3334

Signed-off-by: katelyn martin <[email protected]>

* chore(markdownlint): allow duplicate "labels" headers

Signed-off-by: katelyn martin <[email protected]>

---------

Signed-off-by: katelyn martin <[email protected]>

Author: cratelyn

linkerd.io/content/2-edge/reference/proxy-metrics.md

@@ -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:
 
@@ -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: