vendor/google.golang.org/grpc/stats/stats.go

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