View your logs

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

To browse logs from your terminal, use bt view logs. It opens an interactive terminal UI with search, filtering, and trace navigation. Pass --url to jump directly to a specific view from the Braintrust app.

Browse traces or 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

Filter traces

Each project provides default table views with common filters, including:

Default view: Shows all records
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 menu to switch the table view. You can also use the Filter menu to add custom filtering. See Filter and search logs for more details.

Built-in views (such as “All logs view”) cannot be modified, but you can create custom table views based on custom filters and display settings.

Group related traces by shared metadata or tags to understand 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.

Examine a trace

Select any trace from the logs table to open it in the trace viewer. See Examine traces for details on navigating trace views, layouts, and actions.

Delete traces

Delete traces from the log table using the Braintrust UI:

Select the traces you want to delete.
Click Delete selected rows from current project logs.
Confirm the deletion.

Mark logs for deletion by setting _object_delete:

import os
import requests

API_URL = "https://api.braintrust.dev/"
headers = {"Authorization": "Bearer " + os.environ["BRAINTRUST_API_KEY"]}

# Find logs to delete
query = """
SELECT id
FROM project_logs('project-id', shape => 'traces')
WHERE metadata.user_id = 'test-user'
"""

response = requests.post(
    f"{API_URL}/btql",
    headers=headers,
    json={"query": query}
).json()

ids = [row["id"] for row in response["data"]]

# Delete logs
delete_events = [{"id": id, "_object_delete": True} for id in ids]
requests.post(
    f"{API_URL}/v1/project_logs/project-id/insert",
    headers=headers,
    json={"events": delete_events}
)

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.

Assign for review

You can assign traces to team members for review, analysis, or follow-up action. Assignments are particularly useful for human review workflows, where you can assign specific rows that need human evaluation and distribute review work across multiple team members. See Assign rows for review for details.

Organize with tags

Tags help you categorize and track specific types of data across logs, datasets, and experiments. See Apply tags for how to configure tags and apply them via the UI or SDK.

Customize the logs table

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. When topics are enabled, facet summaries and classifications appear as columns in the logs table, similar to scores. You can filter and sort by facet columns to analyze patterns across your logs. For example, filter by Task to see all logs related to a specific user goal, or sort by Sentiment to identify negative interactions.

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.

Change the table density

To change the table density to see more or less detail per row, select Display > Row height > Compact or Tall.

Visualize topic distributions

Select Display > Row type > Topics to see topic distributions across all your facets. Each topic appears as a card showing its percentage of the total and trace count.

Create custom table views

To create or update a custom table view:

Apply the filters and display settings you want.
Open the menu and select Save view… or Save view as….

Custom table views are visible to all project members. Creating or editing a table view requires the Update project permission.

Set default table views

You can set default views at two levels:

Organization default: Visible to all members when they open the page. This applies per page — for example, you can set separate organization defaults for Logs, Experiments, and Review. To set an organization default, you need the Manage settings organization permission (included by default in the Owner role). See Access control for details.
Personal default: Overrides the organization default for you only. Personal defaults are stored in your browser, so they do not carry over across devices or browsers.

To set a default view:

Switch to the view you want by selecting it from the menu.
Open the menu again and hover over the currently selected view to reveal its submenu.
Choose Set as personal default view or Set as organization default view.

To clear a default view:

Open the menu and hover over the currently selected view to reveal its submenu.
Choose Clear personal default view or Clear organization default view.

When a user opens a page, Braintrust loads the first match in this order: personal default, organization default, then the standard “All …” view (e.g., “All logs view”).

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 or spans

Filter traces

Examine a trace

Delete traces

Analyze with Loop

Iterate in playgrounds

Assign for review

Organize with tags

Customize the logs table

Show and hide columns

Create custom columns

Change the table density

Visualize topic distributions

Create custom table views

Set default table views

Next steps

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Documentation Index

​Browse traces or spans

​Filter traces

​Group related traces

​Examine a trace

​Delete traces

​Analyze with Loop

​Iterate in playgrounds

​Assign for review

​Organize with tags

​Customize the logs table

​Show and hide columns

​Create custom columns

​Change the table density

​Visualize topic distributions

​Create custom table views

​Set default table views

​Next steps

Browse traces or spans

Filter traces

Group related traces

Examine a trace

Delete traces

Analyze with Loop

Iterate in playgrounds

Assign for review

Organize with tags

Customize the logs table

Show and hide columns

Create custom columns

Change the table density

Visualize topic distributions

Create custom table views

Set default table views

Next steps