View 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. To view all logged spans individually instead, select Spans in dropdown at the top of the page. This is useful when you want to:

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

View multiple related traces together based on shared metadata or tags. This helps you understand the full context of multi-step operations and related requests.

On the Logs page, select Group and a tag or metadata path to group by.
Select a trace. If the trace includes the grouped attribute, the trace tree shows the trace with all other relevant traces, and the corresponding rows in the table are highlighted.
In the trace panel, select Timeline to view the timing of operations or Thread to view the entire session.

Create custom columns

Extract and display specific values from your traces as table columns. Custom columns let you surface important metadata, scores, or nested values directly in the logs table. To create custom columns:

Select the column dropdown in the logs table.
Click + Add custom column.
Enter a name and either choose from the inferred fields or enter a BTQL expression to extract the value.

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.

Filter and search logs

You can filter logs three ways:

Filter menu: Quick filters and BTQL queries for precise field matching
Loop and deep search: Natural language queries and AI-powered semantic search
API: Programmatic access for integrations and automation

Select Filter to filter logs by tags, time range, comments, and other fields. Use the Basic tab for quick filters, or select BTQL to write a BTQL query. Add your own query or select Generate to create a query from a natural language description.

Filter using Loop and deep search

Use Loop to ask questions about your logs and get AI-powered insights. Loop understands your data structure and can answer questions, identify patterns, and help you find specific traces.

Find similar traces: Select rows in the logs table and use Find similar traces. Loop analyzes the selected traces to identify common traits and returns similar traces.
Deep search: Use deep search to find traces based on semantic meaning rather than exact keywords. Deep search helps you discover patterns, sentiment, and edge cases that traditional filtering might miss.

Filter through the API

For basic filters and programmatic access, use the project logs endpoint. This endpoint supports the same query syntax as the UI and allows you to specify additional fields to return. For advanced queries, use the BTQL endpoint.

Iterate on prompts in playgrounds

Extract prompts and dataset inputs from logs to quickly iterate on them in playgrounds.

On the Logs page, select the rows you want to extract.
Select Iterate in playground.
Customize your playground settings, optionally appending the extracted resources to existing resources.
Select Create playground.

Apply tags to organize traces

Braintrust supports organizing logs with tags. Tags flow between logs, datasets, and experiments, so you can track specific types of data across your application and how they change over time. Tags are configured at the project level.

To configure tags:

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

Specify the tags field when logging data to add tags programmatically.

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

const logger = initLogger({
  projectName: "My Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});
const client = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));

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-3.5-turbo",
      messages: [{ role: "user", content: input }],
    });
    span.log({ input, output: result, tags: ["user-action"] });
    return {
      result,
      requestId: span.id,
    };
  });
}

Tags can only be applied to top-level spans, e.g., those created via traced() or logger.startSpan()/ logger.start_span(). You cannot apply tags to subspans (those created from another span) because they are properties of the whole trace, not individual spans.

You can also apply tags while capturing feedback via the logFeedback() / log_feedback() method.

import { initLogger } from "braintrust";

const logger = initLogger({
  projectName: "My project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

export async function POSTFeedback(req: Request) {
  const { spanId, comment, score, userId } = await req.json();
  logger.logFeedback({
    id: spanId, // Use the newly created span's id, instead of the original request's id
    comment,
    scores: {
      correctness: score,
    },
    metadata: {
      user_id: userId,
    },
    tags: ["user-feedback"],
  });
}

Next steps

Learn how to write logs to Braintrust
Use deep search to find traces semantically
Explore Loop for AI-powered insights
Write advanced queries with BTQL

Start

Integrations

Core

Context

Best practices

Reference

Browse traces and spans

Create custom columns

Filter and search logs

Filter menu

Filter using Loop and deep search

Filter through the API

Iterate on prompts in playgrounds

Apply tags to organize traces

Next steps

Start

Integrations

Core

Context

Best practices

Reference

​Browse traces and spans

​Group related traces

​Create custom columns

​Filter and search logs

​Filter menu

​Filter using Loop and deep search

​Filter through the API

​Iterate on prompts in playgrounds

​Apply tags to organize traces

​Next steps

Browse traces and spans

Group related traces

Create custom columns

Filter and search logs

Filter menu

Filter using Loop and deep search

Filter through the API

Iterate on prompts in playgrounds

Apply tags to organize traces

Next steps