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