fix: Document Request ID in debugging, tracing, and logging (#7767)

* fix: Document Request ID in debugging, tracing, and logging

The doc is making a false assertion. The request_id is not guaranteed to be in the body on error but only appears in the response body in some cases, namely when the request is terminated with kong.response.error which uses error templates.

https://konghq.atlassian.net/browse/FTI-6056

* Apply suggestions from code review

* Apply suggestions from code review

---------

Co-authored-by: Angel <[email protected]>

app/_src/gateway/production/debug-request.md

@@ -62,7 +62,7 @@ The `X-Kong-Request-Debug-Token` is a token for authenticating the client and ma
 {% if_version gte:3.5.x %}
 ### X-Kong-Request-Id header
 
-The `X-Kong-Request-Id` header contains a unique identifier for each client request. This is enabled by default both upstream and downstream. This unique ID helps in matching specific requests to their corresponding error logs, which is useful for debugging. If {{site.base_gateway}} returns an error, the request ID will also be included in the response body generated by {{site.base_gateway}}. In addition, any {{site.base_gateway}} error log generated will contain the same request ID, with the format: `request_id: xxx`.
+The `X-Kong-Request-Id` header contains a unique identifier for each client request. This is enabled by default both upstream and downstream. This unique ID helps in matching specific requests to their corresponding error logs, which is useful for debugging. If {{site.base_gateway}} returns an error by calling the PDK `kong.response.error`, the request ID will also be included in the response body generated by {{site.base_gateway}}. In addition, any {{site.base_gateway}} error log generated will contain the same request ID, with the format: `request_id: xxx`.
 
 The log line produced by the debug header as well as the debug response header contains the request ID. You can use this to search for the debug header output using a log viewer UI. This is especially useful when the debug output is too long to fit in the response header. You can see an example log line that includes the Request ID in the [Truncation for large debugging output](#truncation-for-large-debugging-output) debug request example.
 {% endif_version %}

app/_src/gateway/production/logging/log-reference.md

@@ -19,7 +19,7 @@ Log levels are set in [Kong's configuration](/gateway/{{page.release}}/reference
 {% if_version gte:3.5.x %}
 ## Log the client request identifier
 
-The `X-Kong-Request-Id` header contains a unique identifier for each client request. This is enabled by default both upstream and downstream. This unique ID helps in matching specific requests to their corresponding error logs, which is useful for debugging. If {{site.base_gateway}} returns an error, the request ID will also be included in the response body generated by {{site.base_gateway}}. In addition, any {{site.base_gateway}} error log generated will contain the same request ID, with the format: `request_id: xxx`.
+The `X-Kong-Request-Id` header contains a unique identifier for each client request. This is enabled by default both upstream and downstream. This unique ID helps in matching specific requests to their corresponding error logs, which is useful for debugging. If {{site.base_gateway}} returns an error by calling the PDK `kong.response.error`, the request ID will also be included in the response body generated by {{site.base_gateway}}. In addition, any {{site.base_gateway}} error log generated will contain the same request ID, with the format: `request_id: xxx`.
 
 The log line produced by the debug header as well as the debug response header contains the request ID. You can use this to search for the debug header output using a log viewer UI. This is especially useful when the debug output is too long to fit in the response header.
 

app/_src/gateway/production/tracing/index.md

@@ -57,7 +57,7 @@ See the [kong.conf](/gateway/latest/reference/configuration/#headers) reference
 {% if_version gte:3.5.x %}
 ### X-Kong-Request-Id header
 
-The `X-Kong-Request-Id` header contains a unique identifier for each client request. This is enabled by default both upstream and downstream. This unique ID helps in matching specific requests to their corresponding error logs, which is useful for debugging. If {{site.base_gateway}} returns an error, the request ID will also be included in the response body generated by {{site.base_gateway}}. In addition, any {{site.base_gateway}} error log generated will contain the same request ID, with the format: `request_id: xxx`.
+The `X-Kong-Request-Id` header contains a unique identifier for each client request. This is enabled by default both upstream and downstream. This unique ID helps in matching specific requests to their corresponding error logs, which is useful for debugging. If {{site.base_gateway}} returns an error by calling the PDK `kong.response.error`, the request ID will also be included in the response body generated by {{site.base_gateway}}. In addition, any {{site.base_gateway}} error log generated will contain the same request ID, with the format: `request_id: xxx`.
 
 The log line produced by the debug header as well as the debug response header contains the request ID. You can use this to search for the debug header output using a log viewer UI. This is especially useful when the debug output is too long to fit in the response header.
 {% endif_version %}