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