Stats (proto)

config.metrics.v3.StatsSink

Configuration for pluggable stats sinks.

{
  "name": ...,
  "typed_config": {...}
}

name: (string) The name of the stats sink to instantiate. The name must match a supported stats sink. See the extensions listed in typed_config below for the default list of available stats sink. Sinks optionally support tagged/multiple dimensional metrics.

typed_config

(Any) Stats sink specific configuration which depends on the sink being instantiated. See StatsdSink for an example.

Tip

This extension category has the following known extensions:

config.metrics.v3.StatsConfig

[config.metrics.v3.StatsConfig proto]

Statistics configuration such as tagging.

{
  "stats_tags": [],
  "use_all_default_tags": {...},
  "stats_matcher": {...},
  "histogram_bucket_settings": []
}

stats_tags: (repeated config.metrics.v3.TagSpecifier) Each stat name is independently processed through these tag specifiers. When a tag is matched, the first capture group is not immediately removed from the name, so later TagSpecifiers can also match that same portion of the match. After all tag matching is complete, a tag-extracted version of the name is produced and is used in stats sinks that represent tags, such as Prometheus.

use_all_default_tags

(BoolValue) Use all default tag regexes specified in Envoy. These can be combined with custom tags specified in stats_tags. They will be processed before the custom tags.

Note

If any default tags are specified twice, the config will be considered invalid.

See well_known_names.h for a list of the default tags in Envoy.

If not provided, the value is assumed to be true.

stats_matcher: (config.metrics.v3.StatsMatcher) Inclusion/exclusion matcher for stat name creation. If not provided, all stats are instantiated as normal. Preventing the instantiation of certain families of stats can improve memory performance for Envoys running especially large configs.

Warning

Excluding stats may affect Envoy’s behavior in undocumented ways. See issue #8771 for more information. If any unexpected behavior changes are observed, please open a new issue immediately.

histogram_bucket_settings

(repeated config.metrics.v3.HistogramBucketSettings) Defines rules for setting the histogram buckets. Rules are evaluated in order, and the first match is applied. If no match is found (or if no rules are set), the following default buckets are used:

config.metrics.v3.StatsMatcher

[config.metrics.v3.StatsMatcher proto]

Configuration for disabling stat instantiation.

{
  "reject_all": ...,
  "exclusion_list": {...},
  "inclusion_list": {...}
}

reject_all

(bool) If reject_all is true, then all stats are disabled. If reject_all is false, then all stats are enabled.

Precisely one of reject_all, exclusion_list, inclusion_list must be set.

exclusion_list

(type.matcher.v3.ListStringMatcher) Exclusive match. All stats are enabled except for those matching one of the supplied StringMatcher protos.

Precisely one of reject_all, exclusion_list, inclusion_list must be set.

inclusion_list

(type.matcher.v3.ListStringMatcher) Inclusive match. No stats are enabled except for those matching one of the supplied StringMatcher protos.

Precisely one of reject_all, exclusion_list, inclusion_list must be set.

config.metrics.v3.TagSpecifier

[config.metrics.v3.TagSpecifier proto]

Designates a tag name and value pair. The value may be either a fixed value or a regex providing the value via capture groups. The specified tag will be unconditionally set if a fixed value, otherwise it will only be set if one or more capture groups in the regex match.

{
  "tag_name": ...,
  "regex": ...,
  "fixed_value": ...
}

tag_name: (string) Attaches an identifier to the tag values to identify the tag being in the sink. Envoy has a set of default names and regexes to extract dynamic portions of existing stats, which can be found in well_known_names.h in the Envoy repository. If a tag_name is provided in the config and neither regex or fixed_value were specified, Envoy will attempt to find that name in its set of defaults and use the accompanying regex.

Note

A stat name may be spelled in such a way that it matches two different tag extractors for the same tag name. In that case, all but one of the tag values will be dropped. It is not specified which tag value will be retained. The extraction will only occur for one of the extractors, and only the matched extraction will be removed from the tag name.

regex

(string) Designates a tag to strip from the tag extracted name and provide as a named tag value for all statistics. This will only occur if any part of the name matches the regex provided with one or more capture groups.

The first capture group identifies the portion of the name to remove. The second capture group (which will normally be nested inside the first) will designate the value of the tag for the statistic. If no second capture group is provided, the first will also be used to set the value of the tag. All other capture groups will be ignored.

Example 1. a stat name cluster.foo_cluster.upstream_rq_timeout and one tag specifier:

{
  "tag_name": "envoy.cluster_name",
  "regex": "^cluster\\.((.+?)\\.)"
}

Note that the regex will remove foo_cluster. making the tag extracted name cluster.upstream_rq_timeout and the tag value for envoy.cluster_name will be foo_cluster (note: there will be no . character because of the second capture group).

Example 2. a stat name http.connection_manager_1.user_agent.ios.downstream_cx_total and two tag specifiers:

[
  {
    "tag_name": "envoy.http_user_agent",
    "regex": "^http(?=\\.).*?\\.user_agent\\.((.+?)\\.)\\w+?$"
  },
  {
    "tag_name": "envoy.http_conn_manager_prefix",
    "regex": "^http\\.((.*?)\\.)"
  }
]

The two regexes of the specifiers will be processed from the elaborated stat name.

The first regex will save ios. as the tag value for envoy.http_user_agent. It will leave it in the name for potential matching with additional tag specifiers. After all tag specifiers are processed the tags will be removed from the name.

The second regex will populate tag envoy.http_conn_manager_prefix with value connection_manager_1., based on the original stat name.

As a final step, the matched tags are removed, leaving http.user_agent.downstream_cx_total as the tag extracted name.

Only one of regex, fixed_value may be set.

fixed_value

(string) Specifies a fixed tag value for the tag_name.

Only one of regex, fixed_value may be set.

config.metrics.v3.HistogramBucketSettings

[config.metrics.v3.HistogramBucketSettings proto]

Specifies a matcher for stats and the buckets that matching stats should use.

{
  "match": {...},
  "buckets": []
}

match: (type.matcher.v3.StringMatcher, REQUIRED) The stats that this rule applies to. The match is applied to the original stat name before tag-extraction, for example cluster.exampleclustername.upstream_cx_length_ms.

buckets: (repeated double, REQUIRED) Each value is the upper bound of a bucket. Each bucket must be greater than 0 and unique. The order of the buckets does not matter.

config.metrics.v3.StatsdSink

[config.metrics.v3.StatsdSink proto]

Stats configuration proto schema for built-in envoy.stat_sinks.statsd sink. This sink does not support tagged metrics.

This extension has the qualified name envoy.stat_sinks.statsd

Note

This extension does not operate on the data plane and hence is intended to be robust against untrusted traffic.

Tip

This extension extends and can be used with the following extension category:

envoy.stats_sinks

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.config.metrics.v3.StatsdSink

{
  "address": {...},
  "tcp_cluster_name": ...,
  "prefix": ...
}

address

(config.core.v3.Address) The UDP address of a running statsd compliant listener. If specified, statistics will be flushed to this address.

Precisely one of address, tcp_cluster_name must be set.

tcp_cluster_name

(string) The name of a cluster that is running a TCP statsd compliant listener. If specified, Envoy will connect to this cluster to flush statistics.

Precisely one of address, tcp_cluster_name must be set.

prefix

(string) Optional custom prefix for StatsdSink. If specified, this will override the default prefix. For example:

{
  "prefix" : "envoy-prod"
}

will change emitted stats to

envoy-prod.test_counter:1|c
envoy-prod.test_timer:5|ms

Note that the default prefix, “envoy”, will be used if a prefix is not specified.

Stats with default prefix:

envoy.test_counter:1|c
envoy.test_timer:5|ms

config.metrics.v3.DogStatsdSink

[config.metrics.v3.DogStatsdSink proto]

Stats configuration proto schema for built-in envoy.stat_sinks.dog_statsd sink. The sink emits stats with DogStatsD compatible tags. Tags are configurable via StatsConfig.

This extension has the qualified name envoy.stat_sinks.dog_statsd

Note

This extension does not operate on the data plane and hence is intended to be robust against untrusted traffic.

Tip

This extension extends and can be used with the following extension category:

envoy.stats_sinks

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.config.metrics.v3.DogStatsdSink

{
  "address": {...},
  "prefix": ...,
  "max_bytes_per_datagram": {...}
}

address: (config.core.v3.Address, REQUIRED) The UDP address of a running DogStatsD compliant listener. If specified, statistics will be flushed to this address.

prefix: (string) Optional custom metric name prefix. See StatsdSink’s prefix field for more details.

max_bytes_per_datagram

(UInt64Value) Optional max datagram size to use when sending UDP messages. By default Envoy will emit one metric per datagram. By specifying a max-size larger than a single metric, Envoy will emit multiple, new-line separated metrics. The max datagram size should not exceed your network’s MTU.

Note that this value may not be respected if smaller than a single metric.

config.metrics.v3.HystrixSink

[config.metrics.v3.HystrixSink proto]

Stats configuration proto schema for built-in envoy.stat_sinks.hystrix sink. The sink emits stats in text/event-stream formatted stream for use by Hystrix dashboard.

Note that only a single HystrixSink should be configured.

Streaming is started through an admin endpoint GET /hystrix_event_stream.

This extension has the qualified name envoy.stat_sinks.hystrix

Note

This extension does not operate on the data plane and hence is intended to be robust against untrusted traffic.

Tip

This extension extends and can be used with the following extension category:

envoy.stats_sinks

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.config.metrics.v3.HystrixSink

{
  "num_buckets": ...
}

num_buckets

(int64) The number of buckets the rolling statistical window is divided into.

Each time the sink is flushed, all relevant Envoy statistics are sampled and added to the rolling window (removing the oldest samples in the window in the process). The sink then outputs the aggregate statistics across the current rolling window to the event stream(s).

rolling_window(ms) = stats_flush_interval(ms) * num_of_buckets

More detailed explanation can be found in Hystrix wiki.