Using Debugger for Datakit

When you run a Debugger session on a Kong Gateway instance that uses the Datakit plugin, Debugger captures tracing data for each Datakit node in the pipeline. This gives you visibility into how data flows through your Datakit configuration, which nodes ran, what values they received and produced, and where errors or skips occurred.

Datakit tracing provides debugging detail without exposing sensitive data. Kong Gateway tracks values as they move through the Datakit workflow and applies redaction and sanitization rules before sending trace data to Konnect.

To collect Datakit tracing events, start a Konnect Debugger session with body payload capture enabled. If header-only payload capture is enabled, node spans will be recorded but tracing events won’t be uploaded.

For each Datakit node that executes, Debugger creates a span named kong.datakit.node.NODE_NAME, where NODE_NAME is the name you assigned to the node in your Datakit configuration.

Node spans capture metadata about node execution but don’t contain node input or output values. Values are only captured in the separate Datakit tracing event payload.

If a node is skipped due to branch routing rules, it won’t create a span because execution hasn’t started. Information about skipped nodes is available in Datakit tracing events.

Each span includes the following attributes:

Tracing events capture the full lifecycle of each node, including input and output values. Each event corresponds to a specific point in a node’s execution and includes the data the node was working with at that point.

Note: Large values may be omitted from tracing events if they exceed the capture size limit.

Each tracing event includes the following fields:

Actions

The action field describes what happened to the node at the moment the event was recorded.

Datakit values can carry arbitrary content, including Vault secrets, authentication headers, personally identifiable information (PII), response bodies, and transformed values. Datakit applies redaction and sanitization rules based on the source of the node’s input. Tracing values are sanitized on the data plane before being transmitted to Konnect.

The same custom masking rules you configure for general Debugger payload capture also apply to Datakit tracing events.

Vault-derived values

Any value that comes from a Vault secret is always replaced with ********, regardless of other sanitization rules. If a node’s output is derived from a Vault-resolved value, the entire output is redacted.

Header sanitization

When a Datakit value is a headers map (a structured map of header name-value pairs), it’s sanitized using header-name rules. The following headers are masked by default:

• authorization
• api-key
• x-api-key
• x-consumer-username
• x-consumer-custom-id
• x-consumer-id
• x-credential-identifier

Header context is lost when a value passes through a transformation node like jq, json_to_xml, or xml_to_json. After transformation, the value no longer carries header context and is sanitized using body rules instead.

Body and structured value sanitization

String values are sanitized using body rules (regex or JSONPath). Structured values (maps and objects) are sanitized using body rules with JSONPath expressions applied to the structure. When a node’s output is assembled from individual field-level inputs, each field is sanitized independently according to the rules that apply to its source.

Node-specific sanitization behavior

The sanitization applied to a node’s tracing event values depends on the node type and the source of its inputs. In summary:

• Values that come from request data use sanitizer rules configured for request data.
• Values that come from response data use sanitizer rules configured for response data.
• Values that combine request and response data can use both request and response sanitizer rules.

The following table breaks down sanitization behavior by node:

Custom payload sanitization rules configured for Debugger also apply to Datakit tracing values. Custom body rules can use regex or JSONPath expressions (RFC 9535).

For object inputs and outputs, each field is sanitized independently. When a node’s output is assembled from field-level inputs (for example, request.headers connected to jq.headers), Datakit preserves per-field sanitization for that output. Transformed $self outputs, like the full output of a jq node, are sanitized as a single value.

Write JSONPath rules relative to the value as it appears in the tracing event. For example, jwt_decode output is an object with header, payload, and signature fields:

{
  "header": {
    "typ": "JWT",
    "alg": "HS256"
  },
  "payload": {
    "sub": "user-123",
    "email": "alice@example.com"
  },
  "signature": "..."
}

• To redact payload.sub, use $.payload.sub.
• To redact header.typ, use $.header.typ.

If the jwt_decode output is then passed through a jq node that reshapes it, write your JSONPath rule relative to the jq output structure instead.

To redact any field named sub regardless of its position in the structure, use the recursive deep-scan JSONPath rule $..sub.