Redact sensitive data

• 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 any SDK span.

​

Choose an approach

• Start with a masking function. It covers every record, and if it throws an error, 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.

​

Masking functions

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 setMaskingFunction() with your function. To remove it later, pass null.
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.

• 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

• 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>

import { setMaskingFunction, initLogger } from "braintrust";

// Mask API keys, passwords, and tokens
const maskFunction = (data: unknown): unknown => {
  if (typeof data === "string") {
    return data.replace(
      /\b(api[_-]?key|password|token)[\s:=]+\S+/gi,
      "$1: [REDACTED]",
    );
  }

  if (typeof data === "object" && data !== null) {
    if (Array.isArray(data)) {
      return data.map((item) => maskFunction(item));
    }

    const masked: Record<string, unknown> = {};
    for (const [key, value] of Object.entries(data)) {
      if (/^(api[_-]?key|password|secret|token|auth|credential)$/i.test(key)) {
        masked[key] = "[REDACTED]";
      } else {
        masked[key] = maskFunction(value);
      }
    }
    return masked;
  }

  return data;
};

setMaskingFunction(maskFunction);

const logger = initLogger({ projectName: "My Project" });

logger.log({
  input: { query: "Process payment", api_key: "your-api-key" },
  metadata: { password: "super-secret" },
});

​

Mask PII

import { setMaskingFunction, initLogger } from "braintrust";

const maskPII = (data: unknown): unknown => {
  if (typeof data === "string") {
    let masked = data;
    // Mask email addresses
    masked = masked.replace(
      /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
      "[EMAIL]",
    );
    // Mask phone numbers (US format)
    masked = masked.replace(/\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g, "[PHONE]");
    // Mask SSN
    masked = masked.replace(/\b\d{3}-\d{2}-\d{4}\b/g, "[SSN]");
    return masked;
  }

  if (typeof data === "object" && data !== null) {
    if (Array.isArray(data)) {
      return data.map((item) => maskPII(item));
    }

    const masked: Record<string, unknown> = {};
    for (const [key, value] of Object.entries(data)) {
      if (
        ["email", "phone", "ssn", "phone_number"].includes(key.toLowerCase())
      ) {
        masked[key] = `[${key.toUpperCase()}]`;
      } else {
        masked[key] = maskPII(value);
      }
    }
    return masked;
  }

  return data;
};

setMaskingFunction(maskPII);

// Usage example
const logger = initLogger({ projectName: "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",
    },
  },
});

​

Apply custom rules

• 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 { setMaskingFunction, initLogger } from "braintrust";

const customMask = (data: unknown): unknown => {
  // Handle different data types
  if (typeof data === "string") {
    // Only mask if the string contains certain keywords
    if (data.toLowerCase().includes("confidential")) {
      return "[CONFIDENTIAL DATA REMOVED]";
    }
    return data;
  }

  if (typeof data === "object" && data !== null) {
    // Handle special data structures
    if ("credit_card" in data && "cvv" in data) {
      // Mask credit card info but keep last 4 digits
      return {
        ...data,
        credit_card:
          typeof data.credit_card === "string"
            ? data.credit_card.replace(/\d(?=(?:\D*\d){4})/g, "X")
            : data.credit_card,
        cvv: "XXX",
      };
    }

    if (Array.isArray(data)) {
      return data.map((item) => customMask(item));
    }

    // Default object handling
    const masked: Record<string, unknown> = {};
    for (const [key, value] of Object.entries(data)) {
      // Skip masking for specific fields
      if (["timestamp", "request_id", "trace_id"].includes(key)) {
        masked[key] = value;
      } else {
        masked[key] = customMask(value);
      }
    }
    return masked;
  }

  return data;
};

setMaskingFunction(customMask);

// Usage example
const logger = initLogger({ projectName: "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",
  },
});

​

Span customizers

​

Register a customizer

1. Write the customizer. Create an object with an onSpanExport(data) method. It receives one record of the span’s data as a plain object and returns the record to upload, changed as needed. A span can have several records, as described in How customizers run.
2. Import configureInstrumentation() from braintrust/instrumentation. The same function is also exported from braintrust, but importing braintrust turns instrumentation on, so a call through that import logs a warning and has no effect.
3. Call it with your customizers at startup, before you import braintrust or any AI SDK.
4. Load braintrust and your AI SDKs with dynamic import() calls. Static imports are hoisted above the configureInstrumentation() call.

import {
  configureInstrumentation,
  type SpanCustomizer,
} from "braintrust/instrumentation";

const EMAIL = /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g;

function redactEmails(value: unknown): unknown {
  if (typeof value === "string") {
    return value.replace(EMAIL, "[EMAIL]");
  }
  if (Array.isArray(value)) {
    return value.map(redactEmails);
  }
  // Only walk plain objects, so SDK values such as attachments pass through
  if (
    typeof value === "object" &&
    value !== null &&
    Object.getPrototypeOf(value) === Object.prototype
  ) {
    return Object.fromEntries(
      Object.entries(value).map(([key, item]) => [key, redactEmails(item)]),
    );
  }
  return value;
}

const redactEmailAddresses: SpanCustomizer = {
  onSpanExport(data) {
    for (const field of ["input", "output", "metadata"]) {
      if (field in data) {
        data[field] = redactEmails(data[field]);
      }
    }
    return data;
  },
};

configureInstrumentation({ spanCustomizers: [redactEmailAddresses] });

const { initLogger } = await import("braintrust");
const { default: OpenAI } = await import("openai");

const logger = initLogger({ projectName: "my-project" }); // Replace with your project name
const client = new OpenAI();

await client.responses.create({
  model: "gpt-5-mini",
  input: "Draft a reply to jane@example.com.",
});

await logger.flush();

node --import braintrust/hook.mjs app.ts

​

Add tags and metadata

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 plain object with the merged fields.

import { type SpanCustomizer } from "braintrust/instrumentation";

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

const addEnvironment: SpanCustomizer = {
  onSpanExport(data) {
    const metadata = isRecord(data.metadata) ? data.metadata : {};
    const tags = Array.isArray(data.tags) ? data.tags : [];
    return {
      ...data,
      metadata: { ...metadata, environment: "production" },
      tags: tags.includes("production") ? tags : [...tags, "production"],
    };
  },
};

​

Chain customizers

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.

configureInstrumentation({
  spanCustomizers: [redactEmailAddresses, addEnvironment],
});

​

How customizers run

• All native SDK spans: The SDK runs customizers on all native SDK spans, including spans you create with traced(), startSpan(), and logger.log(), as well as spans from auto-instrumentation and wrappers. Customizers don’t run on 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: onSpanExport() must return the record directly. If it returns a promise, the SDK treats the call as a failure.
• OpenTelemetry compatibility mode: Customizers run when you enable compatibility mode with BRAINTRUST_OTEL_COMPAT or setupOtelCompat(), with @braintrust/otel v1.1.0 or later and SDK v3.38.0 or later. Earlier versions don’t apply customizers in compatibility mode.
• 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.

​

Customizer failures

​

OpenTelemetry spans

• Data: onSpanExport() receives a detached copy of the finished span as a plain object with keys such as name, kind, attributes, events, links, status, resource, and instrumentationScope. Span data such as inputs and outputs is in attributes. kind and status.code are integer values. Attribute values must be strings, numbers, booleans, or arrays of them.
• Once per span: Each customizer runs once per finished span, at export time, after filterAISpans or customFilter filtering. The SDK waits for asynchronous resource attributes first, so customizers can also change those.
• Protected fields: The SDK restores spanContext, parentSpanId, parentSpanContext, startTime, endTime, duration, and the braintrust.parent attribute after every call.
• Failures: If a customizer throws, or returns values that OpenTelemetry can’t export, the SDK logs an error once per process and exports only the span’s identity, timing, and braintrust.parent attribute, with the braintrust.context_json attribute set to {"customizer_error":true}. Other spans in the batch are exported normally. If the SDK can’t export even that, it drops the span.

​

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 logFeedback().
• Import path: configureInstrumentation() imported from braintrust has no effect. Import it from braintrust/instrumentation.
• Evaluation cache: In evaluations, the SDK caches span data on local disk for scorers before customizers and masking run. To keep unredacted values off local disk, pass enableCache: false in the Eval() options.

​

Next steps

• See all redaction options, including ingestion redaction, in Protect sensitive data.
• See setMaskingFunction(), configureInstrumentation(), and SpanCustomizer in the API reference.
• Set up auto-instrumentation for your AI SDKs.