Skip to main content

Documentation Index

Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

Once Topics is enabled, the pipeline runs on a daily cycle. This page covers the operations you’ll perform to keep it healthy: checking status, triggering runs on demand, tuning what gets processed, and replaying history. For facet-specific operations (creating, editing, deleting facets), see Custom facets.

​
Check automation status

Topics runs as a daily pipeline. To see a live indicator of the current stage:
Go to the Topics page. The Topics automation status panel shows:
  • Current pipeline state and when it was entered.
  • Next scheduled topic generation time.
  • Active facets, with health indicators for any unhealthy references.
  • Facet coverage: traces matched, processed, running, and errored per facet.
  • The most recent error, if any.
The Logs-page Topics > Status dialog provides the same information.
The pipeline moves through these stages:
StageMeaning
IdleWaiting until the next scheduled run. Trigger a run immediately with Re-generate topics.
Waiting for facetsWaiting for at least 100 processed traces before generating topics.
Recomputing topicsGenerating new topics based on collected facet summaries.
Pending logs processingNew topics generated; preparing to apply classifications to existing logs.
Processing logsApplying newly generated topics to existing logs.

​
Re-generate topics

Trigger an immediate run of the topic generation pipeline instead of waiting for the next daily cycle. Useful after enabling Topics, after raising the sampling rate, or whenever you want fresher classifications now.
Click Re-generate topics in the Topics automation status panel on the Topics page.

​
Adjust automation

Tune which traces are processed and how often the pipeline runs.
At high trace volume, a sampling rate as low as 5% often produces enough signal for meaningful topic clusters. Lower-volume projects benefit from keeping the rate higher so the 100-summary threshold for topic generation is met sooner.
Go to the Topics page and expand Automation settings in the status panel.
  • Filter: Restricts which traces are processed. Use the basic filter UI or enter a SQL expression directly.
  • Sampling rate: Percentage of incoming traces that get processed (default: 100%).
  • Idle time: Seconds after the last trace before the automation is run again (default: 600).
Click Save to apply changes.
You can also reach these fields from Settings > Automations by editing the Topics rule.

​
Process existing traces

Process existing traces to fill coverage gaps for logs that weren’t classified the first time, for example after raising the sampling rate. Traces that have already been processed are skipped.
  1. Go to the Topics page.
  2. In the status panel, click the ellipsis menu next to Re-generate topics and select Process existing traces.
  3. Choose a time range and confirm.
Processing a large window can be costly. Start with a narrow time range when possible.
To force recomputation of facets and topics for a window, for example after changing a facet prompt, use Rewind history instead.

​
Rewind history

bt topics rewind replays a window of historical traces through the Topics pipeline, recomputing facet summaries and classifications for all matching traces on the next executor pass. There is no UI equivalent for this operation. 
bt topics rewind 7d    # reprocess the last 7 days
bt topics rewind 1h    # reprocess the last hour
See bt topics rewind for all flags. This is useful after editing a custom facet or changing the automation filter. Rewind the affected window so existing traces pick up the new classifications without waiting for the daily cycle.

​
Common issues

Topics run on a daily cycle, so new classifications won’t appear immediately after enabling. See Check automation status to see where the pipeline is. If you want results sooner, re-generate topics to trigger a run immediately.
Topic generation requires at least 100 facet summaries. If the automation status shows Waiting for facets, more traces need to be processed first.
Classification runs automatically after topics are generated. Check the automation status:
  • Processing logs: Classification is in progress. Wait for it to complete.
  • Idle: Re-generate topics to trigger a new cycle.
  • Older logs: Only approximately the most recent 500 logs are backfilled on enable. Traces outside that window won’t have classifications.

​
Next steps