...

Text file src/github.com/datawire/ambassador/v2/api/envoy/config/metrics/v3/stats.proto

Documentation: github.com/datawire/ambassador/v2/api/envoy/config/metrics/v3

     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