docs: add documents about tagged metrics (#544)

Signed-off-by: Taiki Ono <taiki-ono@cookpad.com>

docs/root/intro/arch_overview/statistics.rst

@@ -4,23 +4,39 @@ Statistics
 ==========
 
 One of the primary goals of Envoy is to make the network understandable. Envoy emits a large number
-of statistics depending on how it is configured. Generally the statistics fall into two categories:
+of statistics depending on how it is configured. Generally the statistics fall into three categories:
 
 * **Downstream**: Downstream statistics relate to incoming connections/requests. They are emitted by
   listeners, the HTTP connection manager, the TCP proxy filter, etc.
 * **Upstream**: Upstream statistics relate to outgoing connections/requests. They are emitted by
   connection pools, the router filter, the TCP proxy filter, etc.
+* **Server**: Server statistics describe how the Envoy server instance is working. Statistics like
+  server uptime or amount of allocated memory are categorized here.
 
 A single proxy scenario typically involves both downstream and upstream statistics. The two types
 can be used to get a detailed picture of that particular network hop. Statistics from the entire
 mesh give a very detailed picture of each hop and overall network health. The statistics emitted are
 documented in detail in the operations guide.
 
-Envoy uses statsd as the statistics output format, though plugging in a different statistics sink
-would not be difficult. Both TCP and UDP statsd is supported. Internally, counters and gauges are
-batched and periodically flushed to improve performance. Histograms are written as they are
-received. Note: what were previously referred to as timers have become histograms as the only
-difference between the two representations was the units.
+In the v1 API, Envoy only supports statsd as the statistics output format. Both TCP and UDP statsd
+are supported. As of the v2 API, Envoy has the ability to support custom, pluggable sinks. :ref:`A
+few standard sink implementations<envoy_api_msg_config.metrics.v2.StatsSink>` are included in Envoy.
+Some sinks also support emitting statistics with tags/dimensions.
+
+Within Envoy and throughout the documentation, statistics are identified by a canonical string
+representation. The dynamic portions of these strings are stripped to become tags. Users can
+configure this behavior via :ref:`the Tag Specifier configuration <envoy_api_msg_config.metrics.v2.TagSpecifier>`.
+
+Envoy emits three types of values as statistics:
+
+* **Counters**: Unsigned integers that only increase and never decrease. E.g., total requests.
+* **Gauges**: Unsigned integers that both increase and decrease. E.g., currently active requests.
+* **Histograms**: Unsigned integers that are part of a stream of values that are then aggregated by
+  the collector to ultimately yield summarized percentile values. E.g., upstream request time.
+
+Internally, counters and gauges are batched and periodically flushed to improve performance.
+Histograms are written as they are received. Note: what were previously referred to as timers have
+become histograms as the only difference between the two representations was the units.
 
 * :ref:`v1 API reference <config_overview_v1>`.
 * :ref:`v2 API reference <envoy_api_field_config.bootstrap.v2.Bootstrap.stats_sinks>`.

envoy/config/metrics/v2/stats.proto

@@ -21,6 +21,8 @@ message StatsSink {
   // * :ref:`envoy.statsd <envoy_api_msg_config.metrics.v2.StatsdSink>`
   // * :ref:`envoy.dog_statsd <envoy_api_msg_config.metrics.v2.DogStatsdSink>`
   // * :ref:`envoy.metrics_service <envoy_api_msg_config.metrics.v2.MetricsServiceConfig>`
+  //
+  // Sinks optionally support tagged/multiple dimensional metrics.
   string name = 1;
 
   // Stats sink specific configuration which depends on the sink being
@@ -137,7 +139,8 @@ message TagSpecifier {
   }
 }
 
-// Stats configuration proto schema for built-in *envoy.statsd* sink.
+// Stats configuration proto schema for built-in *envoy.statsd* sink. This sink does not support
+// tagged metrics.
 message StatsdSink {
   oneof statsd_specifier {
     option (validate.required) = true;