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