stats: Improved sequencing documentation for server-side stats events and added tests.

stats/stats.go

@@ -36,7 +36,49 @@
 	IsClient() bool
 }
 
+// InHeader contain stats when the header is received.
+//  First event in the server side event sequence.
+//  Follows last OutPayload for server side events.
+// 
+// Server Stats Example Event Ordering:
+//  *InHeader* -> Begin -> InPayload(s) -> OutHeader -> OutPayload(s) -> OutTrailer -> End 
+// 
+// Client Stats Example Event Ordering:
+//  Begin -> OutHeader -> OutPayload(s) -> *InHeader* -> InTrailer -> InPayload(s) -> End
+type InHeader struct {
+	// Client is true if this InHeader is from client side.
+	Client bool
+	// WireLength is the wire length of header.
+	WireLength int
+	// Compression is the compression algorithm used for the RPC.
+	Compression string
+	// Header contains the header metadata received.
+	Header metadata.MD
+
+	// The following fields are valid only if Client is false.
+	// FullMethod is the full RPC method string, i.e., /package.service/method.
+	FullMethod string
+	// RemoteAddr is the remote address of the corresponding connection.
+	RemoteAddr net.Addr
+	// LocalAddr is the local address of the corresponding connection.
+	LocalAddr net.Addr
+}
+
+// IsClient indicates if the stats information is from client side.
+func (s *InHeader) IsClient() bool { return s.Client }
+
+func (s *InHeader) isRPCStats() {}
+
 // Begin contains stats when an RPC attempt begins.
+//  First event in the client-side event sequence.
+//  Follows InHeader for server-side events.
+// 
+// Server Stats Example Event Ordering:
+//  InHeader -> *Begin* -> InPayload(s) -> OutHeader -> OutPayload(s) -> OutTrailer -> End
+// 
+// Client Stats Example Event Ordering:
+//  *Begin* -> OutHeader -> OutPayload(s) -> InHeader -> InTrailer -> InPayload(s) -> End
+//
 // FailFast is only valid if this Begin is from client side.
 type Begin struct {
 	// Client is true if this Begin is from client side.
@@ -98,31 +140,6 @@
 
 func (s *InPayload) isRPCStats() {}
 
-// InHeader contains stats when a header is received.
-type InHeader struct {
-	// Client is true if this InHeader is from client side.
-	Client bool
-	// WireLength is the wire length of header.
-	WireLength int
-	// Compression is the compression algorithm used for the RPC.
-	Compression string
-	// Header contains the header metadata received.
-	Header metadata.MD
-
-	// The following fields are valid only if Client is false.
-	// FullMethod is the full RPC method string, i.e., /package.service/method.
-	FullMethod string
-	// RemoteAddr is the remote address of the corresponding connection.
-	RemoteAddr net.Addr
-	// LocalAddr is the local address of the corresponding connection.
-	LocalAddr net.Addr
-}
-
-// IsClient indicates if the stats information is from client side.
-func (s *InHeader) IsClient() bool { return s.Client }
-
-func (s *InHeader) isRPCStats() {}
-
 // InTrailer contains stats when a trailer is received.
 type InTrailer struct {
 	// Client is true if this InTrailer is from client side.