Clarify meaning of latency headers in proxy page and update kong.log PDK latencies field #8792
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This update improves the documentation for the X-Kong-Proxy-Latency and X-Kong-Upstream-Latency headers. It clarifies that X-Kong-Proxy-Latency measures only Kong's internal processing time, excluding upstream and third-party I/O latencies (such as Redis, DNS, HTTP calls, and socket calls). It also explains that latency headers are reported during the header_filter phase, which may be too early in cases where body processing is significant. As a result, the reported latency values might not reflect the full request lifecycle. For more comprehensive latency data, users are advised to use Active Tracing in Konnect, the Analytics feature in Konnect, a metrics plugin (e.g., Prometheus), or a logging plugin (e.g., http-log). We also added information about the new advanced_latency_tokens configuration option, which allows users to include additional latency tokens in the response headers. This feature is useful for those who want to customize the latency information returned in the response. Fix KAG-6992, DOCU-4190
✅ Deploy Preview for kongdocs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
locao
approved these changes
May 22, 2025
veenaraja
reviewed
May 22, 2025
| @@ -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]. | |||
There was a problem hiding this comment.
There is no mentioned of this advanced_latency_tokens in the config reference page. CAn you include how it need to be set right here?
Is it advanced_latency_tokens=true?
There was a problem hiding this comment.
It should be sourced from our kong.conf file. It's a value from the KONG_HEADERS config option.
lena-larionova
added
the
do not merge
gruceo
changed the title
| @@ -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. | |||
There was a problem hiding this comment.
Are all of these available in 2.8?
There was a problem hiding this comment.
No, only 3.11 onwards
There was a problem hiding this comment.
I was under the expectation that this page would be sourced from our log.lua PDK source code, but apparently it is not the case. We have to duplicate the docs in both places. Is that correct?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This update improves the documentation for the X-Kong-Proxy-Latency and X-Kong-Upstream-Latency headers. It clarifies that X-Kong-Proxy-Latency measures only Kong's internal processing time, excluding upstream and third-party I/O latencies (such as Redis, DNS, HTTP calls, and socket calls). It also explains that latency headers are reported during the header_filter phase, which may be too early in cases where body processing is significant. As a result, the reported latency values might not reflect the full request lifecycle. For more comprehensive latency data, users are advised to use Active Tracing in Konnect, the Analytics feature in Konnect, a metrics plugin (e.g., Prometheus), or a logging plugin (e.g., http-log).
We also added information about the new advanced_latency_tokens configuration option, which allows users to include additional latency tokens in the response headers. This feature is useful for those who want to customize the latency information returned in the response.
Additionally, we updated the documentation in kong.log.md to accurately describe all latency fields available in the latencies table returned by kong.log.serialize() such as receive, client, third_party, dns, redis, http_client, and socket as described in kong-ee. The update clarifies the meaning of each field and references the configuration option for advanced latency metrics. This improves clarity for plugin developers and users integrating with logging plugins, ensuring they understand the full set of latency metrics available for observability and troubleshooting.
Fix KAG-6992, DOCU-4190
Testing instructions
Preview link: https://deploy-preview-8792--kongdocs.netlify.app/
Checklist