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         "net"
  28         "time"
  29
  30         "golang.org/x/net/context"
  31 )
  32
  33 // RPCStats contains stats information about RPCs.
  34 type 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.
  42 type 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.
  52 func (s *Begin) IsClient() bool { return s.Client }
  53
  54 func (s *Begin) isRPCStats() {}
  55
  56 // InPayload contains the information for an incoming payload.
  57 type 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.
  73 func (s *InPayload) IsClient() bool { return s.Client }
  74
  75 func (s *InPayload) isRPCStats() {}
  76
  77 // InHeader contains stats when a header is received.
  78 type 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.
  96 func (s *InHeader) IsClient() bool { return s.Client }
  97
  98 func (s *InHeader) isRPCStats() {}
  99
 100 // InTrailer contains stats when a trailer is received.
 101 type 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.
 109 func (s *InTrailer) IsClient() bool { return s.Client }
 110
 111 func (s *InTrailer) isRPCStats() {}
 112
 113 // OutPayload contains the information for an outgoing payload.
 114 type 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.
 130 func (s *OutPayload) IsClient() bool { return s.Client }
 131
 132 func (s *OutPayload) isRPCStats() {}
 133
 134 // OutHeader contains stats when a header is sent.
 135 type 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.
 151 func (s *OutHeader) IsClient() bool { return s.Client }
 152
 153 func (s *OutHeader) isRPCStats() {}
 154
 155 // OutTrailer contains stats when a trailer is sent.
 156 type 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.
 164 func (s *OutTrailer) IsClient() bool { return s.Client }
 165
 166 func (s *OutTrailer) isRPCStats() {}
 167
 168 // End contains stats when an RPC ends.
 169 type End struct {
 170         // Client is true if this End is from client side.
 171         Client bool
 172         // EndTime is the time when the RPC ends.
 173         EndTime time.Time
 174         // Error is the error the RPC ended with. It is an error generated from
 175         // status.Status and can be converted back to status.Status using
 176         // status.FromError if non-nil.
 177         Error error
 178 }
 179
 180 // IsClient indicates if this is from client side.
 181 func (s *End) IsClient() bool { return s.Client }
 182
 183 func (s *End) isRPCStats() {}
 184
 185 // ConnStats contains stats information about connections.
 186 type ConnStats interface {
 187         isConnStats()
 188         // IsClient returns true if this ConnStats is from client side.
 189         IsClient() bool
 190 }
 191
 192 // ConnBegin contains the stats of a connection when it is established.
 193 type ConnBegin struct {
 194         // Client is true if this ConnBegin is from client side.
 195         Client bool
 196 }
 197
 198 // IsClient indicates if this is from client side.
 199 func (s *ConnBegin) IsClient() bool { return s.Client }
 200
 201 func (s *ConnBegin) isConnStats() {}
 202
 203 // ConnEnd contains the stats of a connection when it ends.
 204 type ConnEnd struct {
 205         // Client is true if this ConnEnd is from client side.
 206         Client bool
 207 }
 208
 209 // IsClient indicates if this is from client side.
 210 func (s *ConnEnd) IsClient() bool { return s.Client }
 211
 212 func (s *ConnEnd) isConnStats() {}
 213
 214 type incomingTagsKey struct{}
 215 type outgoingTagsKey struct{}
 216
 217 // SetTags attaches stats tagging data to the context, which will be sent in
 218 // the outgoing RPC with the header grpc-tags-bin.  Subsequent calls to
 219 // SetTags will overwrite the values from earlier calls.
 220 //
 221 // NOTE: this is provided only for backward compatibility with existing clients
 222 // and will likely be removed in an upcoming release.  New uses should transmit
 223 // this type of data using metadata with a different, non-reserved (i.e. does
 224 // not begin with "grpc-") header name.
 225 func SetTags(ctx context.Context, b []byte) context.Context {
 226         return context.WithValue(ctx, outgoingTagsKey{}, b)
 227 }
 228
 229 // Tags returns the tags from the context for the inbound RPC.
 230 //
 231 // NOTE: this is provided only for backward compatibility with existing clients
 232 // and will likely be removed in an upcoming release.  New uses should transmit
 233 // this type of data using metadata with a different, non-reserved (i.e. does
 234 // not begin with "grpc-") header name.
 235 func Tags(ctx context.Context) []byte {
 236         b, _ := ctx.Value(incomingTagsKey{}).([]byte)
 237         return b
 238 }
 239
 240 // SetIncomingTags attaches stats tagging data to the context, to be read by
 241 // the application (not sent in outgoing RPCs).
 242 //
 243 // This is intended for gRPC-internal use ONLY.
 244 func SetIncomingTags(ctx context.Context, b []byte) context.Context {
 245         return context.WithValue(ctx, incomingTagsKey{}, b)
 246 }
 247
 248 // OutgoingTags returns the tags from the context for the outbound RPC.
 249 //
 250 // This is intended for gRPC-internal use ONLY.
 251 func OutgoingTags(ctx context.Context) []byte {
 252         b, _ := ctx.Value(outgoingTagsKey{}).([]byte)
 253         return b
 254 }
 255
 256 type incomingTraceKey struct{}
 257 type outgoingTraceKey struct{}
 258
 259 // SetTrace attaches stats tagging data to the context, which will be sent in
 260 // the outgoing RPC with the header grpc-trace-bin.  Subsequent calls to
 261 // SetTrace will overwrite the values from earlier calls.
 262 //
 263 // NOTE: this is provided only for backward compatibility with existing clients
 264 // and will likely be removed in an upcoming release.  New uses should transmit
 265 // this type of data using metadata with a different, non-reserved (i.e. does
 266 // not begin with "grpc-") header name.
 267 func SetTrace(ctx context.Context, b []byte) context.Context {
 268         return context.WithValue(ctx, outgoingTraceKey{}, b)
 269 }
 270
 271 // Trace returns the trace from the context for the inbound RPC.
 272 //
 273 // NOTE: this is provided only for backward compatibility with existing clients
 274 // and will likely be removed in an upcoming release.  New uses should transmit
 275 // this type of data using metadata with a different, non-reserved (i.e. does
 276 // not begin with "grpc-") header name.
 277 func Trace(ctx context.Context) []byte {
 278         b, _ := ctx.Value(incomingTraceKey{}).([]byte)
 279         return b
 280 }
 281
 282 // SetIncomingTrace attaches stats tagging data to the context, to be read by
 283 // the application (not sent in outgoing RPCs).  It is intended for
 284 // gRPC-internal use.
 285 func SetIncomingTrace(ctx context.Context, b []byte) context.Context {
 286         return context.WithValue(ctx, incomingTraceKey{}, b)
 287 }
 288
 289 // OutgoingTrace returns the trace from the context for the outbound RPC.  It is
 290 // intended for gRPC-internal use.
 291 func OutgoingTrace(ctx context.Context) []byte {
 292         b, _ := ctx.Value(outgoingTraceKey{}).([]byte)
 293         return b
 294 }