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

# Custom facets

> Define domain-specific facets with custom preprocessors and prompts to extract patterns the built-in Task, Sentiment, and Issues facets miss.

The built-in facets (Task, Sentiment, Issues) cover general patterns, but most products have domain-specific signals worth tracking. Custom facets let you define your own extractors with a preprocessor, prompt, and optional exclusion regex.

<Tip>
  Custom facets inherit the Topics automation's [scope](/observe/topics/manage#adjust-automation). If your facet should analyze a session or multi-turn conversation as a whole, configure the automation to [group traces](/observe/topics/manage#group-traces-into-conversations) before testing.
</Tip>

## When to create a custom facet

Create a custom facet when the built-ins don't capture the patterns you need:

* **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").

For example, to assess customer churn risk, create a custom "Churn risk" facet that analyzes conversations to classify users as low, medium, high, or critical risk based on satisfaction, language, and outcome.

## Create a facet

1. Go to the [**<Icon icon="pentagon" /> Topics**](https://www.braintrust.dev/app/~/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 **Thread** (default) to format traces as conversation threads using Braintrust's built-in preprocessor.
   * Select **+ Custom preprocessor (advanced)** to write a JavaScript function that reshapes non-standard traces. See [Write a custom preprocessor](/observe/topics/enable#write-a-custom-preprocessor) for examples.

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. Verify extraction quality on a real trace. Open a trace in the side panel to enable the test buttons, then:
   * Next to the preprocessor, click <Icon icon="play" /> **Test with selected trace** to preview just the preprocessor's output.
   * At the bottom of the panel, click <Icon icon="play" /> **Test with selected trace** to run the full facet (preprocessor and prompt) end to end.

7. Choose whether to **Apply to existing traces** or only to new traces.

   <Note>
     This option triggers processing across all automated facets, not just this one. Logs already processed for a given facet are skipped.
   </Note>

8. Click **Create**.

## Manage facets

1. Go to the [**<Icon icon="pentagon" /> Topics**](https://www.braintrust.dev/app/~/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 **<Icon icon="pencil-line" /> 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.

     <Note>
       This option triggers processing across all automated facets, not just this one. Logs already processed for a given facet are skipped.
     </Note>
   * **Edit clustering settings** — In the ellipsis menu, select **<Icon icon="settings-2" /> Edit clustering settings** to control how the facet's summaries are grouped into topics. See [Tune clustering settings](/observe/topics/manage#tune-clustering-settings).
   * **Delete facet** — In the ellipsis menu, select **<Icon icon="trash-2" /> Delete facet**. Built-in facets (Task, Sentiment, Issues) cannot be deleted.

     <Warning>
       Permanently deleting a custom facet and its associated topics is irreversible. You cannot re-use the facet summaries for other topics in the future.
     </Warning>

## Common issues

<AccordionGroup>
  <Accordion title="Poor topic quality">
    **Too many uncategorized traces**: Topics may be too specific for your data. Try [adjusting the automation filter](/observe/topics/manage#adjust-automation) to include a broader range of traces, or use a more targeted prompt when [creating a facet](#create-a-facet).

    **Topics too generic**: Refine the facet prompt to extract more specific summaries, such as distinguishing between different task subtypes.

    **Summaries too similar**: If the facet produces nearly identical summaries, clustering can't differentiate well. Review sample summaries and [adjust the prompt](#create-a-facet) to capture more variation.
  </Accordion>
</AccordionGroup>

## Next steps

* [Iterate on facet output](/observe/examine-traces#test-and-apply-evaluators) using the Evaluators tab on individual traces.
* [Rewind history](/observe/topics/manage#rewind-history) to reprocess past traces after changing a facet prompt.
* [Build datasets](/observe/topics/act-on-findings#build-datasets-from-topics) from logs classified by your new facet.