For the complete documentation index, see llms.txt. This page is also available as Markdown.

Obfuscate Traces

Obfuscate Traces

Overview

Protect sensitive data in your traces by masking or removing it before storage. By integrating data obfuscation directly into your traces pipeline, you maintain privacy and meet compliance requirements while still retaining the necessary operational details.

Why Obfuscate Traces?

Traces often contain sensitive information in payloads, headers, and attributes:

  • Personal Identifiable Information (PII) - emails, names, addresses in request/response bodies

  • Credentials - API keys, tokens, passwords in headers or payloads

  • Financial data - credit card numbers, account numbers in payment spans

  • Internal system details - internal IPs, service tokens in headers

Obfuscating this data helps you:

  • Meet compliance requirements (GDPR, PCI-DSS, HIPAA, etc.)

  • Protect customer privacy

  • Reduce security risks from leaked credentials

  • Maintain audit trails while removing sensitive details

Obfuscation Approaches

There are three approaches to obfuscating sensitive data in traces:

1. Automatic PII Detection with obfuscate_pii

Automatically detect and redact sensitive data, no regex required. This is the recommended approach for broad coverage with minimal configuration.

Best for: Broad PII protection across many pattern types with zero regex effort

2. Masking with replace_pattern

Replace parts of a string with a masking token (e.g., replacing email characters with asterisks). Use this when you want to preserve the field structure while hiding the sensitive value.

Best for: Custom patterns not covered by obfuscate_pii, partial masking with capture groups

3. Removing with delete_key

Remove fields that contain sensitive data entirely. Use this when the field is not required for downstream analysis.

Best for: API keys, passwords, tokens, unnecessary PII in attributes

Best Practices

  1. Apply obfuscation to the right scope - Target specific workloads, headers, or body fields rather than applying broadly

  2. Be specific with patterns - Avoid over-matching by using precise regex patterns

  3. Test thoroughly - Review rules carefully before deploying

  4. Document your rules - Use clear ruleName values to explain what each rule protects

  5. Balance utility and privacy - Mask data in a way that preserves operational value

  6. Combine approaches - Use obfuscate_pii for broad coverage and replace_pattern for custom patterns

  7. Order matters - Place obfuscation rules after transformation rules so useful fields are extracted first

Automatic PII Obfuscation

The obfuscate_pii function detects and redacts sensitive data across 16 built-in patterns — without writing any regex. It scans the specified field and replaces any detected PII in-place.

Supported Patterns

Pattern
Category
Example
Min Match Length

email

personal_info

user@example.com

6

credit_card

credit_card

4111-1111-1111-1111

13

ipv4_address

network_info

192.168.1.1

7

ipv6_address

network_info

::1

3

mac_address

network_info

11:22:33:44:55:66

17

url

network_info

https://example.com/path

10

jwt

auth_token

eyJhbGciOi...

20

bearer_token

auth_token

Bearer abc123xyz

10

aws_credential

cloud_credential

AKIAIOSFODNN7EXAMPLE

20

azure_credential

cloud_credential

azure_key=ABCDE...

15

github_token

api_token

ghp_xxxx...

40

gitlab_token

api_token

glpat-xxxx...

26

slack_token

api_token

xoxb-xxxx...

15

google_api_key

api_token

AIzaXXXX...

39

stripe_key

api_token

sk_live_xxxx...

24

private_key

private_key

-----BEGIN RSA PRIVATE KEY-----

50

Usage

Arguments:

Argument
Required
Description

field

Yes

The field to scan and obfuscate (e.g. request_body)

replacement

Yes

The string used to redact detected PII. A single ASCII character (e.g. "*") enables mask mode; a multi-character string uses replacement mode

patterns

Yes

Comma-separated list of pattern names to enable

Two replacement modes:

  • Mask mode (single ASCII character, e.g. "*") — overwrites each byte of the match with the mask char, preserving the original length. Recommended for structured payloads since the surrounding JSON stays byte-aligned.

  • Replacement mode (multi-character, e.g. "[R]") — replaces each match with the literal string and compacts the buffer (output is shorter than input). Length must be ≤ the shortest enabled pattern's min match length, or compilation fails.

Non-ASCII single runes (e.g. "•") are rejected since mask mode is byte-level.

Mode Comparison: Before / After

The same input run through each mode produces different outputs. Given this request body:

Mask mode with "*" — every PII byte is overwritten in place; quotes, commas, and braces stay at the same byte offsets, so the result is still valid JSON of the same length:

Replacement mode with "[R]" — each match is replaced by the literal string and the buffer compacts (output is shorter):

For trace bodies and headers that share storage with attribute strings, prefer mask mode so byte offsets are preserved and JSON parsing downstream is unaffected.

When PII is detected, obfuscate_pii automatically:

  1. Replaces the matched content in the target field

  2. Sets pii_<pattern>_detected = "true" as a span attribute

  3. Sets is_pii = true on the span

Common Use Cases

Obfuscate Request Body (mask mode — recommended for JSON payloads)

Scan request payloads for emails and cloud credentials. Single-character replacement ("*") selects mask mode, so the body's byte length is preserved and any JSON structure stays parseable downstream.

💡 What it does: Scans the request body for emails and AWS credentials, overwriting each matched byte with *. Automatically sets is_pii = true and detection attributes.

Obfuscate Response Body (replacement mode example)

Same idea, but using a multi-character replacement ("[R]") — this is replacement mode, so each match collapses to the literal string [R] and the buffer compacts. Use this only when you don't need to preserve byte offsets or JSON structure.

💡 What it does: Scans response bodies from the user service for emails, credit cards, and IP addresses. Each match is replaced with [R] and the buffer is compacted (output shorter than input).

Obfuscate Authorization Headers

Redact bearer tokens and JWTs in request headers (mask mode).

💡 What it does: Detects and redacts bearer tokens and JWTs in the Authorization header, byte-for-byte.

Scan All Request Headers

Scan every entry in request headers for sensitive data (mask mode).

💡 What it does: Scans all request header values for tokens and credentials, without needing to specify individual header names.

Obfuscate Span Attributes

Redact sensitive values stored in span attributes (mask mode).

💡 What it does: Detects and redacts email addresses in the user_email attribute, preserving the attribute's byte length.


Manual Obfuscation with replace_pattern

For custom patterns not covered by obfuscate_pii, use replace_pattern with regex.

Mask SSN in Attributes

💡 Example: 123-45-6789XXX-XX-XXXX

Redact Passwords in Request Body

💡 Example: {"password": "secret123"}{"password": "[REDACTED]"}

Redact Entire Response from Sensitive Server

💡 What it does: Completely replaces the response body for all spans from the vault service.

Redact Cookie Headers

💡 What it does: Removes cookie values from both request and response headers.

Removing Sensitive Attributes

Use delete_key to completely remove sensitive fields.

💡 What it does: Removes the entire api_key, secret_token, and password_hash attributes from auth service spans.

Key Functions

obfuscate_pii

Automatically detects and redacts sensitive data across built-in PII patterns.

Syntax:

Supported targets:

  • request_body / response_body — scan payloads

  • attributes["key"] — scan a specific attribute

  • attributes — scan ALL attributes

  • request_headers["key"] — scan a specific header

  • request_headers / response_headers — scan ALL headers

Available patterns: email, credit_card, ipv4_address, ipv6_address, mac_address, url, jwt, bearer_token, aws_credential, azure_credential, github_token, gitlab_token, slack_token, google_api_key, stripe_key, private_key

replace_pattern

Replaces text matching a pattern with a replacement string.

Syntax:

With capture groups:

delete_key

Completely removes a field from the attributes.

Syntax:

Last updated