docs: clarify x-request-id generation and preservation behavior (#43949)

## Description

Clarifies how `generate_request_id`, `use_remote_address`, and
`preserve_external_request_id` interact to control `x-request-id` header
handling. Adds a note to the headers documentation describing each
setting's role and summarizes the resulting behavior for each
combination.

This picks up and expands the work from #37616 (stale-closed),
incorporating reviewer feedback from @wbpcode to also cover
`generate_request_id` and to clarify that `preserve_external_request_id`
only applies when `use_remote_address` is `true`.

Relates to #36971.

---

**Commit Message:** docs: clarify x-request-id generation and
preservation behavior
**Risk Level:** N/A (docs only)
**Testing:** N/A
**Docs Changes:** Added note block to
`docs/root/configuration/http/http_conn_man/headers.rst`
**Release Notes:** N/A

Signed-off-by: kovan <xaum.io@gmail.com>

Author: kovan

docs/root/configuration/http/http_conn_man/headers.rst

@@ -556,6 +556,39 @@ following features are available:
 See the architecture overview on
 :ref:`context propagation <arch_overview_tracing_context_propagation>` for more information.
 
+.. note::
+
+ Three configuration settings control ``x-request-id`` generation and preservation:
+
+ :ref:`generate_request_id <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.generate_request_id>`
+  When ``true`` (the default), Envoy generates a new ``x-request-id`` for requests that
+  do not already have one. When ``false``, the entire request ID generation and mutation
+  logic is skipped. Disabling this can reduce overhead in high-throughput scenarios where
+  request ID tracking is not needed.
+
+ :ref:`use_remote_address <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.use_remote_address>`
+  When ``true``, Envoy uses the downstream connection's remote address to determine whether
+  a request is an *edge request* (i.e., from an external client). For edge requests, Envoy
+  replaces any existing ``x-request-id`` with a newly generated value by default. When
+  ``false`` (the default), requests are never treated as edge requests, so any existing
+  ``x-request-id`` is preserved.
+
+ :ref:`preserve_external_request_id <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.preserve_external_request_id>`
+  When ``true``, Envoy keeps an existing ``x-request-id`` on edge requests rather than
+  replacing it. This setting only has an effect when ``use_remote_address`` is ``true``,
+  since edge requests cannot occur otherwise.
+
+ The resulting behavior is:
+
+ * **No ``x-request-id`` in the request** -- Envoy generates a new UUID (if
+   ``generate_request_id`` is enabled).
+ * **``x-request-id`` present, non-edge request** (``use_remote_address`` is ``false``, or
+   the downstream address is internal) -- Envoy preserves the existing value.
+ * **``x-request-id`` present, edge request, ``preserve_external_request_id`` is ``false``**
+   -- Envoy replaces the value with a new UUID.
+ * **``x-request-id`` present, edge request, ``preserve_external_request_id`` is ``true``**
+   -- Envoy preserves the existing value.
+
 .. _config_http_conn_man_headers_x-ot-span-context:
 
 x-ot-span-context