stats: Improved sequencing documentation for server-side stats events and added tests. (#7885)

Author: RyanBlaney

stats/stats.go

@@ -36,7 +36,12 @@ type RPCStats interface {
 	IsClient() bool
 }
 
-// Begin contains stats when an RPC attempt begins.
+// Begin contains stats for the start of an RPC attempt.
+//
+//   - Server-side: Triggered after `InHeader`, as headers are processed
+//     before the RPC lifecycle begins.
+//   - Client-side: The first stats event recorded.
+//
 // FailFast is only valid if this Begin is from client side.
 type Begin struct {
 	// Client is true if this Begin is from client side.
@@ -69,7 +74,7 @@ func (*PickerUpdated) IsClient() bool { return true }
 
 func (*PickerUpdated) isRPCStats() {}
 
-// InPayload contains the information for an incoming payload.
+// InPayload contains stats about an incoming payload.
 type InPayload struct {
 	// Client is true if this InPayload is from client side.
 	Client bool
@@ -98,7 +103,9 @@ func (s *InPayload) IsClient() bool { return s.Client }
 
 func (s *InPayload) isRPCStats() {}
 
-// InHeader contains stats when a header is received.
+// InHeader contains stats about header reception.
+//
+// - Server-side: The first stats event after the RPC request is received.
 type InHeader struct {
 	// Client is true if this InHeader is from client side.
 	Client bool
@@ -123,7 +130,7 @@ func (s *InHeader) IsClient() bool { return s.Client }
 
 func (s *InHeader) isRPCStats() {}
 
-// InTrailer contains stats when a trailer is received.
+// InTrailer contains stats about trailer reception.
 type InTrailer struct {
 	// Client is true if this InTrailer is from client side.
 	Client bool
@@ -139,7 +146,7 @@ func (s *InTrailer) IsClient() bool { return s.Client }
 
 func (s *InTrailer) isRPCStats() {}
 
-// OutPayload contains the information for an outgoing payload.
+// OutPayload contains stats about an outgoing payload.
 type OutPayload struct {
 	// Client is true if this OutPayload is from client side.
 	Client bool
@@ -166,7 +173,10 @@ func (s *OutPayload) IsClient() bool { return s.Client }
 
 func (s *OutPayload) isRPCStats() {}
 
-// OutHeader contains stats when a header is sent.
+// OutHeader contains stats about header transmission.
+//
+//   - Client-side: Only occurs after 'Begin', as headers are always the first
+//     thing sent on a stream.
 type OutHeader struct {
 	// Client is true if this OutHeader is from client side.
 	Client bool
@@ -189,14 +199,15 @@ func (s *OutHeader) IsClient() bool { return s.Client }
 
 func (s *OutHeader) isRPCStats() {}
 
-// OutTrailer contains stats when a trailer is sent.
+// OutTrailer contains stats about trailer transmission.
 type OutTrailer struct {
 	// Client is true if this OutTrailer is from client side.
 	Client bool
 	// WireLength is the wire length of trailer.
 	//
-	// Deprecated: This field is never set. The length is not known when this message is
-	// emitted because the trailer fields are compressed with hpack after that.
+	// Deprecated: This field is never set. The length is not known when this
+	// message is emitted because the trailer fields are compressed with hpack
+	// after that.
 	WireLength int
 	// Trailer contains the trailer metadata sent to the client. This
 	// field is only valid if this OutTrailer is from the server side.
@@ -208,7 +219,7 @@ func (s *OutTrailer) IsClient() bool { return s.Client }
 
 func (s *OutTrailer) isRPCStats() {}
 
-// End contains stats when an RPC ends.
+// End contains stats about RPC completion.
 type End struct {
 	// Client is true if this End is from client side.
 	Client bool
@@ -238,7 +249,7 @@ type ConnStats interface {
 	IsClient() bool
 }
 
-// ConnBegin contains the stats of a connection when it is established.
+// ConnBegin contains stats about connection establishment.
 type ConnBegin struct {
 	// Client is true if this ConnBegin is from client side.
 	Client bool
@@ -249,7 +260,7 @@ func (s *ConnBegin) IsClient() bool { return s.Client }
 
 func (s *ConnBegin) isConnStats() {}
 
-// ConnEnd contains the stats of a connection when it ends.
+// ConnEnd contains stats about connection termination.
 type ConnEnd struct {
 	// Client is true if this ConnEnd is from client side.
 	Client bool