In critical scenarios, having access to payload details can help identify and pinpoint failures. With payload capture feature, a debug session can be configured to capture header and/or body for requests and response. However due to the nature of this telemetry, this feature requires customers to explicitly opt-in with a prior agreement called the Advanced Features Addendum. Once the agreement is in place, the feature is enabled in debugger.
Payload capture is an opt-in feature that can be enabled with prior agreement. Please contact your organization admin or reach out to your Kong representative
- Your organization has opted-in to use debugger’s payload capture feature and signed the Advanced Features Addendum
- Data plane nodes are deployed with new telemetry endpoints that support the payload capture feature
- Customer firewall rules updated to allow for the new telemetry endpoints
To use the payload capture during a debugging session, the data plane nodes have to be deployed with the following new telemetry endpoints:
* `KONG_CLUSTER_CONTROL_PLANE=xxx.us.cp.konghq.com:443`
* `KONG_CLUSTER_SERVER_NAME=xxx.us.cp.konghq.com`
* `KONG_CLUSTER_TELEMETRY_ENDPOINT=xxx.us.tp.konghq.com:443`
* `KONG_CLUSTER_TELEMETRY_SERVER_NAME=xxx.us.tp.konghq.com`
When a debug session is initiated with payload capture, the debugger captures request/response headers and/or body for all requests matching sampling criteria. Sampling filters and sanitization occur on the data plane before any data is transmitted to Konnect. Transactions are scrubbed using the log sanitizer, and sensitive data such as credit card numbers are redacted from the payload. Authentication and identity headers (for example, Authorization, API key header values, and consumer ID header fields) are also masked by default.
v3.14+ Gzip-encoded bodies (Content-Encoding: gzip or x-gzip) are automatically decompressed before capture, so they appear as readable text in the debugger.
Log sanitizer uses the Luhn algorithm, a well-known algorithm to validate credit card numbers, International Mobile Equipment Identity (IMEI) numbers, and other sensitive numerical data. The redaction is done by replacing the matched characters with *
You can define custom payload masking rules to target specific sensitive data in your requests and responses. Custom rules allow you to redact data in both headers and body content.
Custom masking rules require Kong Gateway version 3.14 or later.
Header masking rules let you redact the value of specific headers by name.
Body masking rules support two strategies:
-
JSONPath (RFC 9535): Target specific fields in JSON payloads using standard JSONPath expressions. This includes support for dot notation (
$.field), bracket notation, wildcards ([*]), recursive descent ($..), array slicing, and filter expressions.
-
Regex (PCRE): Match and redact patterns in the raw body content using PCRE-compatible regular expressions.
The redaction is done by replacing the matched content with *.
Custom masking rules are applied in addition to the built-in credit card redaction. The built-in Luhn algorithm-based redaction is always active and cannot be disabled.
By default, Konnect encrypts the captured payload with a default encryption key that has been provisioned for your org. However, you can configure Konnect to use a customer-managed encryption keys (CMEK). Konnect supports symmetric key encryption and integrates with AWS Key Management Services (KMS).
Debug session with payload data is retained for up to 3 days, after which they are purged from Konnect.
