Redact sensitive data

​

Register a customizer

1. Write the class. Define an on_span_export(span) method. It receives each completed span and returns the span to export. In the method:
   • Read the attributes you want to change. Integrations store the span’s content as JSON strings in braintrust.input_json (input), braintrust.output_json (output), and braintrust.metadata (metadata). Braintrust parses these into the span’s fields.
   • Change the span and return it. span.attributes is a writable hash, so you can replace or delete entries in place. You can also change other fields, such as span.name. To leave a span unchanged, return it as is.
2. Register an instance. Pass it in the span_customizers: array of Braintrust.init.

require "braintrust"
require "json"

class RedactEmails
  EMAIL = /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/
  CONTENT_KEYS = %w[braintrust.input_json braintrust.output_json braintrust.metadata].freeze

  def on_span_export(span)
    CONTENT_KEYS.each do |key|
      value = span.attributes[key]
      span.attributes[key] = value.gsub(EMAIL, "[EMAIL]") if value.is_a?(String)
    end
    span
  end
end

Braintrust.init(
  default_project: "my-project", # Replace with your project name
  span_customizers: [RedactEmails.new]
)

tracer = OpenTelemetry.tracer_provider.tracer("my-app")
tracer.in_span("draft-reply") do |span|
  span.set_attribute("braintrust.input_json", JSON.generate({to: "jane@example.com"}))
end

​

Add tags and metadata

1. Read the existing values. braintrust.metadata holds the span’s whole metadata object as a JSON string, and braintrust.tags holds its tags as an array of strings.
2. Merge in your values. Add your keys to the parsed metadata and your tags to the existing list. Replacing either attribute drops what was there.
3. Write the merged values back to span.attributes and return the span.

class AddEnvironment
  def on_span_export(span)
    existing = span.attributes["braintrust.metadata"]
    metadata = existing ? JSON.parse(existing) : {}
    metadata["environment"] = "production"
    tags = Array(span.attributes["braintrust.tags"]) | ["production"]
    span.attributes["braintrust.metadata"] = JSON.generate(metadata)
    span.attributes["braintrust.tags"] = tags
    span
  rescue JSON::ParserError
    span
  end
end

• Customizers that add data, like this one: Return the span unchanged when you can’t process it. This example does that when the existing metadata isn’t valid JSON.
• Customizers that redact data: Raise an error when you can’t redact a span, so the SDK drops the batch instead of sending unredacted data.

​

Chain customizers

1. Write each customizer separately, so each one handles one change and you can test and reuse it on its own.
2. List them in span_customizers: in the order you want them to run. Each customizer receives the span that the previous one returned.

Braintrust.init(
  default_project: "my-project", # Replace with your project name
  span_customizers: [RedactEmails.new, AddEnvironment.new]
)

​

How customizers run

• Every exported span: The SDK runs customizers on every span it exports, including spans from integrations, evaluations, and spans you create with the OpenTelemetry API. If you set filter_ai_spans: true or BRAINTRUST_OTEL_FILTER_AI_SPANS=true, the SDK exports only spans whose name or attributes start with gen_ai., braintrust., llm., ai., or traceloop.. Customizers don’t run on the spans that this filter or your span_filter_funcs drop.
• Once per completed span: The SDK runs each customizer once per span, after the span ends, on the background export thread. Keep customizers fast, because slow customizers delay exports. Spans that your customizer creates, for example by calling an instrumented client, aren’t traced.
• Identity: Customizers can change anything except the trace ID, span ID, and parent span ID, which are read-only. To return a different span instead, build it from span.to_span_data.dup so it keeps the same IDs, and return that OpenTelemetry::SDK::Trace::SpanData.

​

Limitations

• Code only: You register customizers in code, with Braintrust.init. There’s no environment variable for them, and braintrust/setup and braintrust exec can’t register them.
• Objects, not blocks: Each entry in span_customizers: must respond to on_span_export. Procs and lambdas don’t, so Braintrust.init raises an ArgumentError for them, and for any other object without the method.
• No custom exporter: Customizers run in the SDK’s exporter. If you pass both span_customizers: and exporter: to Braintrust.init, it raises an ArgumentError.
• Fixed at initialization: Braintrust.init copies the span_customizers: array, so later changes to the array don’t apply.
• Console output: Spans that BRAINTRUST_ENABLE_TRACE_CONSOLE_LOG prints aren’t customized.

​

Next steps

• See all redaction options, including ingestion redaction, in Protect sensitive data.
• See span_customizers in the API reference.
• Set up Ruby SDK integrations for your AI libraries.