blob: 9e22c393f16882f3b49dee41cfaf2fe31cfc2cfa [file] [log] [blame]
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -07001/*
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
Arjun E K57a7fcb2020-01-30 06:44:45 +000094 // Header contains the header metadata received.
95 Header metadata.MD
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070096}
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
Arjun E K57a7fcb2020-01-30 06:44:45 +0000109 // 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
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700112}
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
Arjun E K57a7fcb2020-01-30 06:44:45 +0000154 // Header contains the header metadata sent.
155 Header metadata.MD
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700156}
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
Arjun E K57a7fcb2020-01-30 06:44:45 +0000169 // 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
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700172}
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.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000189 // Deprecated: use Trailer in InTrailer instead.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700190 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}