Custom facets

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.

​

When to create a custom facet

• Domain-specific categories: Your logs have patterns that built-in facets don’t capture.
• Too many uncategorized traces: The built-ins aren’t extracting relevant summaries.
• Wrong level of detail: You need more specific categorization (e.g., distinguish between different API endpoints instead of just “API request”).
• Business-specific needs: Track patterns unique to your product (e.g., “Feature requests,” “Pricing questions,” “Integration issues”).

​

Create a facet

1. Go to the Topics page and click + Facet.
2. Give your facet a name and description. The name cannot be changed after creation. Example:
   • “Churn risk”
   • “Facet for assessing customer churn risk based on conversations”
3. Choose a preprocessor to transform your trace data.
   • Select Preprocessor > Thread (default) to format traces as conversation threads.
   • Or select + Custom preprocessor to write a JavaScript function that filters or transforms your data. Common patterns:
     Extract user messages

     Format with metadata

     Filter to errors

     function userMessagesOnly(span) {
       const messages = span.input?.messages || [];
       const userMessages = messages
         .filter(m => m.role === 'user')
         .map(m => m.content)
         .join('\n\n');
     
       return userMessages || '(No user messages found)';
     }
     
4. Enter a prompt with clear instructions for what to extract. Example:
   Based on this conversation, assess the churn risk for this customer.
   
   Consider:
   
   - Frustration level and language used (complaints, strong negative words)
   - Whether their issue was resolved satisfactorily
   - Mentions of competitors, alternatives, or cancellation
   - Overall satisfaction signals (thanks, happy, vs angry, disappointed)
   - Severity and recurrence of issues
   
   Classify as:
   - LOW RISK: Satisfied customer, issue resolved, positive interaction
   - MEDIUM RISK: Some frustration but issue handled, no major red flags
   - HIGH RISK: Frustrated customer, unresolved issues, or mentions of dissatisfaction
   - CRITICAL: Explicitly mentioned canceling, switching to competitor, or very angry
   
   Respond with the label followed by a colon and the key risk indicators (one sentence).
   
   Examples:
   - "LOW_RISK: User thanked the agent and confirmed their billing question was answered."
   - "HIGH_RISK: User expressed frustration about repeated API errors and said this is unacceptable."
   - "CRITICAL: User stated they are considering switching to a competitor if issues persist."
   
5. Optionally, enter a case-insensitive regex to exclude facet outputs from topic generation. For example, if the facet output is 'NONE', a regex of '^NONE' will exclude it from being used in topic generation.
6. Click Test to verify extraction quality on sample traces.
7. Choose whether to Apply to existing traces or only to new traces.
   This option triggers processing across all automated facets, not just this one. Logs already processed for a given facet are skipped.
8. Click Create.

​

Manage facets

1. Go to the Topics page.
2. Find the facet’s card and select an action:
   • Pause or Resume — Click the Active toggle in the card header and confirm in the dialog.
   • Edit facet — In the ellipsis menu, select Edit facet. The facet panel opens on the Logs page where you can update the preprocessor, prompt, or exclusion pattern. To reprocess existing logs with the updated definition, enable Apply to existing traces before saving.
     This option triggers processing across all automated facets, not just this one. Logs already processed for a given facet are skipped.
   • Delete facet — In the ellipsis menu, select Delete facet. Built-in facets (Task, Sentiment, Issues) cannot be deleted.
     Permanently deleting a custom facet and its associated topics is irreversible. You cannot re-use the facet summaries for other topics in the future.

​

Common issues

​

Next steps

• Iterate on facet output using the Signals tab on individual traces.
• Rewind history to reprocess past traces after changing a facet prompt.
• Build datasets from logs classified by your new facet.