1syntax = "proto3";
2
3package envoy.config.metrics.v3;
4
5import "envoy/config/core/v3/address.proto";
6import "envoy/type/matcher/v3/string.proto";
7
8import "google/protobuf/any.proto";
9import "google/protobuf/struct.proto";
10import "google/protobuf/wrappers.proto";
11
12import "udpa/annotations/status.proto";
13import "udpa/annotations/versioning.proto";
14import "validate/validate.proto";
15
16option java_package = "io.envoyproxy.envoy.config.metrics.v3";
17option java_outer_classname = "StatsProto";
18option java_multiple_files = true;
19option (udpa.annotations.file_status).package_version_status = ACTIVE;
20
21// [#protodoc-title: Stats]
22// Statistics :ref:`architecture overview <arch_overview_statistics>`.
23
24// Configuration for pluggable stats sinks.
25message StatsSink {
26 option (udpa.annotations.versioning).previous_message_type = "envoy.config.metrics.v2.StatsSink";
27
28 reserved 2;
29
30 reserved "config";
31
32 // The name of the stats sink to instantiate. The name must match a supported
33 // stats sink. The built-in stats sinks are:
34 //
35 // * :ref:`envoy.stat_sinks.statsd <envoy_api_msg_config.metrics.v3.StatsdSink>`
36 // * :ref:`envoy.stat_sinks.dog_statsd <envoy_api_msg_config.metrics.v3.DogStatsdSink>`
37 // * :ref:`envoy.stat_sinks.metrics_service <envoy_api_msg_config.metrics.v3.MetricsServiceConfig>`
38 // * :ref:`envoy.stat_sinks.hystrix <envoy_api_msg_config.metrics.v3.HystrixSink>`
39 //
40 // Sinks optionally support tagged/multiple dimensional metrics.
41 string name = 1;
42
43 // Stats sink specific configuration which depends on the sink being instantiated. See
44 // :ref:`StatsdSink <envoy_api_msg_config.metrics.v3.StatsdSink>` for an example.
45 oneof config_type {
46 google.protobuf.Any typed_config = 3;
47 }
48}
49
50// Statistics configuration such as tagging.
51message StatsConfig {
52 option (udpa.annotations.versioning).previous_message_type =
53 "envoy.config.metrics.v2.StatsConfig";
54
55 // Each stat name is iteratively processed through these tag specifiers.
56 // When a tag is matched, the first capture group is removed from the name so
57 // later :ref:`TagSpecifiers <envoy_api_msg_config.metrics.v3.TagSpecifier>` cannot match that
58 // same portion of the match.
59 repeated TagSpecifier stats_tags = 1;
60
61 // Use all default tag regexes specified in Envoy. These can be combined with
62 // custom tags specified in :ref:`stats_tags
63 // <envoy_api_field_config.metrics.v3.StatsConfig.stats_tags>`. They will be processed before
64 // the custom tags.
65 //
66 // .. note::
67 //
68 // If any default tags are specified twice, the config will be considered
69 // invalid.
70 //
71 // See :repo:`well_known_names.h <source/common/config/well_known_names.h>` for a list of the
72 // default tags in Envoy.
73 //
74 // If not provided, the value is assumed to be true.
75 google.protobuf.BoolValue use_all_default_tags = 2;
76
77 // Inclusion/exclusion matcher for stat name creation. If not provided, all stats are instantiated
78 // as normal. Preventing the instantiation of certain families of stats can improve memory
79 // performance for Envoys running especially large configs.
80 //
81 // .. warning::
82 // Excluding stats may affect Envoy's behavior in undocumented ways. See
83 // `issue #8771 <https://github.com/envoyproxy/envoy/issues/8771>`_ for more information.
84 // If any unexpected behavior changes are observed, please open a new issue immediately.
85 StatsMatcher stats_matcher = 3;
86
87 // Defines rules for setting the histogram buckets. Rules are evaluated in order, and the first
88 // match is applied. If no match is found (or if no rules are set), the following default buckets
89 // are used:
90 //
91 // .. code-block:: json
92 //
93 // [
94 // 0.5,
95 // 1,
96 // 5,
97 // 10,
98 // 25,
99 // 50,
100 // 100,
101 // 250,
102 // 500,
103 // 1000,
104 // 2500,
105 // 5000,
106 // 10000,
107 // 30000,
108 // 60000,
109 // 300000,
110 // 600000,
111 // 1800000,
112 // 3600000
113 // ]
114 repeated HistogramBucketSettings histogram_bucket_settings = 4;
115}
116
117// Configuration for disabling stat instantiation.
118message StatsMatcher {
119 // The instantiation of stats is unrestricted by default. If the goal is to configure Envoy to
120 // instantiate all stats, there is no need to construct a StatsMatcher.
121 //
122 // However, StatsMatcher can be used to limit the creation of families of stats in order to
123 // conserve memory. Stats can either be disabled entirely, or they can be
124 // limited by either an exclusion or an inclusion list of :ref:`StringMatcher
125 // <envoy_api_msg_type.matcher.v3.StringMatcher>` protos:
126 //
127 // * If `reject_all` is set to `true`, no stats will be instantiated. If `reject_all` is set to
128 // `false`, all stats will be instantiated.
129 //
130 // * If an exclusion list is supplied, any stat name matching *any* of the StringMatchers in the
131 // list will not instantiate.
132 //
133 // * If an inclusion list is supplied, no stats will instantiate, except those matching *any* of
134 // the StringMatchers in the list.
135 //
136 //
137 // A StringMatcher can be used to match against an exact string, a suffix / prefix, or a regex.
138 // **NB:** For performance reasons, it is highly recommended to use a prefix- or suffix-based
139 // matcher rather than a regex-based matcher.
140 //
141 // Example 1. Excluding all stats.
142 //
143 // .. code-block:: json
144 //
145 // {
146 // "statsMatcher": {
147 // "rejectAll": "true"
148 // }
149 // }
150 //
151 // Example 2. Excluding all cluster-specific stats, but not cluster-manager stats:
152 //
153 // .. code-block:: json
154 //
155 // {
156 // "statsMatcher": {
157 // "exclusionList": {
158 // "patterns": [
159 // {
160 // "prefix": "cluster."
161 // }
162 // ]
163 // }
164 // }
165 // }
166 //
167 // Example 3. Including only manager-related stats:
168 //
169 // .. code-block:: json
170 //
171 // {
172 // "statsMatcher": {
173 // "inclusionList": {
174 // "patterns": [
175 // {
176 // "prefix": "cluster_manager."
177 // },
178 // {
179 // "prefix": "listener_manager."
180 // }
181 // ]
182 // }
183 // }
184 // }
185 //
186
187 option (udpa.annotations.versioning).previous_message_type =
188 "envoy.config.metrics.v2.StatsMatcher";
189
190 oneof stats_matcher {
191 option (validate.required) = true;
192
193 // If `reject_all` is true, then all stats are disabled. If `reject_all` is false, then all
194 // stats are enabled.
195 bool reject_all = 1;
196
197 // Exclusive match. All stats are enabled except for those matching one of the supplied
198 // StringMatcher protos.
199 type.matcher.v3.ListStringMatcher exclusion_list = 2;
200
201 // Inclusive match. No stats are enabled except for those matching one of the supplied
202 // StringMatcher protos.
203 type.matcher.v3.ListStringMatcher inclusion_list = 3;
204 }
205}
206
207// Designates a tag name and value pair. The value may be either a fixed value
208// or a regex providing the value via capture groups. The specified tag will be
209// unconditionally set if a fixed value, otherwise it will only be set if one
210// or more capture groups in the regex match.
211message TagSpecifier {
212 option (udpa.annotations.versioning).previous_message_type =
213 "envoy.config.metrics.v2.TagSpecifier";
214
215 // Attaches an identifier to the tag values to identify the tag being in the
216 // sink. Envoy has a set of default names and regexes to extract dynamic
217 // portions of existing stats, which can be found in :repo:`well_known_names.h
218 // <source/common/config/well_known_names.h>` in the Envoy repository. If a :ref:`tag_name
219 // <envoy_api_field_config.metrics.v3.TagSpecifier.tag_name>` is provided in the config and
220 // neither :ref:`regex <envoy_api_field_config.metrics.v3.TagSpecifier.regex>` or
221 // :ref:`fixed_value <envoy_api_field_config.metrics.v3.TagSpecifier.fixed_value>` were specified,
222 // Envoy will attempt to find that name in its set of defaults and use the accompanying regex.
223 //
224 // .. note::
225 //
226 // It is invalid to specify the same tag name twice in a config.
227 string tag_name = 1;
228
229 oneof tag_value {
230 // Designates a tag to strip from the tag extracted name and provide as a named
231 // tag value for all statistics. This will only occur if any part of the name
232 // matches the regex provided with one or more capture groups.
233 //
234 // The first capture group identifies the portion of the name to remove. The
235 // second capture group (which will normally be nested inside the first) will
236 // designate the value of the tag for the statistic. If no second capture
237 // group is provided, the first will also be used to set the value of the tag.
238 // All other capture groups will be ignored.
239 //
240 // Example 1. a stat name ``cluster.foo_cluster.upstream_rq_timeout`` and
241 // one tag specifier:
242 //
243 // .. code-block:: json
244 //
245 // {
246 // "tag_name": "envoy.cluster_name",
247 // "regex": "^cluster\\.((.+?)\\.)"
248 // }
249 //
250 // Note that the regex will remove ``foo_cluster.`` making the tag extracted
251 // name ``cluster.upstream_rq_timeout`` and the tag value for
252 // ``envoy.cluster_name`` will be ``foo_cluster`` (note: there will be no
253 // ``.`` character because of the second capture group).
254 //
255 // Example 2. a stat name
256 // ``http.connection_manager_1.user_agent.ios.downstream_cx_total`` and two
257 // tag specifiers:
258 //
259 // .. code-block:: json
260 //
261 // [
262 // {
263 // "tag_name": "envoy.http_user_agent",
264 // "regex": "^http(?=\\.).*?\\.user_agent\\.((.+?)\\.)\\w+?$"
265 // },
266 // {
267 // "tag_name": "envoy.http_conn_manager_prefix",
268 // "regex": "^http\\.((.*?)\\.)"
269 // }
270 // ]
271 //
272 // The two regexes of the specifiers will be processed in the definition order.
273 //
274 // The first regex will remove ``ios.``, leaving the tag extracted name
275 // ``http.connection_manager_1.user_agent.downstream_cx_total``. The tag
276 // ``envoy.http_user_agent`` will be added with tag value ``ios``.
277 //
278 // The second regex will remove ``connection_manager_1.`` from the tag
279 // extracted name produced by the first regex
280 // ``http.connection_manager_1.user_agent.downstream_cx_total``, leaving
281 // ``http.user_agent.downstream_cx_total`` as the tag extracted name. The tag
282 // ``envoy.http_conn_manager_prefix`` will be added with the tag value
283 // ``connection_manager_1``.
284 string regex = 2 [(validate.rules).string = {max_bytes: 1024}];
285
286 // Specifies a fixed tag value for the ``tag_name``.
287 string fixed_value = 3;
288 }
289}
290
291// Specifies a matcher for stats and the buckets that matching stats should use.
292message HistogramBucketSettings {
293 // The stats that this rule applies to. The match is applied to the original stat name
294 // before tag-extraction, for example `cluster.exampleclustername.upstream_cx_length_ms`.
295 type.matcher.v3.StringMatcher match = 1 [(validate.rules).message = {required: true}];
296
297 // Each value is the upper bound of a bucket. Each bucket must be greater than 0 and unique.
298 // The order of the buckets does not matter.
299 repeated double buckets = 2 [(validate.rules).repeated = {
300 min_items: 1
301 unique: true
302 items {double {gt: 0.0}}
303 }];
304}
305
306// Stats configuration proto schema for built-in *envoy.stat_sinks.statsd* sink. This sink does not support
307// tagged metrics.
308// [#extension: envoy.stat_sinks.statsd]
309message StatsdSink {
310 option (udpa.annotations.versioning).previous_message_type = "envoy.config.metrics.v2.StatsdSink";
311
312 oneof statsd_specifier {
313 option (validate.required) = true;
314
315 // The UDP address of a running `statsd <https://github.com/etsy/statsd>`_
316 // compliant listener. If specified, statistics will be flushed to this
317 // address.
318 core.v3.Address address = 1;
319
320 // The name of a cluster that is running a TCP `statsd
321 // <https://github.com/etsy/statsd>`_ compliant listener. If specified,
322 // Envoy will connect to this cluster to flush statistics.
323 string tcp_cluster_name = 2;
324 }
325
326 // Optional custom prefix for StatsdSink. If
327 // specified, this will override the default prefix.
328 // For example:
329 //
330 // .. code-block:: json
331 //
332 // {
333 // "prefix" : "envoy-prod"
334 // }
335 //
336 // will change emitted stats to
337 //
338 // .. code-block:: cpp
339 //
340 // envoy-prod.test_counter:1|c
341 // envoy-prod.test_timer:5|ms
342 //
343 // Note that the default prefix, "envoy", will be used if a prefix is not
344 // specified.
345 //
346 // Stats with default prefix:
347 //
348 // .. code-block:: cpp
349 //
350 // envoy.test_counter:1|c
351 // envoy.test_timer:5|ms
352 string prefix = 3;
353}
354
355// Stats configuration proto schema for built-in *envoy.stat_sinks.dog_statsd* sink.
356// The sink emits stats with `DogStatsD <https://docs.datadoghq.com/guides/dogstatsd/>`_
357// compatible tags. Tags are configurable via :ref:`StatsConfig
358// <envoy_api_msg_config.metrics.v3.StatsConfig>`.
359// [#extension: envoy.stat_sinks.dog_statsd]
360message DogStatsdSink {
361 option (udpa.annotations.versioning).previous_message_type =
362 "envoy.config.metrics.v2.DogStatsdSink";
363
364 reserved 2;
365
366 oneof dog_statsd_specifier {
367 option (validate.required) = true;
368
369 // The UDP address of a running DogStatsD compliant listener. If specified,
370 // statistics will be flushed to this address.
371 core.v3.Address address = 1;
372 }
373
374 // Optional custom metric name prefix. See :ref:`StatsdSink's prefix field
375 // <envoy_api_field_config.metrics.v3.StatsdSink.prefix>` for more details.
376 string prefix = 3;
377
378 // Optional max datagram size to use when sending UDP messages. By default Envoy
379 // will emit one metric per datagram. By specifying a max-size larger than a single
380 // metric, Envoy will emit multiple, new-line separated metrics. The max datagram
381 // size should not exceed your network's MTU.
382 //
383 // Note that this value may not be respected if smaller than a single metric.
384 google.protobuf.UInt64Value max_bytes_per_datagram = 4 [(validate.rules).uint64 = {gt: 0}];
385}
386
387// Stats configuration proto schema for built-in *envoy.stat_sinks.hystrix* sink.
388// The sink emits stats in `text/event-stream
389// <https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events>`_
390// formatted stream for use by `Hystrix dashboard
391// <https://github.com/Netflix-Skunkworks/hystrix-dashboard/wiki>`_.
392//
393// Note that only a single HystrixSink should be configured.
394//
395// Streaming is started through an admin endpoint :http:get:`/hystrix_event_stream`.
396// [#extension: envoy.stat_sinks.hystrix]
397message HystrixSink {
398 option (udpa.annotations.versioning).previous_message_type =
399 "envoy.config.metrics.v2.HystrixSink";
400
401 // The number of buckets the rolling statistical window is divided into.
402 //
403 // Each time the sink is flushed, all relevant Envoy statistics are sampled and
404 // added to the rolling window (removing the oldest samples in the window
405 // in the process). The sink then outputs the aggregate statistics across the
406 // current rolling window to the event stream(s).
407 //
408 // rolling_window(ms) = stats_flush_interval(ms) * num_of_buckets
409 //
410 // More detailed explanation can be found in `Hystrix wiki
411 // <https://github.com/Netflix/Hystrix/wiki/Metrics-and-Monitoring#hystrixrollingnumber>`_.
412 int64 num_buckets = 1;
413}
View as plain text