XXX: 🍞 breadcrumb comments

linkerd/app/outbound/src/http/logical/policy/route.rs

@@ -57,6 +57,8 @@ pub(crate) type Grpc<T> = MatchedRoute<
 pub(crate) type BackendDistribution<T, F> = distribute::Distribution<Backend<T, F>>;
 pub(crate) type NewDistribute<T, F, N> = distribute::NewDistribute<Backend<T, F>, (), N>;
 
+// XXX(kate): this is the router's metrics type. (route- and backend-level labels)
+// XXX(kate): this does not need to be generic over R and B the `StreamLabel` is shared in practice
 pub type Metrics<R, B> = metrics::RouteMetrics<
     <R as http_prom::MkStreamLabel>::StreamLabel,
     <B as http_prom::MkStreamLabel>::StreamLabel,
@@ -91,7 +93,7 @@ where
     Self: svc::Param<extensions::Params>,
     Self: http_prom::MkStreamLabel,
     MatchedBackend<T, M, F>: filters::Apply,
-    MatchedBackend<T, M, F>: http_prom::MkStreamLabel,
+    MatchedBackend<T, M, F>: http_prom::MkStreamLabel, // XXX(kate): MkStreamLabel bound
 {
     /// Builds a route stack that applies policy filters to requests and
     /// distributes requests over each route's backends. These [`Concrete`]
@@ -173,6 +175,7 @@ impl<T> filters::Apply for Http<T> {
     }
 }
 
+// XXX(kate): an implementation of `MkStreamLabel`.
 impl<T> http_prom::MkStreamLabel for Http<T> {
     type StreamLabel = metrics::LabelHttpRouteRsp;
 
@@ -225,6 +228,7 @@ impl<T> filters::Apply for Grpc<T> {
     }
 }
 
+// XXX(kate): an implementation of `MkStreamLabel`.
 impl<T> http_prom::MkStreamLabel for Grpc<T> {
     type StreamLabel = metrics::LabelGrpcRouteRsp;
 

linkerd/app/outbound/src/http/logical/policy/route/backend.rs

@@ -147,6 +147,7 @@ impl<T> filters::Apply for Http<T> {
     }
 }
 
+// XXX(kate): an implementation of `MkStreamLabel`.
 impl<T> http_prom::MkStreamLabel for Http<T> {
     type StreamLabel = route::metrics::LabelHttpRouteBackendRsp;
 
@@ -173,6 +174,7 @@ impl<T> filters::Apply for Grpc<T> {
     }
 }
 
+// XXX(kate): an implementation of `MkStreamLabel`.
 impl<T> http_prom::MkStreamLabel for Grpc<T> {
     type StreamLabel = route::metrics::LabelGrpcRouteBackendRsp;
 

linkerd/app/outbound/src/http/logical/policy/route/backend/metrics.rs

@@ -13,6 +13,7 @@ use linkerd_http_prom::{
 #[cfg(test)]
 mod tests;
 
+// XXX(kate): this is the application's view of route backend metrics.
 #[derive(Debug)]
 pub struct RouteBackendMetrics<L: StreamLabel> {
     requests: RequestCountFamilies<labels::RouteBackend>,
@@ -30,6 +31,7 @@ pub fn layer<T, N>(
 > + Clone
 where
     T: MkStreamLabel,
+    // XXX(kate): each layer of middleware has to show its `NewService<T>` bounds here.
     N: svc::NewService<T>,
     NewCountRequests<
         ExtractRequestCount,

linkerd/app/outbound/src/http/logical/policy/route/metrics.rs

@@ -11,6 +11,7 @@ pub(super) mod test_util;
 #[cfg(test)]
 mod tests;
 
+// XXX(kate): this is the application's view of route metrics.
 #[derive(Debug)]
 pub struct RouteMetrics<R: StreamLabel, B: StreamLabel> {
     pub(super) retry: retry::RouteRetryMetrics,
@@ -76,6 +77,7 @@ where
 
 // === impl RouteMetrics ===
 
+// XXX(kate): buckets for request/response durations for route-level metrics.
 impl<R: StreamLabel, B: StreamLabel> RouteMetrics<R, B> {
     // There are two histograms for which we need to register metrics: request
     // durations, measured on routes, and response durations, measured on
@@ -168,6 +170,7 @@ impl<P> From<P> for LabelHttpRsp<P> {
     }
 }
 
+// XXX(kate): stream label implementation for http responses.
 impl<P> StreamLabel for LabelHttpRsp<P>
 where
     P: EncodeLabelSetMut + Clone + Eq + std::fmt::Debug + std::hash::Hash + Send + Sync + 'static,
@@ -219,6 +222,7 @@ impl<P> From<P> for LabelGrpcRsp<P> {
     }
 }
 
+// XXX(kate): stream label implementation for grpc responses.
 impl<P> StreamLabel for LabelGrpcRsp<P>
 where
     P: EncodeLabelSetMut + Clone + Eq + std::fmt::Debug + std::hash::Hash + Send + Sync + 'static,

linkerd/http/prom/src/record_response.rs

@@ -31,6 +31,8 @@ pub use self::{
 ///
 /// This is specifically to support higher-cardinality status counters and
 /// lower-cardinality stream duration histograms.
+//  XXX(kate): this is a trait we would like to remove.
+//  XXX(kate): consider a blanket implementation of this for `T: Fn(..) -> ..`
 pub trait MkStreamLabel {
     type StreamLabel: StreamLabel;
 
@@ -83,6 +85,9 @@ pub struct NewRecordResponse<L, X, M, N> {
 }
 
 /// A Service that can record a request/response durations.
+//
+//  XXX(kate): this middle instruments an inner service `S` with a `L`-typed [`MkStreamLabel`].
+//  XXX(kate): service impls instrument `S` with a `RequestMetrics` and `ResponseMetrics`.
 #[derive(Clone, Debug)]
 pub struct RecordResponse<L, M, S> {
     inner: S,
@@ -101,6 +106,9 @@ where
 }
 
 /// Notifies the response labeler when the response body is flushed.
+//
+//  XXX(kate): i do not believe this comment is correct. `RequestBody` does that, this type in
+//  fact updates the metrics when finished.
 #[pin_project::pin_project(PinnedDrop)]
 struct ResponseBody<L: StreamLabel> {
     #[pin]