blob: a7970c79abe5dd09d6b9f18a9834307a0954b6f7 [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
amit.ghosh258d14c2020-10-02 15:13:38 +020084 // Compression is the compression algorithm used for the RPC.
85 Compression string
86 // Header contains the header metadata received.
87 Header metadata.MD
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -070088
89 // The following fields are valid only if Client is false.
90 // FullMethod is the full RPC method string, i.e., /package.service/method.
91 FullMethod string
92 // RemoteAddr is the remote address of the corresponding connection.
93 RemoteAddr net.Addr
94 // LocalAddr is the local address of the corresponding connection.
95 LocalAddr net.Addr
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
amit.ghosh258d14c2020-10-02 15:13:38 +0200144 // Compression is the compression algorithm used for the RPC.
145 Compression string
146 // Header contains the header metadata sent.
147 Header metadata.MD
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700148
149 // The following fields are valid only if Client is true.
150 // FullMethod is the full RPC method string, i.e., /package.service/method.
151 FullMethod string
152 // RemoteAddr is the remote address of the corresponding connection.
153 RemoteAddr net.Addr
154 // LocalAddr is the local address of the corresponding connection.
155 LocalAddr net.Addr
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.
amit.ghosh258d14c2020-10-02 15:13:38 +0200168 //
169 // Deprecated: This field is never set. The length is not known when this message is
170 // emitted because the trailer fields are compressed with hpack after that.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700171 WireLength int
Arjun E K57a7fcb2020-01-30 06:44:45 +0000172 // Trailer contains the trailer metadata sent to the client. This
173 // field is only valid if this OutTrailer is from the server side.
174 Trailer metadata.MD
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700175}
176
177// IsClient indicates if this stats information is from client side.
178func (s *OutTrailer) IsClient() bool { return s.Client }
179
180func (s *OutTrailer) isRPCStats() {}
181
182// End contains stats when an RPC ends.
183type End struct {
184 // Client is true if this End is from client side.
185 Client bool
186 // BeginTime is the time when the RPC began.
187 BeginTime time.Time
188 // EndTime is the time when the RPC ends.
189 EndTime time.Time
190 // Trailer contains the trailer metadata received from the server. This
191 // field is only valid if this End is from the client side.
Arjun E K57a7fcb2020-01-30 06:44:45 +0000192 // Deprecated: use Trailer in InTrailer instead.
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -0700193 Trailer metadata.MD
194 // Error is the error the RPC ended with. It is an error generated from
195 // status.Status and can be converted back to status.Status using
196 // status.FromError if non-nil.
197 Error error
198}
199
200// IsClient indicates if this is from client side.
201func (s *End) IsClient() bool { return s.Client }
202
203func (s *End) isRPCStats() {}
204
205// ConnStats contains stats information about connections.
206type ConnStats interface {
207 isConnStats()
208 // IsClient returns true if this ConnStats is from client side.
209 IsClient() bool
210}
211
212// ConnBegin contains the stats of a connection when it is established.
213type ConnBegin struct {
214 // Client is true if this ConnBegin is from client side.
215 Client bool
216}
217
218// IsClient indicates if this is from client side.
219func (s *ConnBegin) IsClient() bool { return s.Client }
220
221func (s *ConnBegin) isConnStats() {}
222
223// ConnEnd contains the stats of a connection when it ends.
224type ConnEnd struct {
225 // Client is true if this ConnEnd is from client side.
226 Client bool
227}
228
229// IsClient indicates if this is from client side.
230func (s *ConnEnd) IsClient() bool { return s.Client }
231
232func (s *ConnEnd) isConnStats() {}
233
234type incomingTagsKey struct{}
235type outgoingTagsKey struct{}
236
237// SetTags attaches stats tagging data to the context, which will be sent in
238// the outgoing RPC with the header grpc-tags-bin. Subsequent calls to
239// SetTags will overwrite the values from earlier calls.
240//
241// NOTE: this is provided only for backward compatibility with existing clients
242// and will likely be removed in an upcoming release. New uses should transmit
243// this type of data using metadata with a different, non-reserved (i.e. does
244// not begin with "grpc-") header name.
245func SetTags(ctx context.Context, b []byte) context.Context {
246 return context.WithValue(ctx, outgoingTagsKey{}, b)
247}
248
249// Tags returns the tags from the context for the inbound RPC.
250//
251// NOTE: this is provided only for backward compatibility with existing clients
252// and will likely be removed in an upcoming release. New uses should transmit
253// this type of data using metadata with a different, non-reserved (i.e. does
254// not begin with "grpc-") header name.
255func Tags(ctx context.Context) []byte {
256 b, _ := ctx.Value(incomingTagsKey{}).([]byte)
257 return b
258}
259
260// SetIncomingTags attaches stats tagging data to the context, to be read by
261// the application (not sent in outgoing RPCs).
262//
263// This is intended for gRPC-internal use ONLY.
264func SetIncomingTags(ctx context.Context, b []byte) context.Context {
265 return context.WithValue(ctx, incomingTagsKey{}, b)
266}
267
268// OutgoingTags returns the tags from the context for the outbound RPC.
269//
270// This is intended for gRPC-internal use ONLY.
271func OutgoingTags(ctx context.Context) []byte {
272 b, _ := ctx.Value(outgoingTagsKey{}).([]byte)
273 return b
274}
275
276type incomingTraceKey struct{}
277type outgoingTraceKey struct{}
278
279// SetTrace attaches stats tagging data to the context, which will be sent in
280// the outgoing RPC with the header grpc-trace-bin. Subsequent calls to
281// SetTrace will overwrite the values from earlier calls.
282//
283// NOTE: this is provided only for backward compatibility with existing clients
284// and will likely be removed in an upcoming release. New uses should transmit
285// this type of data using metadata with a different, non-reserved (i.e. does
286// not begin with "grpc-") header name.
287func SetTrace(ctx context.Context, b []byte) context.Context {
288 return context.WithValue(ctx, outgoingTraceKey{}, b)
289}
290
291// Trace returns the trace from the context for the inbound RPC.
292//
293// NOTE: this is provided only for backward compatibility with existing clients
294// and will likely be removed in an upcoming release. New uses should transmit
295// this type of data using metadata with a different, non-reserved (i.e. does
296// not begin with "grpc-") header name.
297func Trace(ctx context.Context) []byte {
298 b, _ := ctx.Value(incomingTraceKey{}).([]byte)
299 return b
300}
301
302// SetIncomingTrace attaches stats tagging data to the context, to be read by
303// the application (not sent in outgoing RPCs). It is intended for
304// gRPC-internal use.
305func SetIncomingTrace(ctx context.Context, b []byte) context.Context {
306 return context.WithValue(ctx, incomingTraceKey{}, b)
307}
308
309// OutgoingTrace returns the trace from the context for the outbound RPC. It is
310// intended for gRPC-internal use.
311func OutgoingTrace(ctx context.Context) []byte {
312 b, _ := ctx.Value(outgoingTraceKey{}).([]byte)
313 return b
314}