.. _envoy_api_file_envoy/config/metrics/v2/stats.proto: Stats ===== Statistics :ref:`architecture overview `. .. _envoy_api_msg_config.metrics.v2.StatsSink: config.metrics.v2.StatsSink --------------------------- `[config.metrics.v2.StatsSink proto] `_ Configuration for pluggable stats sinks. .. code-block:: json { "name": "...", "config": "{...}" } .. _envoy_api_field_config.metrics.v2.StatsSink.name: name (`string `_) The name of the stats sink to instantiate. The name must match a supported stats sink. The built-in stats sinks are: * :ref:`envoy.statsd ` * :ref:`envoy.dog_statsd ` * :ref:`envoy.metrics_service ` * :ref:`envoy.stat_sinks.hystrix ` Sinks optionally support tagged/multiple dimensional metrics. .. _envoy_api_field_config.metrics.v2.StatsSink.config: config (`Struct `_) Stats sink specific configuration which depends on the sink being instantiated. See :ref:`StatsdSink ` for an example. .. _envoy_api_msg_config.metrics.v2.StatsConfig: config.metrics.v2.StatsConfig ----------------------------- `[config.metrics.v2.StatsConfig proto] `_ Statistics configuration such as tagging. .. code-block:: json { "stats_tags": [], "use_all_default_tags": "{...}", "stats_matcher": "{...}" } .. _envoy_api_field_config.metrics.v2.StatsConfig.stats_tags: stats_tags (:ref:`config.metrics.v2.TagSpecifier `) Each stat name is iteratively processed through these tag specifiers. When a tag is matched, the first capture group is removed from the name so later :ref:`TagSpecifiers ` cannot match that same portion of the match. .. _envoy_api_field_config.metrics.v2.StatsConfig.use_all_default_tags: use_all_default_tags (`BoolValue `_) Use all default tag regexes specified in Envoy. These can be combined with custom tags specified in :ref:`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. .. _envoy_api_field_config.metrics.v2.StatsConfig.stats_matcher: stats_matcher (:ref:`config.metrics.v2.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. .. _envoy_api_msg_config.metrics.v2.StatsMatcher: config.metrics.v2.StatsMatcher ------------------------------ `[config.metrics.v2.StatsMatcher proto] `_ Configuration for disabling stat instantiation. .. code-block:: json { "reject_all": "...", "exclusion_list": "{...}", "inclusion_list": "{...}" } .. _envoy_api_field_config.metrics.v2.StatsMatcher.reject_all: 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 :ref:`reject_all `, :ref:`exclusion_list `, :ref:`inclusion_list ` must be set. .. _envoy_api_field_config.metrics.v2.StatsMatcher.exclusion_list: exclusion_list (:ref:`type.matcher.ListStringMatcher `) Exclusive match. All stats are enabled except for those matching one of the supplied StringMatcher protos. Precisely one of :ref:`reject_all `, :ref:`exclusion_list `, :ref:`inclusion_list ` must be set. .. _envoy_api_field_config.metrics.v2.StatsMatcher.inclusion_list: inclusion_list (:ref:`type.matcher.ListStringMatcher `) Inclusive match. No stats are enabled except for those matching one of the supplied StringMatcher protos. Precisely one of :ref:`reject_all `, :ref:`exclusion_list `, :ref:`inclusion_list ` must be set. .. _envoy_api_msg_config.metrics.v2.TagSpecifier: config.metrics.v2.TagSpecifier ------------------------------ `[config.metrics.v2.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. .. code-block:: json { "tag_name": "...", "regex": "...", "fixed_value": "..." } .. _envoy_api_field_config.metrics.v2.TagSpecifier.tag_name: 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 :ref:`tag_name ` is provided in the config and neither :ref:`regex ` or :ref:`fixed_value ` were specified, Envoy will attempt to find that name in its set of defaults and use the accompanying regex. .. note:: It is invalid to specify the same tag name twice in a config. .. _envoy_api_field_config.metrics.v2.TagSpecifier.regex: 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: .. code-block:: json { "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: .. code-block:: json [ { "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 in the definition order. The first regex will remove ``ios.``, leaving the tag extracted name ``http.connection_manager_1.user_agent.downstream_cx_total``. The tag ``envoy.http_user_agent`` will be added with tag value ``ios``. The second regex will remove ``connection_manager_1.`` from the tag extracted name produced by the first regex ``http.connection_manager_1.user_agent.downstream_cx_total``, leaving ``http.user_agent.downstream_cx_total`` as the tag extracted name. The tag ``envoy.http_conn_manager_prefix`` will be added with the tag value ``connection_manager_1``. Only one of :ref:`regex `, :ref:`fixed_value ` may be set. .. _envoy_api_field_config.metrics.v2.TagSpecifier.fixed_value: fixed_value (`string `_) Specifies a fixed tag value for the ``tag_name``. Only one of :ref:`regex `, :ref:`fixed_value ` may be set. .. _envoy_api_msg_config.metrics.v2.StatsdSink: config.metrics.v2.StatsdSink ---------------------------- `[config.metrics.v2.StatsdSink proto] `_ Stats configuration proto schema for built-in *envoy.statsd* sink. This sink does not support tagged metrics. .. code-block:: json { "address": "{...}", "tcp_cluster_name": "...", "prefix": "..." } .. _envoy_api_field_config.metrics.v2.StatsdSink.address: address (:ref:`core.Address `) The UDP address of a running `statsd `_ compliant listener. If specified, statistics will be flushed to this address. Precisely one of :ref:`address `, :ref:`tcp_cluster_name ` must be set. .. _envoy_api_field_config.metrics.v2.StatsdSink.tcp_cluster_name: 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 :ref:`address `, :ref:`tcp_cluster_name ` must be set. .. _envoy_api_field_config.metrics.v2.StatsdSink.prefix: prefix (`string `_) Optional custom prefix for StatsdSink. If specified, this will override the default prefix. For example: .. code-block:: json { "prefix" : "envoy-prod" } will change emitted stats to .. code-block:: cpp 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: .. code-block:: cpp envoy.test_counter:1|c envoy.test_timer:5|ms .. _envoy_api_msg_config.metrics.v2.DogStatsdSink: config.metrics.v2.DogStatsdSink ------------------------------- `[config.metrics.v2.DogStatsdSink proto] `_ Stats configuration proto schema for built-in *envoy.dog_statsd* sink. The sink emits stats with `DogStatsD `_ compatible tags. Tags are configurable via :ref:`StatsConfig `. .. code-block:: json { "address": "{...}", "prefix": "..." } .. _envoy_api_field_config.metrics.v2.DogStatsdSink.address: address (:ref:`core.Address `, *REQUIRED*) The UDP address of a running DogStatsD compliant listener. If specified, statistics will be flushed to this address. .. _envoy_api_field_config.metrics.v2.DogStatsdSink.prefix: prefix (`string `_) Optional custom metric name prefix. See :ref:`StatsdSink's prefix field ` for more details. .. _envoy_api_msg_config.metrics.v2.HystrixSink: config.metrics.v2.HystrixSink ----------------------------- `[config.metrics.v2.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 :http:get:`/hystrix_event_stream`. .. code-block:: json { "num_buckets": "..." } .. _envoy_api_field_config.metrics.v2.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 `Hystix wiki `_.