View your logs

To view logs from your application in real-time, go to your project in the Braintrust UI and select Logs.

Browse traces and spans

By default, logs display as a table of traces where each row represents a complete trace with its root span. Select Display > Row type > Spans view to see all logged spans individually. View individual spans when you want to:

Analyze specific operations within traces
Find particular function calls or API requests
Examine timing for individual operations

Change the display

Switch the view

Each project includes locked default views that cannot be modified, including:

Non-errors: Shows only records without errors
Errors: Shows only records with errors
Unreviewed: Hides items that have been human-reviewed
Assigned to me: Shows only records assigned to the current user for human review

Use the View menu to switch the view.

To set the current view as default, select Manage view > Set as your default view.
To discard unsaved changes and return to the default view, select Reset.

Create a custom view

Custom views save your table configurations including filters, column order, column visibility, and display settings. This lets you quickly switch between different ways of analyzing your logs. To create a custom view:

Apply the filters and display settings you want.
Select Save as in the toolbar.
Enter a view name.

Custom views are accessible and configurable by any member of the organization. When you create a custom view and set it as your default, it becomes your personal default view. The system default views remain available to all team members. Group multiple related traces based on shared metadata or tags to understand the full context of multi-step operations.

Select Display > Group trace by and choose a tag or metadata path.
Select a trace with the grouped attribute to see it alongside all related traces
Switch to Timeline view to see operation timing or Thread view for the entire session.

Filter traces

Select Filter to open the filter menu. Use the Basic tab for point-and-click filtering, or switch to SQL to write precise queries. The SQL editor includes Generate button that creates queries from natural language descriptions. See Filter and search logs for more details.

Show and hide columns

Select Display > Columns and then:

Show or hide columns to focus on relevant data
Reorder columns by dragging them
Pin important columns to the left

All column settings are automatically saved when you save a view.

Create custom columns

Surface important metadata, scores, or nested values directly in the logs table by creating custom columns:

Select Display > + Add custom column.
Name your column.
Choose from inferred fields or write a SQL expression.

For example, create a column named User ID with the expression metadata.user_id to display the user ID for each trace. Custom columns work the same way in both logs and experiments. For more details, see Create custom columns.

Adjust table layout

To change the table density to see more or less detail per row, select Display > Row height > Compact or Tall. To switch between different layouts, select Display > Layout and one of the following:

List: Default table view.
Grid: Compare outputs side-by-side.
Summary: Large-type summary of scores and metrics across all experiments.

Layouts respect view filters and are automatically saved when you save a view.

View individual traces

Select any trace from the logs table to open it in a panel on the right side of your screen. The trace shows all spans that make up the request, with detailed information about inputs, outputs, timing, and metadata. Use the button to expand the trace to fullscreen or the button to open it in a separate page.

Timeline view

Select Timeline to visualize the trace as a gantt chart. This view shows spans as horizontal bars where the width represents duration. Bars are color-coded by span type, making it easy to identify performance bottlenecks and understand the execution flow.

Thread view

Select Thread to view the trace as a conversation thread. This view displays messages, tool calls, and scores in chronological order, ideal for debugging LLM conversations and multi-turn interactions. Use Find or press Cmd/Ctrl+F to search within the thread view and quickly locate specific content such as message text and score rationale. Matches are highlighted in-place using your browser’s native highlighting.

Thread view searches only within the currently open trace, not across all traces in your project.

Custom view

Select Custom to create a custom visualization using natural language. Describe how you want to view your trace data and Loop will generate the code. For example:

“Create a view that renders a list of all tools available in this trace and their outputs”
“Render the video url from the trace’s metadata field and show simple thumbs up/down buttons”

To save a custom view, click Save version, select Save as new custom view version, and click Update. The saved view persists when viewing any trace in the project.

Self-hosted deployments: If you restrict outbound access, allowlist https://www.braintrustsandbox.dev to enable custom views. This domain hosts the sandboxed iframe that securely renders custom view code.

View raw trace data

When viewing a trace, select a span and then select the button in the span’s header to view the complete JSON representation. The raw data view shows all fields including metadata, inputs, outputs, and internal properties that may not be visible in other views. The raw data view has two tabs:

This span - Shows the complete JSON for the selected span only
Full trace - Shows the complete JSON for the entire trace

Use the search bar at the top of the dialog to find specific content within the data. Raw span data is useful when you need to:

Inspect the complete span structure for debugging
Find specific fields in large or deeply nested spans
Verify exact values and data types
Export or copy the full span for reproduction

Change span data views

When viewing a trace, each span field (input, output, metadata, etc.) displays data in a specific format. Change how a field displays by selecting the view mode dropdown in the field’s header. Available views:

Pretty - Parses objects deeply and renders values as Markdown (optimized for readability)
JSON - JSON highlighting and folding
YAML - YAML highlighting and folding
Tree - Hierarchical tree view for nested data structures

Additional format-specific views appear automatically for certain data types:

LLM - Formatted AI messages and tool calls with Markdown
LLM Raw - Unformatted AI messages and tool calls
HTML - Rendered HTML content

Your view mode selection is remembered per field type. To set a default view mode for all fields, go to Settings > Personal > Profile and select your preferred data view. See Personal settings for more details.

Analyze with Loop

Use Loop to query and analyze your logs through natural language. Loop is available on both the main Logs page and when viewing individual traces. See Analyze logs and Analyze individual traces for more details.

Iterate in playgrounds

Extract prompts and inputs from logs to quickly test variations in playgrounds.

Select the rows you want to extract.
Select Iterate in playground.
Customize settings and optionally append to existing resources.
Select Create playground.

Organize with tags

Tags help you categorize and track specific types of data across logs, datasets, and experiments.

Configure tags in your project:

Navigate to the Configuration tab
Add, modify, or delete tags with custom names, colors, and descriptions

Add tags programmatically when logging:

import { wrapOpenAI, initLogger } from "braintrust";
import { OpenAI } from "openai";

const logger = initLogger({ projectName: "My Project" });
const client = wrapOpenAI(new OpenAI());

export async function POST(req: Request) {
  return logger.traced(async (span) => {
    const input = await req.text();
    const result = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: input }],
    });
    span.log({ input, output: result, tags: ["user-action"] });
    return { result, requestId: span.id };
  });
}

Tags can be applied to any span in a trace. When viewing traces, tags from all spans are aggregated and displayed together at the trace level. This means you can add contextual tags to specific operations while still being able to filter traces by any of their contained tags.

Add tags when logging feedback:

import { initLogger } from "braintrust";

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

export async function POSTFeedback(req: Request) {
  const { spanId, comment, score, userId } = await req.json();
  logger.logFeedback({
    id: spanId,
    comment,
    scores: { correctness: score },
    metadata: { user_id: userId },
    tags: ["user-feedback"],
  });
}

Next steps

Analyze with Loop using natural language queries
Filter and search to find specific traces
Use deep search for semantic queries
Score online to evaluate production data
Create dashboards to monitor metrics

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Browse traces and spans

Change the display

Switch the view

Create a custom view

Filter traces

Show and hide columns

Create custom columns

Adjust table layout

View individual traces

Timeline view

Thread view

Custom view

View raw trace data

Change span data views

Analyze with Loop

Iterate in playgrounds

Organize with tags

Next steps

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

​Browse traces and spans

​Change the display

​Switch the view

​Create a custom view

​Group related traces

​Filter traces

​Show and hide columns

​Create custom columns

​Adjust table layout

​View individual traces

​Timeline view

​Thread view

​Custom view

​View raw trace data

​Change span data views

​Analyze with Loop

​Iterate in playgrounds

​Organize with tags

​Next steps

Browse traces and spans

Change the display

Switch the view

Create a custom view

Group related traces

Filter traces

Show and hide columns

Create custom columns

Adjust table layout

View individual traces

Timeline view

Thread view

Custom view

View raw trace data

Change span data views

Analyze with Loop

Iterate in playgrounds

Organize with tags

Next steps