> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Redact sensitive data

> Remove sensitive data from Python SDK traces before upload with a masking function, span customizers, or both.

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

* **[Masking functions](#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](#span-customizers)**: Change, add, or remove any field on records from instrumented spans.

<Note>
  To redact data after Braintrust receives it instead, or to see all redaction options, see [Protect sensitive data](/docs/admin/data-management/protect-sensitive-data).
</Note>

## 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](#how-customizers-run) |
| 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:

1. **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.
2. **Install it once, at startup.** Call [`set_masking_function()`](/docs/sdks/python/api-reference#set_masking_function) with your function. To remove it later, pass `None`.
3. **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.

```python expandable theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```python expandable wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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

```python expandable wrap theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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

<Note>
  Requires Python SDK v0.43.0 or later.
</Note>

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()`](/docs/sdks/python/api-reference#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](#masking-functions) to cover those spans.

### Register a customizer

To create a customizer and register it with the SDK:

1. **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](#how-customizers-run).
2. **Register an instance** with the `span_customizers` argument to `auto_instrument()`, or with [`set_span_customizers()`](/docs/sdks/python/api-reference#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:

```python app.py expandable theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:

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

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

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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:

1. **Write each customizer separately**, so each one handles one change and you can test and reuse it on its own.
2. **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`:

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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`.

<Warning>
  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.
</Warning>

## Limitations

* **Feedback comments and metadata**: When you [log user feedback](/docs/instrument/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](/docs/admin/data-management/protect-sensitive-data).
* See [`set_masking_function()`](/docs/sdks/python/api-reference#set_masking_function), [`set_span_customizers()`](/docs/sdks/python/api-reference#set_span_customizers), and [`SpanCustomizer`](/docs/sdks/python/api-reference#spancustomizer) in the API reference.
* Set up [auto-instrumentation](/docs/instrument/trace-llm-calls) for your AI libraries.