Redact sensitive data

The Python SDK gives you two ways to remove sensitive data from traces before it leaves your application:

Masking functions: Replace sensitive parts of a fixed set of field values, on every record the SDK logs, including spans, dataset rows, and feedback scores.
Span customizers: Change, add, or remove any field on records from instrumented spans.

To redact data after Braintrust receives it instead, or to see all redaction options, see Protect sensitive data.

Choose an approach

	Masking function	Span customizer
Receives	One field value at a time	The whole record
Can change	`input`, `output`, `expected`, `metadata`, `context`, `scores`, and `metrics`	Any field except protected fields
Covers	Every record, including spans you create, dataset rows, and feedback scores	Spans from instrumentation and wrappers only
If it raises	The SDK uploads an error message instead of the field’s value	Undefined, so customizers must not raise

For sensitive data:

Start with a masking function. It covers every record, and if it raises an exception, the SDK uploads an error message in place of the affected field instead of the unmasked value.
Add span customizers for changes masking can’t make, such as editing tags or error, adding metadata, or deciding what to change based on other fields in the record.

When you use both, customizers run first, on each record. Masking then runs just before upload, after the SDK combines each span’s records, so it also sees your customizers’ output.

Masking functions

A masking function is a function you write that replaces sensitive parts of logged values, using rules such as matching field names like password or text patterns like email addresses. The SDK applies it just before upload to every record it logs, including spans, dataset rows, and feedback scores. To mask sensitive data with a masking function:

Write the function. It receives one logged value and returns the value to upload, with sensitive parts replaced. Values can be strings, objects, or arrays. The function can modify values in place to reduce copying.
Install it once, at startup. Call set_masking_function() with your function. To remove it later, pass None.
Test it against representative data. Check that sensitive values are masked and the rest of the trace stays intact. Use the examples below as starting points.

The SDK passes the value of each present field to the function separately: input, output, expected, metadata, context, scores, and metrics. It doesn’t pass error or tags, and it doesn’t say which field a value came from. If the function raises, the SDK keeps the affected field’s value out of the upload:

For input, output, expected, and context, it replaces the value with an error-message string.
For metadata, it replaces the value with an object containing an error message.
For scores and metrics, it removes the field and adds a diagnostic to the record’s error field.

Mask credentials

This example finds credentials by name and replaces them with [REDACTED], leaving the rest of the trace data as is. It replaces:

Values of fields named like a credential, such as api_key, password, and token
Text in strings that follows api_key, password, or token, such as password: <password>

It walks nested objects and arrays, so the same rules apply throughout the logged fields.

import re
import braintrust

def mask_sensitive_data(data):
    if isinstance(data, str):
        return re.sub(
            r"\b(api[_-]?key|password|token)[\s:=]+\S+",
            r"\1: [REDACTED]",
            data,
            flags=re.IGNORECASE,
        )

    elif isinstance(data, dict):
        masked = {}
        for key, value in data.items():
            if re.match(
                r"^(api[_-]?key|password|secret|token|auth|credential)$",
                key,
                re.IGNORECASE,
            ):
                masked[key] = "[REDACTED]"
            else:
                masked[key] = mask_sensitive_data(value)
        return masked

    elif isinstance(data, list):
        return [mask_sensitive_data(item) for item in data]

    return data

braintrust.set_masking_function(mask_sensitive_data)

logger = braintrust.init_logger(project="My Project")
logger.log(
    input={"query": "Process payment", "api_key": "your-api-key"},
    metadata={"password": "super-secret"},
)

The example replaces both input.api_key and metadata.password with [REDACTED] and keeps the query.

Mask PII

When you know which kinds of personally identifiable information (PII) your application records, match them by field name and regular expression. This example masks email addresses, US phone numbers, and social security numbers in text and nested fields. The patterns don’t detect every form of PII, such as person names, so adapt and test them for your data.

import re

import braintrust

def mask_pii(data):
    if isinstance(data, str):
        masked = data
        # Mask email addresses
        masked = re.sub(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b", "[EMAIL]", masked)
        # Mask phone numbers (US format)
        masked = re.sub(r"\b\d{3}[-.]?\d{3}[-.]?\d{4}\b", "[PHONE]", masked)
        # Mask SSN
        masked = re.sub(r"\b\d{3}-\d{2}-\d{4}\b", "[SSN]", masked)
        return masked

    elif isinstance(data, dict):
        masked = {}
        for key, value in data.items():
            if key.lower() in ["email", "phone", "ssn", "phone_number"]:
                masked[key] = f"[{key.upper()}]"
            else:
                masked[key] = mask_pii(value)
        return masked

    elif isinstance(data, list):
        return [mask_pii(item) for item in data]

    return data

braintrust.set_masking_function(mask_pii)

# Usage example
logger = braintrust.init_logger(project="My Project")
logger.log(
    input={
        "message": "Contact john.doe@example.com or call 555-123-4567",
        "user": {"name": "John Doe", "email": "john.doe@example.com", "phone": "555-123-4567", "ssn": "123-45-6789"},
    }
)

The example replaces the email address, phone number, and social security number with category markers, and leaves the name John Doe unchanged.

Apply custom rules

To keep useful context alongside masked values, write rules that understand the structure of your data. This example:

Keeps the last four card digits and the amount in a transaction, and replaces its CVV with XXX
Removes confidential text
Keeps identifiers and timestamps

import braintrust
import re

def custom_mask(data):
    # Handle different data types
    if isinstance(data, str):
        # Only mask if the string contains certain keywords
        if "confidential" in data.lower():
            return "[CONFIDENTIAL DATA REMOVED]"
        return data

    elif isinstance(data, dict):
        # Handle special data structures
        if "credit_card" in data and "cvv" in data:
            # Mask credit card info but keep last 4 digits
            masked_cc = data.get("credit_card", "")
            if isinstance(masked_cc, str):
                masked_cc = re.sub(r"\d(?=(?:\D*\d){4})", "X", masked_cc)

            return {
                **data,
                "credit_card": masked_cc,
                "cvv": "XXX",
            }

        # Default dict handling
        masked = {}
        for key, value in data.items():
            # Skip masking for specific fields
            if key in ["timestamp", "request_id", "trace_id"]:
                masked[key] = value
            else:
                masked[key] = custom_mask(value)
        return masked

    elif isinstance(data, list):
        return [custom_mask(item) for item in data]

    return data

braintrust.set_masking_function(custom_mask)

# Usage example
logger = braintrust.init_logger(project="My Project")
logger.log(
    input={
        "transaction": {
            "credit_card": "4532-1234-5678-9012",
            "cvv": "123",
            "amount": 15000,
            "timestamp": "2024-01-01T00:00:00Z",
        },
        "internal_note": "Confidential: Premium customer",
    },
    metadata={"trace_id": "trace-123", "debug_info": "Processing large transaction"},
)

The example keeps the card suffix 9012, the transaction amount 15000, and the timestamp. It replaces the CVV with XXX and the internal note with [CONFIDENTIAL DATA REMOVED], and leaves the metadata unchanged.

Span customizers

Requires Python SDK v0.43.0 or later.

A span customizer is an object whose on_span_export() method changes span data before the SDK uploads it. Use customizers to redact values, add tags or metadata, or remove fields, including tags and error. The SDK calls customizers on spans that auto_instrument() and wrappers such as wrap_openai() create. Customizers don’t run on spans you create yourself with traced(), start_span(), or logger.log(), so use them alongside the masking function to cover those spans.

Register a customizer

To create a customizer and register it with the SDK:

Subclass SpanCustomizer and override on_span_export(data). The method receives one record of the span’s data as a dict and returns the record to upload, changed as needed. A span can have several records, as described in How customizers run.
Register an instance with the span_customizers argument to auto_instrument(), or with set_span_customizers(), which you can call at any point in your program. Pass instances, such as RedactEmailAddresses(). Passing a class instead raises TypeError.

Registering a list replaces any customizers already installed:

To remove all customizers, call set_span_customizers(None) or set_span_customizers([]).
Calling auto_instrument() without span_customizers, or with span_customizers=None, leaves the installed customizers unchanged.

This example replaces email addresses in the input, output, and metadata of each LLM span:

app.py

import re

import braintrust
from braintrust import SpanCustomizer, SpanExportData

EMAIL = re.compile(r"[\w.+-]+@[\w-]+(?:\.[\w-]+)+")


def redact_emails(value):
    if isinstance(value, str):
        return EMAIL.sub("[EMAIL]", value)
    if isinstance(value, list):
        return [redact_emails(item) for item in value]
    # Only walk plain dicts, so SDK values such as attachments pass through
    if type(value) is dict:
        return {key: redact_emails(item) for key, item in value.items()}
    return value


class RedactEmailAddresses(SpanCustomizer):
    def on_span_export(self, data: SpanExportData) -> SpanExportData:
        for field in ("input", "output", "metadata"):
            if field in data:
                data[field] = redact_emails(data[field])
        return data


logger = braintrust.init_logger(project="my-project")  # Replace with your project name
braintrust.auto_instrument(span_customizers=[RedactEmailAddresses()])

from openai import OpenAI

client = OpenAI()
client.responses.create(
    model="gpt-5-mini",
    input="Draft a reply to jane@example.com.",
)

logger.flush()

In Braintrust, the LLM span’s input shows Draft a reply to [EMAIL].

Add tags and metadata

To add metadata or tags to a span without losing the values the integration recorded:

Read the record’s existing metadata and tags, if the record has them.
Merge in your values. Replacing metadata or tags drops the values the integration put in that record.
Return the record, or a new dict with the merged fields.

This example adds an environment metadata key and a production tag:

from braintrust import SpanCustomizer, SpanExportData


class AddEnvironment(SpanCustomizer):
    def on_span_export(self, data: SpanExportData) -> SpanExportData:
        data["metadata"] = {**(data.get("metadata") or {}), "environment": "production"}
        tags = list(data.get("tags") or [])
        if "production" not in tags:
            tags.append("production")
        data["tags"] = tags
        return data

Chain customizers

To run more than one customizer:

Write each customizer separately, so each one handles one change and you can test and reuse it on its own.
Pass them in the order you want them to run. Each customizer receives the record that the previous one returned.

This example runs RedactEmailAddresses, then AddEnvironment:

braintrust.set_span_customizers([RedactEmailAddresses(), AddEnvironment()])

How customizers run

Instrumented spans only: The SDK runs customizers on spans that integrations create, through auto_instrument() or wrapper functions such as wrap_openai(). It doesn’t run them on spans you create with traced(), start_span(), or logger.log(), dataset rows, or feedback.
Several calls per span: The SDK sends each span’s data in several records as the data becomes available, such as one record with the input when an LLM call starts and another with the output when it finishes. Braintrust combines the records into one span. Your customizer runs once on each record, so:
- A field can be missing from any one call. Check that a field is present before you change it.
- A call can’t see the span’s other records. For example, it can’t change the output based on the input.
Synchronous: on_span_export() must be a regular method. set_span_customizers() and auto_instrument() raise TypeError for an async method.
Protected fields: The SDK restores these fields after every call, so changing them has no effect: id, span_id, root_span_id, span_parents, org_id, project_id, experiment_id, dataset_id, prompt_session_id, log_id, function_data, _is_merge, _merge_paths, _parent_id, _object_delete, _array_delete, and _xact_id.

A customizer must not raise an exception. If it does, the span data can be left in an unexpected state. Catch exceptions inside on_span_export() and return a safe result, such as the record with the sensitive field removed, and test customizers against representative data.

Limitations

Feedback comments and metadata: When you log user feedback, the masking function runs on its scores and expected values but not on its comment or metadata. If users can type sensitive data into feedback, remove it before you call log_feedback().
One list per process: Each call to set_span_customizers(), and each auto_instrument() call that passes span_customizers, replaces the whole list. Install every customizer your process needs in one call.

Next steps

See all redaction options, including ingestion redaction, in Protect sensitive data.
See set_masking_function(), set_span_customizers(), and SpanCustomizer in the API reference.
Set up auto-instrumentation for your AI libraries.

Use the SDK

Features

Reference

Related packages

Redact sensitive data

Choose an approach

Masking functions

Mask credentials

Mask PII

Apply custom rules

Span customizers

Register a customizer

Add tags and metadata

Chain customizers

How customizers run

Limitations

Next steps

​Choose an approach

​Masking functions

​Mask credentials

​Mask PII

​Apply custom rules

​Span customizers

​Register a customizer

​Add tags and metadata

​Chain customizers

​How customizers run

​Limitations

​Next steps

Choose an approach

Masking functions

Mask credentials

Mask PII

Apply custom rules

Span customizers

Register a customizer

Add tags and metadata

Chain customizers

How customizers run

Limitations

Next steps