1 /* 2 * 3 * Copyright 2016 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 // Package stats is for collecting and reporting various network and RPC stats. 20 // This package is for monitoring purpose only. All fields are read-only. 21 // All APIs are experimental. 22 package stats // import "google.golang.org/grpc/stats" 23 24 import ( 25 "context" 26 "net" 27 "time" 28 29 "google.golang.org/grpc/metadata" 30 ) 31 32 // RPCStats contains stats information about RPCs. 33 type RPCStats interface { 34 isRPCStats() 35 // IsClient returns true if this RPCStats is from client side. 36 IsClient() bool 37 } 38 39 // Begin contains stats when an RPC attempt begins. 40 // FailFast is only valid if this Begin is from client side. 41 type Begin struct { 42 // Client is true if this Begin is from client side. 43 Client bool 44 // BeginTime is the time when the RPC attempt begins. 45 BeginTime time.Time 46 // FailFast indicates if this RPC is failfast. 47 FailFast bool 48 // IsClientStream indicates whether the RPC is a client streaming RPC. 49 IsClientStream bool 50 // IsServerStream indicates whether the RPC is a server streaming RPC. 51 IsServerStream bool 52 // IsTransparentRetryAttempt indicates whether this attempt was initiated 53 // due to transparently retrying a previous attempt. 54 IsTransparentRetryAttempt bool 55 } 56 57 // IsClient indicates if the stats information is from client side. 58 func (s *Begin) IsClient() bool { return s.Client } 59 60 func (s *Begin) isRPCStats() {} 61 62 // PickerUpdated indicates that the LB policy provided a new picker while the 63 // RPC was waiting for one. 64 type PickerUpdated struct{} 65 66 // IsClient indicates if the stats information is from client side. Only Client 67 // Side interfaces with a Picker, thus always returns true. 68 func (*PickerUpdated) IsClient() bool { return true } 69 70 func (*PickerUpdated) isRPCStats() {} 71 72 // InPayload contains the information for an incoming payload. 73 type InPayload struct { 74 // Client is true if this InPayload is from client side. 75 Client bool 76 // Payload is the payload with original type. This may be modified after 77 // the call to HandleRPC which provides the InPayload returns and must be 78 // copied if needed later. 79 Payload any 80 // Data is the serialized message payload. 81 // Deprecated: Data will be removed in the next release. 82 Data []byte 83 84 // Length is the size of the uncompressed payload data. Does not include any 85 // framing (gRPC or HTTP/2). 86 Length int 87 // CompressedLength is the size of the compressed payload data. Does not 88 // include any framing (gRPC or HTTP/2). Same as Length if compression not 89 // enabled. 90 CompressedLength int 91 // WireLength is the size of the compressed payload data plus gRPC framing. 92 // Does not include HTTP/2 framing. 93 WireLength int 94 95 // RecvTime is the time when the payload is received. 96 RecvTime time.Time 97 } 98 99 // IsClient indicates if the stats information is from client side. 100 func (s *InPayload) IsClient() bool { return s.Client } 101 102 func (s *InPayload) isRPCStats() {} 103 104 // InHeader contains stats when a header is received. 105 type InHeader struct { 106 // Client is true if this InHeader is from client side. 107 Client bool 108 // WireLength is the wire length of header. 109 WireLength int 110 // Compression is the compression algorithm used for the RPC. 111 Compression string 112 // Header contains the header metadata received. 113 Header metadata.MD 114 115 // The following fields are valid only if Client is false. 116 // FullMethod is the full RPC method string, i.e., /package.service/method. 117 FullMethod string 118 // RemoteAddr is the remote address of the corresponding connection. 119 RemoteAddr net.Addr 120 // LocalAddr is the local address of the corresponding connection. 121 LocalAddr net.Addr 122 } 123 124 // IsClient indicates if the stats information is from client side. 125 func (s *InHeader) IsClient() bool { return s.Client } 126 127 func (s *InHeader) isRPCStats() {} 128 129 // InTrailer contains stats when a trailer is received. 130 type InTrailer struct { 131 // Client is true if this InTrailer is from client side. 132 Client bool 133 // WireLength is the wire length of trailer. 134 WireLength int 135 // Trailer contains the trailer metadata received from the server. This 136 // field is only valid if this InTrailer is from the client side. 137 Trailer metadata.MD 138 } 139 140 // IsClient indicates if the stats information is from client side. 141 func (s *InTrailer) IsClient() bool { return s.Client } 142 143 func (s *InTrailer) isRPCStats() {} 144 145 // OutPayload contains the information for an outgoing payload. 146 type OutPayload struct { 147 // Client is true if this OutPayload is from client side. 148 Client bool 149 // Payload is the payload with original type. This may be modified after 150 // the call to HandleRPC which provides the OutPayload returns and must be 151 // copied if needed later. 152 Payload any 153 // Data is the serialized message payload. 154 // Deprecated: Data will be removed in the next release. 155 Data []byte 156 // Length is the size of the uncompressed payload data. Does not include any 157 // framing (gRPC or HTTP/2). 158 Length int 159 // CompressedLength is the size of the compressed payload data. Does not 160 // include any framing (gRPC or HTTP/2). Same as Length if compression not 161 // enabled. 162 CompressedLength int 163 // WireLength is the size of the compressed payload data plus gRPC framing. 164 // Does not include HTTP/2 framing. 165 WireLength int 166 // SentTime is the time when the payload is sent. 167 SentTime time.Time 168 } 169 170 // IsClient indicates if this stats information is from client side. 171 func (s *OutPayload) IsClient() bool { return s.Client } 172 173 func (s *OutPayload) isRPCStats() {} 174 175 // OutHeader contains stats when a header is sent. 176 type OutHeader struct { 177 // Client is true if this OutHeader is from client side. 178 Client bool 179 // Compression is the compression algorithm used for the RPC. 180 Compression string 181 // Header contains the header metadata sent. 182 Header metadata.MD 183 184 // The following fields are valid only if Client is true. 185 // FullMethod is the full RPC method string, i.e., /package.service/method. 186 FullMethod string 187 // RemoteAddr is the remote address of the corresponding connection. 188 RemoteAddr net.Addr 189 // LocalAddr is the local address of the corresponding connection. 190 LocalAddr net.Addr 191 } 192 193 // IsClient indicates if this stats information is from client side. 194 func (s *OutHeader) IsClient() bool { return s.Client } 195 196 func (s *OutHeader) isRPCStats() {} 197 198 // OutTrailer contains stats when a trailer is sent. 199 type OutTrailer struct { 200 // Client is true if this OutTrailer is from client side. 201 Client bool 202 // WireLength is the wire length of trailer. 203 // 204 // Deprecated: This field is never set. The length is not known when this message is 205 // emitted because the trailer fields are compressed with hpack after that. 206 WireLength int 207 // Trailer contains the trailer metadata sent to the client. This 208 // field is only valid if this OutTrailer is from the server side. 209 Trailer metadata.MD 210 } 211 212 // IsClient indicates if this stats information is from client side. 213 func (s *OutTrailer) IsClient() bool { return s.Client } 214 215 func (s *OutTrailer) isRPCStats() {} 216 217 // End contains stats when an RPC ends. 218 type End struct { 219 // Client is true if this End is from client side. 220 Client bool 221 // BeginTime is the time when the RPC began. 222 BeginTime time.Time 223 // EndTime is the time when the RPC ends. 224 EndTime time.Time 225 // Trailer contains the trailer metadata received from the server. This 226 // field is only valid if this End is from the client side. 227 // Deprecated: use Trailer in InTrailer instead. 228 Trailer metadata.MD 229 // Error is the error the RPC ended with. It is an error generated from 230 // status.Status and can be converted back to status.Status using 231 // status.FromError if non-nil. 232 Error error 233 } 234 235 // IsClient indicates if this is from client side. 236 func (s *End) IsClient() bool { return s.Client } 237 238 func (s *End) isRPCStats() {} 239 240 // ConnStats contains stats information about connections. 241 type ConnStats interface { 242 isConnStats() 243 // IsClient returns true if this ConnStats is from client side. 244 IsClient() bool 245 } 246 247 // ConnBegin contains the stats of a connection when it is established. 248 type ConnBegin struct { 249 // Client is true if this ConnBegin is from client side. 250 Client bool 251 } 252 253 // IsClient indicates if this is from client side. 254 func (s *ConnBegin) IsClient() bool { return s.Client } 255 256 func (s *ConnBegin) isConnStats() {} 257 258 // ConnEnd contains the stats of a connection when it ends. 259 type ConnEnd struct { 260 // Client is true if this ConnEnd is from client side. 261 Client bool 262 } 263 264 // IsClient indicates if this is from client side. 265 func (s *ConnEnd) IsClient() bool { return s.Client } 266 267 func (s *ConnEnd) isConnStats() {} 268 269 type incomingTagsKey struct{} 270 type outgoingTagsKey struct{} 271 272 // SetTags attaches stats tagging data to the context, which will be sent in 273 // the outgoing RPC with the header grpc-tags-bin. Subsequent calls to 274 // SetTags will overwrite the values from earlier calls. 275 // 276 // NOTE: this is provided only for backward compatibility with existing clients 277 // and will likely be removed in an upcoming release. New uses should transmit 278 // this type of data using metadata with a different, non-reserved (i.e. does 279 // not begin with "grpc-") header name. 280 func SetTags(ctx context.Context, b []byte) context.Context { 281 return context.WithValue(ctx, outgoingTagsKey{}, b) 282 } 283 284 // Tags returns the tags from the context for the inbound RPC. 285 // 286 // NOTE: this is provided only for backward compatibility with existing clients 287 // and will likely be removed in an upcoming release. New uses should transmit 288 // this type of data using metadata with a different, non-reserved (i.e. does 289 // not begin with "grpc-") header name. 290 func Tags(ctx context.Context) []byte { 291 b, _ := ctx.Value(incomingTagsKey{}).([]byte) 292 return b 293 } 294 295 // SetIncomingTags attaches stats tagging data to the context, to be read by 296 // the application (not sent in outgoing RPCs). 297 // 298 // This is intended for gRPC-internal use ONLY. 299 func SetIncomingTags(ctx context.Context, b []byte) context.Context { 300 return context.WithValue(ctx, incomingTagsKey{}, b) 301 } 302 303 // OutgoingTags returns the tags from the context for the outbound RPC. 304 // 305 // This is intended for gRPC-internal use ONLY. 306 func OutgoingTags(ctx context.Context) []byte { 307 b, _ := ctx.Value(outgoingTagsKey{}).([]byte) 308 return b 309 } 310 311 type incomingTraceKey struct{} 312 type outgoingTraceKey struct{} 313 314 // SetTrace attaches stats tagging data to the context, which will be sent in 315 // the outgoing RPC with the header grpc-trace-bin. Subsequent calls to 316 // SetTrace will overwrite the values from earlier calls. 317 // 318 // NOTE: this is provided only for backward compatibility with existing clients 319 // and will likely be removed in an upcoming release. New uses should transmit 320 // this type of data using metadata with a different, non-reserved (i.e. does 321 // not begin with "grpc-") header name. 322 func SetTrace(ctx context.Context, b []byte) context.Context { 323 return context.WithValue(ctx, outgoingTraceKey{}, b) 324 } 325 326 // Trace returns the trace from the context for the inbound RPC. 327 // 328 // NOTE: this is provided only for backward compatibility with existing clients 329 // and will likely be removed in an upcoming release. New uses should transmit 330 // this type of data using metadata with a different, non-reserved (i.e. does 331 // not begin with "grpc-") header name. 332 func Trace(ctx context.Context) []byte { 333 b, _ := ctx.Value(incomingTraceKey{}).([]byte) 334 return b 335 } 336 337 // SetIncomingTrace attaches stats tagging data to the context, to be read by 338 // the application (not sent in outgoing RPCs). It is intended for 339 // gRPC-internal use. 340 func SetIncomingTrace(ctx context.Context, b []byte) context.Context { 341 return context.WithValue(ctx, incomingTraceKey{}, b) 342 } 343 344 // OutgoingTrace returns the trace from the context for the outbound RPC. It is 345 // intended for gRPC-internal use. 346 func OutgoingTrace(ctx context.Context) []byte { 347 b, _ := ctx.Value(outgoingTraceKey{}).([]byte) 348 return b 349 } 350