data-plane-api/api/stats.proto

// [#protodoc-title: Stats]
// Statistics :ref:`architecture overview <arch_overview_statistics>`.

syntax = "proto3";

package envoy.api.v2;

import "api/address.proto";

import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";

import "validate/validate.proto";

// Configuration for pluggable stats sinks.
message StatsSink {
  // The name of the stats sink to instantiate. The name must match a supported
  // stats sink. *envoy.statsd* is a built-in sink suitable for emitting to
  // `statsd <https://github.com/etsy/statsd>`_. Any other built-in stats sink
  // can be found in `well_known_names.h
  // <https://github.com/envoyproxy/envoy/blob/master/source/common/config/well_known_names.h>`_
  // in the Envoy repository.
  string name = 1;

  // Stats sink specific configuration which depends on the sink being
  // instantiated. See :ref:`StatsdSink <envoy_api_msg_StatsdSink>` for an
  // example.
  google.protobuf.Struct config = 2;
}

// Statistics configuration such as tagging.
message StatsConfig {
  // 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 <envoy_api_msg_TagSpecifier>` cannot match that
  // same portion of the match.
  repeated TagSpecifier stats_tags = 1;

  // Use all default tag regexes specified in Envoy. These can be combined with
  // custom tags specified in :ref:`stats_tags
  // <envoy_api_field_StatsConfig.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
  // <https://github.com/envoyproxy/envoy/blob/master/source/common/config/well_known_names.h>`_
  // for a list of the default tags in Envoy.
  //
  // If not provided, the value is assumed to be true.
  google.protobuf.BoolValue use_all_default_tags = 2;
}

// 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.
message TagSpecifier {
  // 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
  // <https://github.com/envoyproxy/envoy/blob/master/source/common/config/well_known_names.h>`_
  // in the Envoy repository. If a :ref:`tag_name
  // <envoy_api_field_TagSpecifier.tag_name>` is provided in the config with an
  // empty regex, Envoy will attempt to find that name in its set of defaults
  // and use the accompanying regex.
  //
  // .. note::
  //
  //   If any default tags are specified twice, the config will be considered
  //   invalid.
  string tag_name = 1;

  // 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.
  //
  // Take for example, with a stat name ``cluster.foo_cluster.upstream_rq_timeout``
  // and
  //
  // .. 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).
  //
  // An example with two regexes and stat name
  // ``http.connection_manager_1.user_agent.ios.downstream_cx_total``:
  //
  // .. code-block:: json
  //
  //   [
  //     {
  //       "tag_name": "envoy.http_user_agent",
  //       "regex": "^http(?=\.).*?\.user_agent\.((.+?)\.)\w+?$"
  //     },
  //     {
  //       "tag_name": "envoy.http_conn_manager_prefix",
  //       "regex": "^http\.((.*?)\.)"
  //     }
  //   ]
  //
  // 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``.
  string regex = 2;
}

// Stats configuration proto schema for built-in *envoy.statsd* sink.
message StatsdSink {
  oneof statsd_specifier {
    option (validate.required) = true;

    // The UDP address of a running `statsd <https://github.com/etsy/statsd>`_
    // compliant listener. If specified, statistics will be flushed to this
    // address.
    Address address = 1;

    // The name of a cluster that is running a TCP `statsd
    // <https://github.com/etsy/statsd>`_ compliant listener. If specified,
    // Envoy will connect to this cluster to flush statistics.
    string tcp_cluster_name = 2;
  }
}

// Stats configuration proto schema for built-in *envoy.dog_statsd* sink.
// The sink emits stats with `DogStatsD <https://docs.datadoghq.com/guides/dogstatsd/>`_
// compatible tags. Tags are configurable via :ref:`StatsConfig <envoy_api_msg_StatsConfig>`.
message DogStatsdSink {
  oneof dog_statsd_specifier {
    option (validate.required) = true;

    // The UDP address of a running DogStatsD compliant listener. If specified,
    // statistics will be flushed to this address.
    Address address = 1;

    // The name of a cluster that is DogStatsD compliant TCP listener. If specified,
    // Envoy will connect to this cluster to flush statistics.
    string tcp_cluster_name = 2;
  }
}