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. Switch to 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

Group multiple related traces based on shared metadata or tags to understand the full context of multi-step operations.

On the Logs page, select Group 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.

Create custom columns

Surface important metadata, scores, or nested values directly in the logs table by creating custom columns. To create a custom column:

Select the column dropdown in the logs table.
Click + Add custom column.
Enter a name and 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.

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 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.

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

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

Create custom columns

Iterate in playgrounds

Organize with tags

Next steps

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

​Browse traces and spans

​Group related traces

​Create custom columns

​Iterate in playgrounds

​Organize with tags

​Next steps

Browse traces and spans

Group related traces

Create custom columns

Iterate in playgrounds

Organize with tags

Next steps