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// Package stats is for collecting and reporting various network and RPC stats.
20// This package is for monitoring purpose only. All fields are read-only.
21// All APIs are experimental.
22package stats // import "google.golang.org/grpc/stats"
23
24import (
25 "context"
26 "net"
27 "time"
28
29 "google.golang.org/grpc/metadata"
30)
31
32// RPCStats contains stats information about RPCs.
33type 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 attempt begins.
40// FailFast is only valid if this Begin is from client side.
41type Begin struct {
42 // Client is true if this Begin is from client side.
43 Client bool
44 // BeginTime is the time when the RPC attempt begins.
45 BeginTime time.Time
46 // FailFast indicates if this RPC is failfast.
47 FailFast bool
48 // IsClientStream indicates whether the RPC is a client streaming RPC.
49 IsClientStream bool
50 // IsServerStream indicates whether the RPC is a server streaming RPC.
51 IsServerStream bool
52 // IsTransparentRetryAttempt indicates whether this attempt was initiated
53 // due to transparently retrying a previous attempt.
54 IsTransparentRetryAttempt bool
55}
56
57// IsClient indicates if the stats information is from client side.
58func (s *Begin) IsClient() bool { return s.Client }
59
60func (s *Begin) isRPCStats() {}
61
62// PickerUpdated indicates that the LB policy provided a new picker while the
63// RPC was waiting for one.
64type PickerUpdated struct{}
65
66// IsClient indicates if the stats information is from client side. Only Client
67// Side interfaces with a Picker, thus always returns true.
68func (*PickerUpdated) IsClient() bool { return true }
69
70func (*PickerUpdated) isRPCStats() {}
71
72// InPayload contains the information for an incoming payload.
73type InPayload struct {
74 // Client is true if this InPayload is from client side.
75 Client bool
76 // Payload is the payload with original type. This may be modified after
77 // the call to HandleRPC which provides the InPayload returns and must be
78 // copied if needed later.
79 Payload any
80
81 // Length is the size of the uncompressed payload data. Does not include any
82 // framing (gRPC or HTTP/2).
83 Length int
84 // CompressedLength is the size of the compressed payload data. Does not
85 // include any framing (gRPC or HTTP/2). Same as Length if compression not
86 // enabled.
87 CompressedLength int
88 // WireLength is the size of the compressed payload data plus gRPC framing.
89 // Does not include HTTP/2 framing.
90 WireLength int
91
92 // RecvTime is the time when the payload is received.
93 RecvTime time.Time
94}
95
96// IsClient indicates if the stats information is from client side.
97func (s *InPayload) IsClient() bool { return s.Client }
98
99func (s *InPayload) isRPCStats() {}
100
101// InHeader contains stats when a header is received.
102type InHeader struct {
103 // Client is true if this InHeader is from client side.
104 Client bool
105 // WireLength is the wire length of header.
106 WireLength int
107 // Compression is the compression algorithm used for the RPC.
108 Compression string
109 // Header contains the header metadata received.
110 Header metadata.MD
111
112 // The following fields are valid only if Client is false.
113 // FullMethod is the full RPC method string, i.e., /package.service/method.
114 FullMethod string
115 // RemoteAddr is the remote address of the corresponding connection.
116 RemoteAddr net.Addr
117 // LocalAddr is the local address of the corresponding connection.
118 LocalAddr net.Addr
119}
120
121// IsClient indicates if the stats information is from client side.
122func (s *InHeader) IsClient() bool { return s.Client }
123
124func (s *InHeader) isRPCStats() {}
125
126// InTrailer contains stats when a trailer is received.
127type InTrailer struct {
128 // Client is true if this InTrailer is from client side.
129 Client bool
130 // WireLength is the wire length of trailer.
131 WireLength int
132 // Trailer contains the trailer metadata received from the server. This
133 // field is only valid if this InTrailer is from the client side.
134 Trailer metadata.MD
135}
136
137// IsClient indicates if the stats information is from client side.
138func (s *InTrailer) IsClient() bool { return s.Client }
139
140func (s *InTrailer) isRPCStats() {}
141
142// OutPayload contains the information for an outgoing payload.
143type OutPayload struct {
144 // Client is true if this OutPayload is from client side.
145 Client bool
146 // Payload is the payload with original type. This may be modified after
147 // the call to HandleRPC which provides the OutPayload returns and must be
148 // copied if needed later.
149 Payload any
150 // Length is the size of the uncompressed payload data. Does not include any
151 // framing (gRPC or HTTP/2).
152 Length int
153 // CompressedLength is the size of the compressed payload data. Does not
154 // include any framing (gRPC or HTTP/2). Same as Length if compression not
155 // enabled.
156 CompressedLength int
157 // WireLength is the size of the compressed payload data plus gRPC framing.
158 // Does not include HTTP/2 framing.
159 WireLength int
160 // SentTime is the time when the payload is sent.
161 SentTime time.Time
162}
163
164// IsClient indicates if this stats information is from client side.
165func (s *OutPayload) IsClient() bool { return s.Client }
166
167func (s *OutPayload) isRPCStats() {}
168
169// OutHeader contains stats when a header is sent.
170type OutHeader struct {
171 // Client is true if this OutHeader is from client side.
172 Client bool
173 // Compression is the compression algorithm used for the RPC.
174 Compression string
175 // Header contains the header metadata sent.
176 Header metadata.MD
177
178 // The following fields are valid only if Client is true.
179 // FullMethod is the full RPC method string, i.e., /package.service/method.
180 FullMethod string
181 // RemoteAddr is the remote address of the corresponding connection.
182 RemoteAddr net.Addr
183 // LocalAddr is the local address of the corresponding connection.
184 LocalAddr net.Addr
185}
186
187// IsClient indicates if this stats information is from client side.
188func (s *OutHeader) IsClient() bool { return s.Client }
189
190func (s *OutHeader) isRPCStats() {}
191
192// OutTrailer contains stats when a trailer is sent.
193type OutTrailer struct {
194 // Client is true if this OutTrailer is from client side.
195 Client bool
196 // WireLength is the wire length of trailer.
197 //
198 // Deprecated: This field is never set. The length is not known when this message is
199 // emitted because the trailer fields are compressed with hpack after that.
200 WireLength int
201 // Trailer contains the trailer metadata sent to the client. This
202 // field is only valid if this OutTrailer is from the server side.
203 Trailer metadata.MD
204}
205
206// IsClient indicates if this stats information is from client side.
207func (s *OutTrailer) IsClient() bool { return s.Client }
208
209func (s *OutTrailer) isRPCStats() {}
210
211// End contains stats when an RPC ends.
212type End struct {
213 // Client is true if this End is from client side.
214 Client bool
215 // BeginTime is the time when the RPC began.
216 BeginTime time.Time
217 // EndTime is the time when the RPC ends.
218 EndTime time.Time
219 // Trailer contains the trailer metadata received from the server. This
220 // field is only valid if this End is from the client side.
221 // Deprecated: use Trailer in InTrailer instead.
222 Trailer metadata.MD
223 // Error is the error the RPC ended with. It is an error generated from
224 // status.Status and can be converted back to status.Status using
225 // status.FromError if non-nil.
226 Error error
227}
228
229// IsClient indicates if this is from client side.
230func (s *End) IsClient() bool { return s.Client }
231
232func (s *End) isRPCStats() {}
233
234// ConnStats contains stats information about connections.
235type ConnStats interface {
236 isConnStats()
237 // IsClient returns true if this ConnStats is from client side.
238 IsClient() bool
239}
240
241// ConnBegin contains the stats of a connection when it is established.
242type ConnBegin struct {
243 // Client is true if this ConnBegin is from client side.
244 Client bool
245}
246
247// IsClient indicates if this is from client side.
248func (s *ConnBegin) IsClient() bool { return s.Client }
249
250func (s *ConnBegin) isConnStats() {}
251
252// ConnEnd contains the stats of a connection when it ends.
253type ConnEnd struct {
254 // Client is true if this ConnEnd is from client side.
255 Client bool
256}
257
258// IsClient indicates if this is from client side.
259func (s *ConnEnd) IsClient() bool { return s.Client }
260
261func (s *ConnEnd) isConnStats() {}
262
263// SetTags attaches stats tagging data to the context, which will be sent in
264// the outgoing RPC with the header grpc-tags-bin. Subsequent calls to
265// SetTags will overwrite the values from earlier calls.
266//
267// Deprecated: set the `grpc-tags-bin` header in the metadata instead.
268func SetTags(ctx context.Context, b []byte) context.Context {
269 return metadata.AppendToOutgoingContext(ctx, "grpc-tags-bin", string(b))
270}
271
272// Tags returns the tags from the context for the inbound RPC.
273//
274// Deprecated: obtain the `grpc-tags-bin` header from metadata instead.
275func Tags(ctx context.Context) []byte {
276 traceValues := metadata.ValueFromIncomingContext(ctx, "grpc-tags-bin")
277 if len(traceValues) == 0 {
278 return nil
279 }
280 return []byte(traceValues[len(traceValues)-1])
281}
282
283// SetTrace attaches stats tagging data to the context, which will be sent in
284// the outgoing RPC with the header grpc-trace-bin. Subsequent calls to
285// SetTrace will overwrite the values from earlier calls.
286//
287// Deprecated: set the `grpc-trace-bin` header in the metadata instead.
288func SetTrace(ctx context.Context, b []byte) context.Context {
289 return metadata.AppendToOutgoingContext(ctx, "grpc-trace-bin", string(b))
290}
291
292// Trace returns the trace from the context for the inbound RPC.
293//
294// Deprecated: obtain the `grpc-trace-bin` header from metadata instead.
295func Trace(ctx context.Context) []byte {
296 traceValues := metadata.ValueFromIncomingContext(ctx, "grpc-trace-bin")
297 if len(traceValues) == 0 {
298 return nil
299 }
300 return []byte(traceValues[len(traceValues)-1])
301}