docs: add missing statistics documents (#550)

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

docs/root/configuration/cluster_manager/cluster_stats.rst

@@ -67,21 +67,22 @@ Every cluster has a statistics tree rooted at *cluster.<name>.* with the followi
   upstream_rq_retry, Counter, Total request retries
   upstream_rq_retry_success, Counter, Total request retry successes
   upstream_rq_retry_overflow, Counter, Total requests not retried due to circuit breaking
-  upstream_flow_control_paused_reading_total, Counter, Total number of times flow control paused reading from upstream.
-  upstream_flow_control_resumed_reading_total, Counter, Total number of times flow control resumed reading from upstream.
-  upstream_flow_control_backed_up_total, Counter, Total number of times the upstream connection backed up and paused reads from downstream.
-  upstream_flow_control_drained_total, Counter, Total number of times the upstream connection drained and resumed reads from downstream.
+  upstream_flow_control_paused_reading_total, Counter, Total number of times flow control paused reading from upstream
+  upstream_flow_control_resumed_reading_total, Counter, Total number of times flow control resumed reading from upstream
+  upstream_flow_control_backed_up_total, Counter, Total number of times the upstream connection backed up and paused reads from downstream
+  upstream_flow_control_drained_total, Counter, Total number of times the upstream connection drained and resumed reads from downstream
   membership_change, Counter, Total cluster membership changes
   membership_healthy, Gauge, Current cluster healthy total (inclusive of both health checking and outlier detection)
   membership_total, Gauge, Current cluster membership total
-  retry_or_shadow_abandoned, Counter, Total number of times shadowing or retry buffering was canceled due to buffer limits.
+  retry_or_shadow_abandoned, Counter, Total number of times shadowing or retry buffering was canceled due to buffer limits
   config_reload, Counter, Total API fetches that resulted in a config reload due to a different config
   update_attempt, Counter, Total cluster membership update attempts
   update_success, Counter, Total cluster membership update successes
   update_failure, Counter, Total cluster membership update failures
+  update_empty, Counter, Total cluster membership updates ending with empty cluster load assignment and continuing with previous config
   version, Gauge, Hash of the contents from the last successful API fetch
   max_host_weight, Gauge, Maximum weight of any host in the cluster
-  bind_errors, Counter, Total errors binding the socket to the configured source address.
+  bind_errors, Counter, Total errors binding the socket to the configured source address
 
 Health check statistics
 -----------------------
@@ -189,6 +190,7 @@ the following statistics:
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
+  lb_recalculate_zone_structures, Counter, The number of times locality aware routing structures are regenerated for fast decisions on upstream locality selection
   lb_healthy_panic, Counter, Total requests load balanced with the load balancer in panic mode
   lb_zone_cluster_too_small, Counter, No zone aware routing because of small upstream cluster size
   lb_zone_routing_all_directly, Counter, Sending all requests directly to the same zone
@@ -196,6 +198,7 @@ the following statistics:
   lb_zone_routing_cross_zone, Counter, Zone aware routing mode but have to send cross zone
   lb_local_cluster_not_ok, Counter, Local host set is not set or it is panic mode for local cluster
   lb_zone_number_differs, Counter, Number of zones in local and upstream cluster different
+  lb_zone_no_capacity_left, Counter, Total number of times ended with random zone selection due to rounding error
 
 Load balancer subset statistics
 -------------------------------
@@ -207,8 +210,8 @@ decisions. Stats are rooted at *cluster.<name>.* and contain the following stati
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
-  lb_subsets_active, Gauge, Number of currently available subsets.
-  lb_subsets_created, Counter, Number of subsets created.
-  lb_subsets_removed, Counter, Number of subsets removed due to no hosts.
-  lb_subsets_selected, Counter, Number of times any subset was selected for load balancing.
-  lb_subsets_fallback, Counter, Number of times the fallback policy was invoked.
+  lb_subsets_active, Gauge, Number of currently available subsets
+  lb_subsets_created, Counter, Number of subsets created
+  lb_subsets_removed, Counter, Number of subsets removed due to no hosts
+  lb_subsets_selected, Counter, Number of times any subset was selected for load balancing
+  lb_subsets_fallback, Counter, Number of times the fallback policy was invoked

docs/root/configuration/configuration.rst

@@ -18,4 +18,5 @@ Configuration reference
   access_log
   rate_limit
   runtime
+  statistics
   tools/router_check

docs/root/configuration/http_conn_man/stats.rst

@@ -44,7 +44,7 @@ statistics:
    downstream_rq_rx_reset, Counter, Total request resets received
    downstream_rq_tx_reset, Counter, Total request resets sent
    downstream_rq_non_relative_path, Counter, Total requests with a non-relative HTTP path
-   downstream_rq_too_large, Counter, Total requests resulting in a 413 due to buffering an overly large body.
+   downstream_rq_too_large, Counter, Total requests resulting in a 413 due to buffering an overly large body
    downstream_rq_1xx, Counter, Total 1xx responses
    downstream_rq_2xx, Counter, Total 2xx responses
    downstream_rq_3xx, Counter, Total 3xx responses
@@ -52,7 +52,7 @@ statistics:
    downstream_rq_5xx, Counter, Total 5xx responses
    downstream_rq_ws_on_non_ws_route, Counter, Total WebSocket upgrade requests rejected by non WebSocket routes
    downstream_rq_time, Histogram, Request time milliseconds
-   rs_too_large, Counter, Total response errors due to buffering an overly large body.
+   rs_too_large, Counter, Total response errors due to buffering an overly large body
 
 Per user agent statistics
 -------------------------
@@ -99,17 +99,28 @@ Http2 codec statistics
 
 All http2 statistics are rooted at *http2.*
 
-
 .. csv-table::
    :header: Name, Type, Description
    :widths: 1, 1, 2
 
-   rx_reset, Counter, Total number of reset stream frames received by Envoy.
-   tx_reset, Counter, Total number of reset stream frames transmitted by Envoy.
-   header_overflow, Counter, Total number of connections reset due to the headers being larger than `Envoy::Http::Http2::ConnectionImpl::StreamImpl::MAX_HEADER_SIZE` (63k).
-   trailers, Counter, Total number of trailers seen on requests coming from downstream.
-   headers_cb_no_stream, Counter, Total number of errors where a header callback is called without an associated stream. This tracks an unexpected occurrence due to an as yet undiagnosed bug.
-   too_many_header_frames, Counter, Total number of times an HTTP2 connection is reset due to receiving too many headers frames. Envoy currently supports proxying at most one header frame for 100-Continue one non-100 response code header frame and one frame with trailers.
+   rx_reset, Counter, Total number of reset stream frames received by Envoy
+   tx_reset, Counter, Total number of reset stream frames transmitted by Envoy
+   header_overflow, Counter, Total number of connections reset due to the headers being larger than `Envoy::Http::Http2::ConnectionImpl::StreamImpl::MAX_HEADER_SIZE` (63k)
+   trailers, Counter, Total number of trailers seen on requests coming from downstream
+   headers_cb_no_stream, Counter, Total number of errors where a header callback is called without an associated stream. This tracks an unexpected occurrence due to an as yet undiagnosed bug
+   too_many_header_frames, Counter, Total number of times an HTTP2 connection is reset due to receiving too many headers frames. Envoy currently supports proxying at most one header frame for 100-Continue one non-100 response code header frame and one frame with trailers
+
+Tracing statistics
+------------------
 
+Tracing statistics are emitted when tracing decisions are made. All tracing statistics are rooted at *http.<stat_prefix>.tracing.* with the following statistics:
 
+.. csv-table::
+   :header: Name, Type, Description
+   :widths: 1, 1, 2
 
+   random_sampling, Counter, Total number of traceable decisions by random sampling
+   service_forced, Counter, Total number of traceable decisions by server runtime flag *tracing.global_enabled*
+   client_enabled, Counter, Total number of traceable decisions by request header *x-envoy-force-trace*
+   not_traceable, Counter, Total number of non-traceable decisions by request id
+   health_check, Counter, Total number of non-traceable decisions by health check

docs/root/configuration/http_filters/ip_tagging_filter.rst

@@ -28,9 +28,9 @@ the owning HTTP connection manager.
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
-        <tag_name>.hit, Counter, Total number of requests that have the <tag_name> applied to it.
-        no_hit, Counter, Total number of requests with no applicable IP tags.
-        total, Counter, Total number of requests the IP Tagging Filter operated on.
+        <tag_name>.hit, Counter, Total number of requests that have the <tag_name> applied to it
+        no_hit, Counter, Total number of requests with no applicable IP tags
+        total, Counter, Total number of requests the IP Tagging Filter operated on
 
 Runtime
 -------

docs/root/configuration/http_filters/router_filter.rst

@@ -259,6 +259,7 @@ prefix <config_http_conn_man_stat_prefix>` comes from the owning HTTP connection
   no_route, Counter, Total requests that had no route and resulted in a 404
   no_cluster, Counter, Total requests in which the target cluster did not exist and resulted in a 404
   rq_redirect, Counter, Total requests that resulted in a redirect response
+  rq_direct_response, Counter, Total requests that resulted in a direct response
   rq_total, Counter, Total routed requests
 
 Virtual cluster statistics are output in the

docs/root/configuration/listeners/stats.rst

@@ -40,8 +40,8 @@ statistics. Any ``:`` character in the stats name is replaced with ``_``.
    listener_added, Counter, Total listeners added (either via static config or LDS)
    listener_modified, Counter, Total listeners modified (via LDS)
    listener_removed, Counter, Total listeners removed (via LDS)
-   listener_create_success, Counter, Total listener objects successfully added to workers.
-   listener_create_failure, Counter, Total failed listener object additions to workers.
+   listener_create_success, Counter, Total listener objects successfully added to workers
+   listener_create_failure, Counter, Total failed listener object additions to workers
    total_listeners_warming, Gauge, Number of currently warming listeners
    total_listeners_active, Gauge, Number of currently active listeners
    total_listeners_draining, Gauge, Number of currently draining listeners

docs/root/configuration/network_filters/tcp_proxy_filter.rst

@@ -20,9 +20,9 @@ statistics are rooted at *tcp.<stat_prefix>.* with the following statistics:
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
-  downstream_cx_total, Counter, Total number of connections handled by the filter.
-  downstream_cx_no_route, Counter, Number of connections for which no matching route was found.
-  downstream_cx_tx_bytes_total, Counter, Total bytes written to the downstream connection.
-  downstream_cx_tx_bytes_buffered, Gauge, Total bytes currently buffered to the downstream connection.
-  downstream_flow_control_paused_reading_total, Counter, Total number of times flow control paused reading from downstream.
-  downstream_flow_control_resumed_reading_total, Counter, Total number of times flow control resumed reading from downstream.
+  downstream_cx_total, Counter, Total number of connections handled by the filter
+  downstream_cx_no_route, Counter, Number of connections for which no matching route was found
+  downstream_cx_tx_bytes_total, Counter, Total bytes written to the downstream connection
+  downstream_cx_tx_bytes_buffered, Gauge, Total bytes currently buffered to the downstream connection
+  downstream_flow_control_paused_reading_total, Counter, Total number of times flow control paused reading from downstream
+  downstream_flow_control_resumed_reading_total, Counter, Total number of times flow control resumed reading from downstream

docs/root/configuration/statistics.rst

@@ -0,0 +1,45 @@
+.. _statistics:
+
+Statistics
+==========
+
+A few statistics are emitted to report statistics system behavior:
+
+.. csv-table::
+  :header: Name, Type, Description
+  :widths: 1, 1, 2
+
+  stats.overflow, Counter, Total number of times Envoy cannot allocate a statistic due to a shortage of shared memory
+
+Server
+------
+
+Server related statistics are rooted at *server.* with following statistics:
+
+.. csv-table::
+  :header: Name, Type, Description
+  :widths: 1, 1, 2
+
+  uptime, Gauge, Current server uptime in seconds
+  memory_allocated, Gauge, Current amount of allocated memory in bytes
+  memory_heap_size, Gauge, Current reserved heap size in bytes
+  live, Gauge, "1 if the server is not currently draining, 0 otherwise"
+  parent_connections, Gauge, Total connections of the old Envoy process on hot restart
+  total_connections, Gauge, Total connections of both new and old Envoy processes
+  version, Gauge, Integer represented version number based on SCM revision
+  days_until_first_cert_expiring, Gauge, Number of days until the next certificate being managed will expire
+
+File system
+-----------
+
+Statistics related to file system are emitted in the *filesystem.* namespace.
+
+.. csv-table::
+  :header: Name, Type, Description
+  :widths: 1, 1, 2
+
+  write_buffered, Counter, Total number of times file data is moved to Envoy's internal flush buffer
+  write_completed, Counter, Total number of times a file was written
+  flushed_by_timer, Counter, Total number of times internal flush buffers are written to a file due to flush timeout
+  reopen_failed, Counter, Total number of times a file was failed to be opened
+  write_total_buffered, Gauge, Current total size of internal flush buffer in bytes