3 * Copyright 2016 gRPC authors.
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
9 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 //go:generate protoc --go_out=plugins=grpc:. grpc_testing/test.proto
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.
24 package stats // import "google.golang.org/grpc/stats"
32 // RPCStats contains stats information about RPCs.
33 type RPCStats interface {
35 // IsClient returns true if this RPCStats is from client side.
39 // Begin contains stats when an RPC begins.
40 // FailFast is only valid if this Begin is from client side.
42 // Client is true if this Begin is from client side.
44 // BeginTime is the time when the RPC begins.
46 // FailFast indicates if this RPC is failfast.
50 // IsClient indicates if the stats information is from client side.
51 func (s *Begin) IsClient() bool { return s.Client }
53 func (s *Begin) isRPCStats() {}
55 // InPayload contains the information for an incoming payload.
56 type InPayload struct {
57 // Client is true if this InPayload is from client side.
59 // Payload is the payload with original type.
61 // Data is the serialized message payload.
63 // Length is the length of uncompressed data.
65 // WireLength is the length of data on wire (compressed, signed, encrypted).
67 // RecvTime is the time when the payload is received.
71 // IsClient indicates if the stats information is from client side.
72 func (s *InPayload) IsClient() bool { return s.Client }
74 func (s *InPayload) isRPCStats() {}
76 // InHeader contains stats when a header is received.
77 type InHeader struct {
78 // Client is true if this InHeader is from client side.
80 // WireLength is the wire length of header.
83 // The following fields are valid only if Client is false.
84 // FullMethod is the full RPC method string, i.e., /package.service/method.
86 // RemoteAddr is the remote address of the corresponding connection.
88 // LocalAddr is the local address of the corresponding connection.
90 // Compression is the compression algorithm used for the RPC.
94 // IsClient indicates if the stats information is from client side.
95 func (s *InHeader) IsClient() bool { return s.Client }
97 func (s *InHeader) isRPCStats() {}
99 // InTrailer contains stats when a trailer is received.
100 type InTrailer struct {
101 // Client is true if this InTrailer is from client side.
103 // WireLength is the wire length of trailer.
107 // IsClient indicates if the stats information is from client side.
108 func (s *InTrailer) IsClient() bool { return s.Client }
110 func (s *InTrailer) isRPCStats() {}
112 // OutPayload contains the information for an outgoing payload.
113 type OutPayload struct {
114 // Client is true if this OutPayload is from client side.
116 // Payload is the payload with original type.
118 // Data is the serialized message payload.
120 // Length is the length of uncompressed data.
122 // WireLength is the length of data on wire (compressed, signed, encrypted).
124 // SentTime is the time when the payload is sent.
128 // IsClient indicates if this stats information is from client side.
129 func (s *OutPayload) IsClient() bool { return s.Client }
131 func (s *OutPayload) isRPCStats() {}
133 // OutHeader contains stats when a header is sent.
134 type OutHeader struct {
135 // Client is true if this OutHeader is from client side.
138 // The following fields are valid only if Client is true.
139 // FullMethod is the full RPC method string, i.e., /package.service/method.
141 // RemoteAddr is the remote address of the corresponding connection.
143 // LocalAddr is the local address of the corresponding connection.
145 // Compression is the compression algorithm used for the RPC.
149 // IsClient indicates if this stats information is from client side.
150 func (s *OutHeader) IsClient() bool { return s.Client }
152 func (s *OutHeader) isRPCStats() {}
154 // OutTrailer contains stats when a trailer is sent.
155 type OutTrailer struct {
156 // Client is true if this OutTrailer is from client side.
158 // WireLength is the wire length of trailer.
162 // IsClient indicates if this stats information is from client side.
163 func (s *OutTrailer) IsClient() bool { return s.Client }
165 func (s *OutTrailer) isRPCStats() {}
167 // End contains stats when an RPC ends.
169 // Client is true if this End is from client side.
171 // BeginTime is the time when the RPC began.
173 // EndTime is the time when the RPC ends.
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.
181 // IsClient indicates if this is from client side.
182 func (s *End) IsClient() bool { return s.Client }
184 func (s *End) isRPCStats() {}
186 // ConnStats contains stats information about connections.
187 type ConnStats interface {
189 // IsClient returns true if this ConnStats is from client side.
193 // ConnBegin contains the stats of a connection when it is established.
194 type ConnBegin struct {
195 // Client is true if this ConnBegin is from client side.
199 // IsClient indicates if this is from client side.
200 func (s *ConnBegin) IsClient() bool { return s.Client }
202 func (s *ConnBegin) isConnStats() {}
204 // ConnEnd contains the stats of a connection when it ends.
205 type ConnEnd struct {
206 // Client is true if this ConnEnd is from client side.
210 // IsClient indicates if this is from client side.
211 func (s *ConnEnd) IsClient() bool { return s.Client }
213 func (s *ConnEnd) isConnStats() {}
215 type incomingTagsKey struct{}
216 type outgoingTagsKey struct{}
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.
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.
226 func SetTags(ctx context.Context, b []byte) context.Context {
227 return context.WithValue(ctx, outgoingTagsKey{}, b)
230 // Tags returns the tags from the context for the inbound RPC.
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.
236 func Tags(ctx context.Context) []byte {
237 b, _ := ctx.Value(incomingTagsKey{}).([]byte)
241 // SetIncomingTags attaches stats tagging data to the context, to be read by
242 // the application (not sent in outgoing RPCs).
244 // This is intended for gRPC-internal use ONLY.
245 func SetIncomingTags(ctx context.Context, b []byte) context.Context {
246 return context.WithValue(ctx, incomingTagsKey{}, b)
249 // OutgoingTags returns the tags from the context for the outbound RPC.
251 // This is intended for gRPC-internal use ONLY.
252 func OutgoingTags(ctx context.Context) []byte {
253 b, _ := ctx.Value(outgoingTagsKey{}).([]byte)
257 type incomingTraceKey struct{}
258 type outgoingTraceKey struct{}
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.
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.
268 func SetTrace(ctx context.Context, b []byte) context.Context {
269 return context.WithValue(ctx, outgoingTraceKey{}, b)
272 // Trace returns the trace from the context for the inbound RPC.
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.
278 func Trace(ctx context.Context) []byte {
279 b, _ := ctx.Value(incomingTraceKey{}).([]byte)
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.
286 func SetIncomingTrace(ctx context.Context, b []byte) context.Context {
287 return context.WithValue(ctx, incomingTraceKey{}, b)
290 // OutgoingTrace returns the trace from the context for the outbound RPC. It is
291 // intended for gRPC-internal use.
292 func OutgoingTrace(ctx context.Context) []byte {
293 b, _ := ctx.Value(outgoingTraceKey{}).([]byte)