Clarify meaning of latency headers in proxy page and update kong.log PDK latencies field

app/_src/gateway/how-kong-works/routing-traffic.md

@@ -495,12 +495,12 @@ This allow you to define two routes with two paths: `/service` and
 
 #### Using Regex in paths
 
-For a path to be considered a regular expression, it must be prefixed with a `~`: 
+For a path to be considered a regular expression, it must be prefixed with a `~`:
 
 ```
 paths: ["~/foo/bar$"]
 ```
-Any path that isn't prefixed with a `~` will be considered plain text: 
+Any path that isn't prefixed with a `~` will be considered plain text:
 
 ```
 "paths": ["/users/\d+/profile", "/following"]
@@ -541,8 +541,8 @@ defined URIs, in this order:
 3. `/version/any/`
 4. `/version`
 
-Routers with a large number of regexes can consume traffic intended for other rules. Regular expressions are much more expensive to build and execute and can't be optimized easily. 
-You can avoid creating complex regular expressions using the [Router Expressions language](/gateway/latest/reference/router-expressions-language/). 
+Routers with a large number of regexes can consume traffic intended for other rules. Regular expressions are much more expensive to build and execute and can't be optimized easily.
+You can avoid creating complex regular expressions using the [Router Expressions language](/gateway/latest/reference/router-expressions-language/).
 
 {% if_version lte:3.1.x %}
 If you see unexpected behavior, sending `Kong-Debug: 1` in your
@@ -979,7 +979,7 @@ There are two configurable elements here:
    means an error or timeout occurring while establishing a connection with the
    server, passing a request to it, or reading the response headers.
 
-The second option is based on Nginx's 
+The second option is based on Nginx's
 [`proxy_next_upstream`](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_next_upstream) directive. This option is not
 directly configurable through {{site.base_gateway}}, but can be added using a custom Nginx
 configuration. See the [configuration reference][configuration-reference] for
@@ -992,18 +992,25 @@ downstream client in a streaming fashion. At this point, {{site.base_gateway}} e
 subsequent plugins added to the route and/or service that implement a hook in
 the `header_filter` phase.
 
-Once the `header_filter` phase of all registered plugins has been executed, the
+Once the `header_filter` phase of all registered plugins has been executed, if the `latency_token` option is enabled, the
 following headers are added by {{site.base_gateway}} and the full set of headers be sent to
 the client:
 
 - `Via: kong/x.x.x`, where `x.x.x` is the {{site.base_gateway}} version in use
 - `X-Kong-Proxy-Latency: <latency>`, where `latency` is the time in milliseconds
   between {{site.base_gateway}} receiving the request from the client and sending the request to
-  your upstream service.
+  your upstream service. This value represents the pure Kong internal processing time, excluding
+  external factors such as upstream latency and third-party I/O latencies (e.g., Redis, DNS, HTTP calls, socket calls).
 - `X-Kong-Upstream-Latency: <latency>`, where `latency` is the time in
   milliseconds that {{site.base_gateway}} was waiting for the first byte of the upstream service
   response.
 
+{:.important}
+> **Important:** These latency headers are reported during the `header_filter` phase, which may occur before the full response body has been processed.
+<br><br>
+> In scenarios where body processing takes significant time, the latency values in these headers might not reflect the complete duration of the request lifecycle. For more accurate and comprehensive latency data, consider using Active Tracing in Konnect, the Analytics feature in Konnect, a metrics plugin (e.g., Prometheus), or a logging plugin
+(e.g., http-log)
+
 Once the headers are sent to the client, {{site.base_gateway}} starts executing
 registered plugins for the route and/or service that implement the
 `body_filter` hook. This hook may be called multiple times, due to the
@@ -1012,6 +1019,8 @@ successfully processed by such `body_filter` hooks is sent back to the client.
 You can find more information about the `body_filter` hook in the [Plugin
 development guide][plugin-development-guide].
 
+{{site.base_gateway}} also supports `advanced_latency_tokens` to expose more detailed timing headers such as total latency, third-party latency, and client latency. For details, see the [configuration-reference].
+
 ## Configuring a fallback route
 
 As a practical use-case and example of the flexibility offered by {{site.base_gateway}}'s

app/gateway/2.8.x/pdk/kong.log.md

@@ -398,6 +398,16 @@ Generates a table with useful information for logging.
  The following fields are included in the returned table:
  * `client_ip` - client IP address in textual format.
  * `latencies` - request/proxy latencies.
+     - `kong` - Time spent processing inside Kong (in ms), excluding upstream and third-party I/O.
+     - `proxy` - Time spent waiting for upstream response (in ms).
+     - `request` - Complete end-to-end request processing time (in ms).
+     - `receive` - Time spent receiving/processing upstream server response data (in ms).
+     - `client` - Time that Kong waits to receive headers and body from the client, plus how long Kong waits for the client to read/receive the response from Kong (in ms).
+     - `third_party` - Total time spent on third-party I/O (in ms), such as Redis, DNS, HTTP calls, and socket calls.
+     - `dns` - Time spent on DNS resolution (in ms).
+     - `redis` - Time spent on Redis operations (in ms).
+     - `http_client` - Time spent on HTTP client calls (in ms).
+     - `socket` - Time spent on generic socket operations (in ms).
  * `request.headers` - request headers.
  * `request.method` - request method.
  * `request.querystring` - request query strings.