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