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. 22package stats // import "google.golang.org/grpc/stats" 23 24import ( 25 "context" 26 "net" 27 "time" 28 29 "google.golang.org/grpc/metadata" 30) 31 32// RPCStats contains stats information about RPCs. 33type 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. 41type 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. 58func (s *Begin) IsClient() bool { return s.Client } 59 60func (s *Begin) isRPCStats() {} 61 62// InPayload contains the information for an incoming payload. 63type InPayload struct { 64 // Client is true if this InPayload is from client side. 65 Client bool 66 // Payload is the payload with original type. 67 Payload interface{} 68 // Data is the serialized message payload. 69 Data []byte 70 // Length is the length of uncompressed data. 71 Length int 72 // WireLength is the length of data on wire (compressed, signed, encrypted). 73 WireLength int 74 // RecvTime is the time when the payload is received. 75 RecvTime time.Time 76} 77 78// IsClient indicates if the stats information is from client side. 79func (s *InPayload) IsClient() bool { return s.Client } 80 81func (s *InPayload) isRPCStats() {} 82 83// InHeader contains stats when a header is received. 84type InHeader struct { 85 // Client is true if this InHeader is from client side. 86 Client bool 87 // WireLength is the wire length of header. 88 WireLength int 89 // Compression is the compression algorithm used for the RPC. 90 Compression string 91 // Header contains the header metadata received. 92 Header metadata.MD 93 94 // The following fields are valid only if Client is false. 95 // FullMethod is the full RPC method string, i.e., /package.service/method. 96 FullMethod string 97 // RemoteAddr is the remote address of the corresponding connection. 98 RemoteAddr net.Addr 99 // LocalAddr is the local address of the corresponding connection. 100 LocalAddr net.Addr 101} 102 103// IsClient indicates if the stats information is from client side. 104func (s *InHeader) IsClient() bool { return s.Client } 105 106func (s *InHeader) isRPCStats() {} 107 108// InTrailer contains stats when a trailer is received. 109type InTrailer struct { 110 // Client is true if this InTrailer is from client side. 111 Client bool 112 // WireLength is the wire length of trailer. 113 WireLength int 114 // Trailer contains the trailer metadata received from the server. This 115 // field is only valid if this InTrailer is from the client side. 116 Trailer metadata.MD 117} 118 119// IsClient indicates if the stats information is from client side. 120func (s *InTrailer) IsClient() bool { return s.Client } 121 122func (s *InTrailer) isRPCStats() {} 123 124// OutPayload contains the information for an outgoing payload. 125type OutPayload struct { 126 // Client is true if this OutPayload is from client side. 127 Client bool 128 // Payload is the payload with original type. 129 Payload interface{} 130 // Data is the serialized message payload. 131 Data []byte 132 // Length is the length of uncompressed data. 133 Length int 134 // WireLength is the length of data on wire (compressed, signed, encrypted). 135 WireLength int 136 // SentTime is the time when the payload is sent. 137 SentTime time.Time 138} 139 140// IsClient indicates if this stats information is from client side. 141func (s *OutPayload) IsClient() bool { return s.Client } 142 143func (s *OutPayload) isRPCStats() {} 144 145// OutHeader contains stats when a header is sent. 146type OutHeader struct { 147 // Client is true if this OutHeader is from client side. 148 Client bool 149 // Compression is the compression algorithm used for the RPC. 150 Compression string 151 // Header contains the header metadata sent. 152 Header metadata.MD 153 154 // The following fields are valid only if Client is true. 155 // FullMethod is the full RPC method string, i.e., /package.service/method. 156 FullMethod string 157 // RemoteAddr is the remote address of the corresponding connection. 158 RemoteAddr net.Addr 159 // LocalAddr is the local address of the corresponding connection. 160 LocalAddr net.Addr 161} 162 163// IsClient indicates if this stats information is from client side. 164func (s *OutHeader) IsClient() bool { return s.Client } 165 166func (s *OutHeader) isRPCStats() {} 167 168// OutTrailer contains stats when a trailer is sent. 169type OutTrailer struct { 170 // Client is true if this OutTrailer is from client side. 171 Client bool 172 // WireLength is the wire length of trailer. 173 // 174 // Deprecated: This field is never set. The length is not known when this message is 175 // emitted because the trailer fields are compressed with hpack after that. 176 WireLength int 177 // Trailer contains the trailer metadata sent to the client. This 178 // field is only valid if this OutTrailer is from the server side. 179 Trailer metadata.MD 180} 181 182// IsClient indicates if this stats information is from client side. 183func (s *OutTrailer) IsClient() bool { return s.Client } 184 185func (s *OutTrailer) isRPCStats() {} 186 187// End contains stats when an RPC ends. 188type End struct { 189 // Client is true if this End is from client side. 190 Client bool 191 // BeginTime is the time when the RPC began. 192 BeginTime time.Time 193 // EndTime is the time when the RPC ends. 194 EndTime time.Time 195 // Trailer contains the trailer metadata received from the server. This 196 // field is only valid if this End is from the client side. 197 // Deprecated: use Trailer in InTrailer instead. 198 Trailer metadata.MD 199 // Error is the error the RPC ended with. It is an error generated from 200 // status.Status and can be converted back to status.Status using 201 // status.FromError if non-nil. 202 Error error 203} 204 205// IsClient indicates if this is from client side. 206func (s *End) IsClient() bool { return s.Client } 207 208func (s *End) isRPCStats() {} 209 210// ConnStats contains stats information about connections. 211type ConnStats interface { 212 isConnStats() 213 // IsClient returns true if this ConnStats is from client side. 214 IsClient() bool 215} 216 217// ConnBegin contains the stats of a connection when it is established. 218type ConnBegin struct { 219 // Client is true if this ConnBegin is from client side. 220 Client bool 221} 222 223// IsClient indicates if this is from client side. 224func (s *ConnBegin) IsClient() bool { return s.Client } 225 226func (s *ConnBegin) isConnStats() {} 227 228// ConnEnd contains the stats of a connection when it ends. 229type ConnEnd struct { 230 // Client is true if this ConnEnd is from client side. 231 Client bool 232} 233 234// IsClient indicates if this is from client side. 235func (s *ConnEnd) IsClient() bool { return s.Client } 236 237func (s *ConnEnd) isConnStats() {} 238 239type incomingTagsKey struct{} 240type outgoingTagsKey struct{} 241 242// SetTags attaches stats tagging data to the context, which will be sent in 243// the outgoing RPC with the header grpc-tags-bin. Subsequent calls to 244// SetTags will overwrite the values from earlier calls. 245// 246// NOTE: this is provided only for backward compatibility with existing clients 247// and will likely be removed in an upcoming release. New uses should transmit 248// this type of data using metadata with a different, non-reserved (i.e. does 249// not begin with "grpc-") header name. 250func SetTags(ctx context.Context, b []byte) context.Context { 251 return context.WithValue(ctx, outgoingTagsKey{}, b) 252} 253 254// Tags returns the tags from the context for the inbound RPC. 255// 256// NOTE: this is provided only for backward compatibility with existing clients 257// and will likely be removed in an upcoming release. New uses should transmit 258// this type of data using metadata with a different, non-reserved (i.e. does 259// not begin with "grpc-") header name. 260func Tags(ctx context.Context) []byte { 261 b, _ := ctx.Value(incomingTagsKey{}).([]byte) 262 return b 263} 264 265// SetIncomingTags attaches stats tagging data to the context, to be read by 266// the application (not sent in outgoing RPCs). 267// 268// This is intended for gRPC-internal use ONLY. 269func SetIncomingTags(ctx context.Context, b []byte) context.Context { 270 return context.WithValue(ctx, incomingTagsKey{}, b) 271} 272 273// OutgoingTags returns the tags from the context for the outbound RPC. 274// 275// This is intended for gRPC-internal use ONLY. 276func OutgoingTags(ctx context.Context) []byte { 277 b, _ := ctx.Value(outgoingTagsKey{}).([]byte) 278 return b 279} 280 281type incomingTraceKey struct{} 282type outgoingTraceKey struct{} 283 284// SetTrace attaches stats tagging data to the context, which will be sent in 285// the outgoing RPC with the header grpc-trace-bin. Subsequent calls to 286// SetTrace will overwrite the values from earlier calls. 287// 288// NOTE: this is provided only for backward compatibility with existing clients 289// and will likely be removed in an upcoming release. New uses should transmit 290// this type of data using metadata with a different, non-reserved (i.e. does 291// not begin with "grpc-") header name. 292func SetTrace(ctx context.Context, b []byte) context.Context { 293 return context.WithValue(ctx, outgoingTraceKey{}, b) 294} 295 296// Trace returns the trace from the context for the inbound RPC. 297// 298// NOTE: this is provided only for backward compatibility with existing clients 299// and will likely be removed in an upcoming release. New uses should transmit 300// this type of data using metadata with a different, non-reserved (i.e. does 301// not begin with "grpc-") header name. 302func Trace(ctx context.Context) []byte { 303 b, _ := ctx.Value(incomingTraceKey{}).([]byte) 304 return b 305} 306 307// SetIncomingTrace attaches stats tagging data to the context, to be read by 308// the application (not sent in outgoing RPCs). It is intended for 309// gRPC-internal use. 310func SetIncomingTrace(ctx context.Context, b []byte) context.Context { 311 return context.WithValue(ctx, incomingTraceKey{}, b) 312} 313 314// OutgoingTrace returns the trace from the context for the outbound RPC. It is 315// intended for gRPC-internal use. 316func OutgoingTrace(ctx context.Context) []byte { 317 b, _ := ctx.Value(outgoingTraceKey{}).([]byte) 318 return b 319} 320