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