.. _arch_overview_statistics:

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 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.

As of the v2 API, Envoy has the ability to support custom, pluggable sinks. :ref:A few standard sink implementations<envoy_v3_api_msg_config.metrics.v3.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_v3_api_msg_config.metrics.v3.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:v3 API reference <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.stats_sinks>.