Include scorer explanations in S3 exports

​

Summary

Use Logs (spans) or a Custom SQL export to include scorer explanations in S3.

​

What is happening

Trace-level exports write one summary row per trace. Scorer explanations live on individual scorer spans at output.metadata.rationale. A Logs (traces) export does not include that scorer metadata.

​

Fix or suggestion

​

Option 1: Switch the automation to Logs (spans)

1. Edit the export automation in the UI.
2. Change the data type to Logs (spans).
3. Save the automation.

Your chosen file format and S3 destination remain the same. Expect more rows and higher downstream processing costs. Update downstream mappings to handle multiple span rows per trace.

​

Option 2: Use a Custom SQL export (select scorer spans)

1. Edit the export automation and choose Custom SQL.
2. Use a query that reads spans and selects the scorer fields. Replace the placeholder '<project_id>' with your project ID.
   SELECT
     created,
     id,
     span_id,
     root_span_id,
     output.name AS scorer_name,
     output.score AS score,
     output.metadata.rationale AS explanation,
     output.metadata.reason AS reason,
     output.metadata AS scorer_metadata,
     error
   FROM project_logs('<project_id>', shape => 'spans')
   WHERE span_attributes.purpose = 'scorer'
     AND span_attributes.type = 'score'
   
   The query already includes the full scorer metadata to help locate rationales stored under another key.
3. Click Update automation to save the query.

​

How to confirm it worked

• Choose a scorer span that contains an explanation in Logs and find its exported row in S3.
• Compare the span’s explanation with output.metadata.rationale for Logs (spans) or explanation for the Custom SQL query above.

​

Notes

• To allow multiple automations in one project without updating the IAM trust policy for each automation, use a trust condition with StringLike and the external ID pattern bt:<org-id>:<project-id>:*.
• Changing an existing export keeps its checkpoint. To export historical spans, use Rewind. Rewind keeps existing files and can produce overlapping rows.
• If exports stall or show pending segments, contact Braintrust support for assistance.
• See Export to S3.