docs: misc

docs/configuration/cluster_manager/cluster_stats.rst

@@ -9,49 +9,49 @@ Every cluster has a statistics tree rooted at *cluster.<name>.* with the followi
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
-  upstream_cx_total, Counter, Description
-  upstream_cx_active, Gauge, Description
-  upstream_cx_http1_total, Counter, Description
-  upstream_cx_http2_total, Counter, Description
-  upstream_cx_connect_fail, Counter, Description
-  upstream_cx_connect_timeout, Counter, Description
-  upstream_cx_connect_ms, Timer, Description
-  upstream_cx_length_ms, Timer, Description
-  upstream_cx_destroy, Counter, Description
-  upstream_cx_destroy_local, Counter, Description
-  upstream_cx_destroy_remote, Counter, Description
-  upstream_cx_destroy_with_active_rq, Counter, Description
-  upstream_cx_destroy_local_with_active_rq, Counter, Description
-  upstream_cx_destroy_remote_with_active_rq, Counter, Description
-  upstream_cx_close_header, Counter, Description
-  upstream_cx_rx_bytes_total, Counter, Description
-  upstream_cx_rx_bytes_buffered, Gauge, Description
-  upstream_cx_tx_bytes_total, Counter, Description
-  upstream_cx_tx_bytes_buffered, Gauge, Description
-  upstream_cx_protocol_error, Counter, Description
-  upstream_cx_max_requests, Counter, Description
-  upstream_cx_none_healthy, Counter, Description
-  upstream_rq_total, Counter, Description
-  upstream_rq_active, Gauge, Description
-  upstream_rq_pending_total, Counter, Description
-  upstream_rq_pending_overflow, Counter, Description
-  upstream_rq_pending_failure_eject, Counter, Description
-  upstream_rq_pending_active, Gauge, Description
-  upstream_rq_cancelled, Counter, Description
-  upstream_rq_timeout, Counter, Description
-  upstream_rq_per_try_timeout, Counter, Description
-  upstream_rq_rx_reset, Counter, Description
-  upstream_rq_tx_reset, Counter, Description
-  upstream_rq_retry, Counter, Description
-  upstream_rq_retry_success, Counter, Description
-  upstream_rq_retry_overflow, Counter, Description
-  upstream_rq_lb_healthy_panic, Counter, Description
-  membership_change, Counter, Description
-  membership_total, Gauge, Description
-  update_attempt, Counter, Description
-  update_success, Counter, Description
-  update_failure, Counter, Description
-  max_host_weight, Gauge, Description
+  upstream_cx_total, Counter, Total connections
+  upstream_cx_active, Gauge, Total active connections
+  upstream_cx_http1_total, Counter, Total HTTP/1.1 connections
+  upstream_cx_http2_total, Counter, Total HTTP/2 connections
+  upstream_cx_connect_fail, Counter, Total connection failures
+  upstream_cx_connect_timeout, Counter, Total connection timeouts
+  upstream_cx_connect_ms, Timer, Connection establishment milliseconds
+  upstream_cx_length_ms, Timer, Connection length milliseconds
+  upstream_cx_destroy, Counter, Total destroyed connections
+  upstream_cx_destroy_local, Counter, Total connections destroyed locally
+  upstream_cx_destroy_remote, Counter, Total connections destroyed remotely
+  upstream_cx_destroy_with_active_rq, Counter, Total connections destroyed with 1+ active request
+  upstream_cx_destroy_local_with_active_rq, Counter, Total connections destroyed locally with 1+ active request
+  upstream_cx_destroy_remote_with_active_rq, Counter, Total connections destroyed remotely with 1+ active request
+  upstream_cx_close_header, Counter, Total connections closed via HTTP/1.1 connection close header
+  upstream_cx_rx_bytes_total, Counter, Total received connection bytes
+  upstream_cx_rx_bytes_buffered, Gauge, Received connection bytes currently buffered
+  upstream_cx_tx_bytes_total, Counter, Total sent connection bytes
+  upstream_cx_tx_bytes_buffered, Gauge, Send connection bytes currently buffered
+  upstream_cx_protocol_error, Counter, Total connection protocol errors
+  upstream_cx_max_requests, Counter, Total connections closed due to maximum requests
+  upstream_cx_none_healthy, Counter, Total times connection not established due to no healthy hosts
+  upstream_rq_total, Counter, Total requests
+  upstream_rq_active, Gauge, Total active requests
+  upstream_rq_pending_total, Counter, Total requests pending a connection pool connection
+  upstream_rq_pending_overflow, Counter, Total requests that overflowed connection pool circuit breaking and were failed
+  upstream_rq_pending_failure_eject, Counter, Total requests that were failed due to a connection pool connection failure
+  upstream_rq_pending_active, Gauge, Total active requests pending a connection pool connection
+  upstream_rq_cancelled, Counter, Total requests cancelled before obtaining a connection pool connection
+  upstream_rq_timeout, Counter, Total requests that timed out waiting for a response
+  upstream_rq_per_try_timeout, Counter, Total requests that hit the per try timeout
+  upstream_rq_rx_reset, Counter, Total requests that were reset remotely
+  upstream_rq_tx_reset, Counter, Total requests that were reset locally
+  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_rq_lb_healthy_panic, Counter, Total requests load balanced with the load balancer in panic mode
+  membership_change, Counter, Total cluster membership changes
+  membership_total, Gauge, Current cluster membership total
+  update_attempt, Counter, Total cluster membership update attempts
+  update_success, Counter, Total cluster membership update successes
+  update_failure, Counter, Total cluster membership update failures
+  max_host_weight, Gauge, Maximum weight of any host in the cluster
 
 Health check statistics
 -----------------------

docs/configuration/http_conn_man/runtime.rst

@@ -6,14 +6,18 @@ The HTTP connection manager supports the following runtime settings:
 .. _config_http_conn_man_runtime_client_enabled:
 
 tracing.client_enabled
-  FIXFIX
+  % of requests that will be force traced if the
+  :ref:`config_http_conn_man_headers_x-client-trace-id` header is set. Defaults to 100.
 
 .. _config_http_conn_man_runtime_global_enabled:
 
 tracing.global_enabled
-  FIXFIX
+  % of requests that will be traced after all other checks have been applied (force tracing,
+  sampling, etc.). Defaults to 100.
 
 .. _config_http_conn_man_runtime_random_sampling:
 
 tracing.random_sampling
-  FIXFIX
+  % of requests that will be randomly traced. See :ref:`here <arch_overview_tracing>` for more
+  information. This runtime control is specified in the range 0-10000 and defaults to 0. Thus,
+  trace sampling can be specified in 0.01% increments.

docs/configuration/http_conn_man/stats.rst

@@ -10,42 +10,42 @@ statistics:
    :header: Name, Type, Description
    :widths: 1, 1, 2
 
-   downstream_cx_total, Counter, Description
-   downstream_cx_ssl_total, Counter, Description
-   downstream_cx_http1_total, Counter, Description
-   downstream_cx_http2_total, Counter, Description
-   downstream_cx_destroy, Counter, Description
-   downstream_cx_destroy_remote, Counter, Description
-   downstream_cx_destroy_local, Counter, Description
-   downstream_cx_destroy_active_rq, Counter, Description
-   downstream_cx_destroy_local_active_rq, Counter, Description
-   downstream_cx_destroy_remote_active_rq, Counter, Description
-   downstream_cx_active, Gauge, Description
-   downstream_cx_ssl_active, Gauge, Description
-   downstream_cx_http1_active, Gauge, Description
-   downstream_cx_http2_active, Gauge, Description
-   downstream_cx_protocol_error, Counter, Description
-   downstream_cx_length_ms, Timer, Description
-   downstream_cx_rx_bytes_total, Counter, Description
-   downstream_cx_rx_bytes_buffered, Gauge, Description
-   downstream_cx_tx_bytes_total, Counter, Description
-   downstream_cx_tx_bytes_buffered, Gauge, Description
-   downstream_cx_drain_close, Counter, Description
-   downstream_cx_idle_timeout, Counter, Description
-   downstream_rq_total, Counter, Description
-   downstream_rq_http1_total, Counter, Description
-   downstream_rq_http2_total, Counter, Description
-   downstream_rq_active, Gauge, Description
-   downstream_rq_response_before_rq_complete, Counter, Description
-   downstream_rq_rx_reset, Counter, Description
-   downstream_rq_tx_reset, Counter, Description
-   downstream_rq_non_relative_path, Counter, Description
-   downstream_rq_2xx, Counter, Description
-   downstream_rq_3xx, Counter, Description
-   downstream_rq_4xx, Counter, Description
-   downstream_rq_5xx, Counter, Description
-   downstream_rq_time, Timer, Description
-   failed_generate_uuid, Counter, Description
+   downstream_cx_total, Counter, Total connections
+   downstream_cx_ssl_total, Counter, Total SSL connections
+   downstream_cx_http1_total, Counter, Total HTTP/1.1 connections
+   downstream_cx_http2_total, Counter, Total HTTP/2 connections
+   downstream_cx_destroy, Counter, Total connections destroyed
+   downstream_cx_destroy_remote, Counter, Total connections destroyed due to remote close
+   downstream_cx_destroy_local, Counter, Total connections destroyed due to local close
+   downstream_cx_destroy_active_rq, Counter, Total connections destroyed with 1+ active request
+   downstream_cx_destroy_local_active_rq, Counter, Total connections destroyed locally with 1+ active request
+   downstream_cx_destroy_remote_active_rq, Counter, Total connections destroyed remotely with 1+ active request
+   downstream_cx_active, Gauge, Total active connections
+   downstream_cx_ssl_active, Gauge, Total active SSL connections
+   downstream_cx_http1_active, Gauge, Total active HTTP/1.1 connections
+   downstream_cx_http2_active, Gauge, Total active HTTP/2 connections
+   downstream_cx_protocol_error, Counter, Total protocol errors
+   downstream_cx_length_ms, Timer, Connection length milliseconds
+   downstream_cx_rx_bytes_total, Counter, Total bytes received
+   downstream_cx_rx_bytes_buffered, Gauge, Total received bytes currently buffered
+   downstream_cx_tx_bytes_total, Counter, Total bytes sent
+   downstream_cx_tx_bytes_buffered, Gauge, Total sent bytes currently buffered
+   downstream_cx_drain_close, Counter, Total connections closed due to draining
+   downstream_cx_idle_timeout, Counter, Total connections closed due to idle timeout
+   downstream_rq_total, Counter, Total requests
+   downstream_rq_http1_total, Counter, Total HTTP/1.1 requests
+   downstream_rq_http2_total, Counter, Total HTTP/2 requests
+   downstream_rq_active, Gauge, Total active requests
+   downstream_rq_response_before_rq_complete, Counter, Total responses sent before the request was complete
+   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_2xx, Counter, Total 2xx responses
+   downstream_rq_3xx, Counter, Total 3xx responses
+   downstream_rq_4xx, Counter, Total 4xx responses
+   downstream_rq_5xx, Counter, Total 5xx responses
+   downstream_rq_time, Timer, Request time milliseconds
+   failed_generate_uuid, Counter, Total UUID generation failures
 
 Per user agent statistics
 -------------------------

docs/configuration/http_filters/buffer_filter.rst

@@ -36,5 +36,5 @@ prefix <config_http_conn_man_stat_prefix>` comes from the owning HTTP connection
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
-  rq_timeout, Counter, Description
-  rq_too_large, Counter, Description
+  rq_timeout, Counter, Total requests that timed out waiting for a full request
+  rq_too_large, Counter, Total requests that failed due to being too large

docs/configuration/http_filters/grpc_http1_bridge_filter.rst

@@ -51,6 +51,6 @@ The filter emits statistics in the *cluster.<route target cluster>.grpc.* namesp
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
-  <grpc service>.<grpc method>.success, Counter, Description
-  <grpc service>.<grpc method>.failure, Counter, Description
-  <grpc service>.<grpc method>.total, Counter, Description
+  <grpc service>.<grpc method>.success, Counter, Total successful service/method calls
+  <grpc service>.<grpc method>.failure, Counter, Total failed service/method calls
+  <grpc service>.<grpc method>.total, Counter, Total service/method calls

docs/configuration/http_filters/rate_limit_filter.rst

@@ -43,17 +43,18 @@ The buffer filter outputs statistics in the *cluster.<route target cluster>.rate
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
-  ok, Counter, Description
-  error, Counter, Description
-  over_limit, Counter, Description
+  ok, Counter, Total under limit responses from the rate limit service
+  error, Counter, Total errors contacting the rate limit service
+  over_limit, Counter, total over limit responses from the rate limit service
 
 Runtime
 -------
 
 The HTTP rate limit filter supports the following runtime settings:
 
 ratelimit.http_filter_enabled
-  FIXFIX
+  % of requests that will call the rate limit service. Defaults to 100.
 
 ratelimit.http_filter_enforcing
-  FIXFIX
+  % of requests that will call the rate limit service and enforce the decision. Defaults to 100.
+  This can be used to test what would happen before fully enforcing the outcome.

docs/configuration/http_filters/router_filter.rst

@@ -154,20 +154,24 @@ prefix <config_http_conn_man_stat_prefix>` comes from the owning HTTP connection
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
-  no_route, Counter, Description
-  rq_redirect, Counter, Description
-  rq_total, Counter, Description
+  no_route, Counter, Total requests that had no route and resulted in a 404
+  rq_redirect, Counter, Total requests that resulted in a redirect response
+  rq_total, Counter, Total routed requests
 
 Runtime
 -------
 
 The router filter supports the following runtime settings:
 
 upstream.base_retry_backoff_ms
-  FIXFIX
+  Base exponential retry back off time. See :ref:`here <arch_overview_http_routing_retry>` for more
+  information. Defaults to 25ms.
 
 upstream.maintenance_mode.<cluster name>
-  FIXFIX
+  % of requests that will result in an immediate 503 response. This overrides any routing behavior
+  for requests that would have been destined for <cluster name>. This can be used for load
+  shedding, failure injection, etc. Defaults to disabled.
 
 upstream.use_retry
-  FIXFIX
+  % of requests that are eligible for retry. This configuration is checked before any other retry
+  configuration and can be used to fully disable retries across all Envoys if needed.

docs/configuration/listeners/runtime.rst

@@ -4,4 +4,5 @@ Runtime
 Listeners support the followiung runtime settings:
 
 ssl.alt_alpn
-  FIXFIX
+  What % of requests use the configured :ref:`alt_alpn <config_listener_ssl_context_alt_alpn>`
+  protocol string. Defaults to 0.

docs/configuration/listeners/ssl.rst

@@ -33,6 +33,8 @@ alpn_protocols
   * "h2,http/1.1" If the listener is going to support both HTTP/2 and HTTP/1.1.
   * "http/1.1" If the listener is only going to support HTTP/1.1
 
+.. _config_listener_ssl_context_alt_alpn:
+
 alt_alpn_protocols
   *(optional, string)* An alternate ALPN protocol string that can be switched to via runtime. This
   is useful for example to disable HTTP/2 without having to deploy a new configuration.

docs/configuration/listeners/stats.rst

@@ -9,13 +9,13 @@ Every listener has a statistics tree rooted at *listener.<port>.* with the follo
    :header: Name, Type, Description
    :widths: 1, 1, 2
 
-   downstream_cx_total, Counter, Description
-   downstream_cx_destroy, Counter, Description
-   downstream_cx_active, Gauge, Description
-   downstream_cx_length_ms, Timer, Description
-   ssl.connection_error, Counter, Description
-   ssl.handshake, Counter, Description
-   ssl.no_certificate, Counter, Description
-   ssl.fail_verify_san, Counter, Description
-   ssl.fail_verify_cert_hash, Counter, Description
-   ssl.cipher.<cipher>, Counter, Description
+   downstream_cx_total, Counter, Total connections
+   downstream_cx_destroy, Counter, Total destroyed connections
+   downstream_cx_active, Gauge, Total active connections
+   downstream_cx_length_ms, Timer, Connection length milliseconds
+   ssl.connection_error, Counter, Total SSL connection errors
+   ssl.handshake, Counter, Total SSL connection handshakes
+   ssl.no_certificate, Counter, Total SSL connections with no client certificate
+   ssl.fail_verify_san, Counter, Total SSL connections that failed SAN verification
+   ssl.fail_verify_cert_hash, Counter, Total SSL connections that failed certificate pinning verification
+   ssl.cipher.<cipher>, Counter, Total SSL connections that used <cipher>

docs/configuration/network_filters/client_ssl_auth_filter.rst

@@ -52,25 +52,50 @@ Every configured client SSL authentication filter has statistics rooted at
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
-  update_success, Counter, Description
-  update_failure, Counter, Description
-  auth_no_ssl, Counter, Description
-  auth_ip_white_list, Counter, Description
-  auth_digest_match, Counter, Description
-  auth_digest_no_match, Counter, Description
-  total_principals, Gauge, Description
+  update_success, Counter, Total principal update successes
+  update_failure, Counter, Total principal update failures
+  auth_no_ssl, Counter, Total connections ignored due to no SSL
+  auth_ip_white_list, Counter, Total connections allowed due to the IP white list
+  auth_digest_match, Counter, Total connections allowed due to certificate match
+  auth_digest_no_match, Counter, Total connections denied due to no certificate match
+  total_principals, Gauge, Total loaded principals
 
 Runtime
 -------
 
 The client SSL authentication filter supports the following runtime settings:
 
 auth.clientssl.refresh_interval_ms
-  FIXFIX
+  Time in milliseconds between principal refreshes from the authentication service. Default is
+  60000 (60s).
 
 .. _config_network_filters_client_ssl_auth_rest_api:
 
 REST API
 --------
 
-FIXFIX
+.. http:get:: /v1/certs/list/approved
+
+  The authentication filter will call this API every refresh interval to fetch the current list
+  of approved certificates/principals. The expected JSON response looks like:
+
+  .. code-block:: json
+
+    {
+      "certificates": []
+    }
+
+  certificates
+    *(required, array)* list of approved certificates/principals.
+
+  Each certificate object is defined as:
+
+  .. code-block:: json
+
+    {
+      "fingerprint_sha256": "...",
+    }
+
+  fingerprint_sha256
+    *(required, string)* The SHA256 hash of the approved client certificate. Envoy will match this
+    hash to the presented client certificate to determine whether there is a digest match.

docs/configuration/network_filters/rate_limit_filter.rst

@@ -47,20 +47,21 @@ following statistics:
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
-  total, Counter, Description
-  error, Counter, Description
-  over_limit, Counter, Description
-  ok, Counter, Description
-  cx_closed, Counter, Description
-  active, Gauge, Description
+  total, Counter, Total requests to the rate limit service
+  error, Counter, Total errors contacting the rate limit service
+  over_limit, Counter, Total over limit responses from the rate limit service
+  ok, Counter, Total under limit responses from the rate limit service
+  cx_closed, Counter, Total connections closed due to an over limit response from the rate limit service
+  active, Gauge, Total active requests to the rate limit service
 
 Runtime
 -------
 
 The network rate limit filter supports the following runtime settings:
 
 ratelimit.tcp_filter_enabled
-  FIXFIX
+  % of connections that will call the rate limit service. Defaults to 100.
 
 ratelimit.tcp_filter_enforcing
-  FIXFIX
+  % of connections that will call the rate limit service and enforce the decision. Defaults to 100.
+  This can be used to test what would happen before fully enforcing the outcome.