> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# bt observability

> Export and apply portable JSON configuration for facets, Topics settings, and Loop automations.

`bt observability template pull` exports a project's facets, their Topics automation settings, and Loop automations into a portable JSON template. `bt observability template push` applies a template to a project. Use these commands to store and reuse active observability configuration.

> [!WARNING]
>
> Observability templates are in [public preview](https://docs.braintrust.dev/feature-lifecycle.md) and can change before reaching general availability.

All `bt observability` subcommands accept the shared [`bt` global flags](https://docs.braintrust.dev/reference/cli/overview#global-flags).

## bt observability template pull

Pull facets, their Topics automation settings, and Loop automations from a project:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt observability template pull --output observability-template.json
```

In an interactive terminal, `bt` lets you select the facets and Loop automations to include. It preselects facets connected to a Topics automation and Loop automations that are not paused. With `--no-input` or `--json`, the template includes only those resources.

The template bundles the settings of each Topics automation that a selected facet belongs to. If a facet's Topics automation is scoped to a specific experiment, the pull fails because the experiment ID doesn't exist in other projects. Topic map definitions and generated topics are not exported.

Without `--output`, the command writes the template to stdout. Use `--output -` to request stdout explicitly. If the output file already exists, pass `--force` to replace it.

### Pull flags

| Flag | Env var | Description |
| - | - | - |
| `--output <PATH>`, `-O <PATH>` | `BRAINTRUST_OBSERVABILITY_TEMPLATE_PULL_OUTPUT` | Write the template to a file instead of stdout. Use `-` for stdout |
| `--force` | `BRAINTRUST_OBSERVABILITY_TEMPLATE_PULL_FORCE` | Replace an existing output file |

## bt observability template push

Push a template to a project from a local file, a public URL, or stdin:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt observability template push observability-template.json --project target-project
bt observability template push https://example.com/observability-template.json --project target-project
bt observability template pull | bt observability template push - --project target-project
```

In an interactive terminal, `bt` displays the number of facets and Loop automations in the template and asks for confirmation before making changes. Pass `--yes` to skip the prompt.

If a facet, preprocessor, topic map, or Loop automation conflicts with a matching resource in the destination project, the command stops unless you pass `--force` to replace it.

When applying the template, `bt` handles related configuration as follows:

* **Facets:** The template preserves each facet's relationship with its Topics automation. By default, `bt` uses the Topics automation named by the template, creating one if needed. If a facet does not name an automation, `bt` uses the destination project's only Topics automation. The command stops when it cannot infer one because the project has zero or multiple Topics automations. Pass `--topics-automation <NAME_OR_ID>` to connect every imported facet to one existing Topics automation instead.
* **Topics settings:** A new Topics automation uses the settings bundled in the template, including its scope, automation-level filter, sampling, model, status, and timing. An existing Topics automation whose settings and description match the template is left unchanged. If they differ, the command stops unless you pass `--force`, which replaces the settings in full and drops settings that exist only in the destination. With `--topics-automation`, `bt` keeps that automation's existing settings instead of the template's. The server validates and can normalize timing settings, so the applied values can differ from the template. Templates with `schema_version` 1 don't bundle Topics settings, so they use the destination's existing or default settings.
* **Topic maps:** `bt` rebuilds each facet's topic map wiring in the destination project. If the selected Topics automation already binds a topic map to an imported facet, the command stops unless you pass `--force`. With `--force`, `bt` replaces the facet's topic map binding in the selected Topics automation only. It reuses or creates the topic map with the slug generated from the template and detaches superseded topic maps from that automation. Other automations keep their bindings. Detached topic maps remain in the project, and the push output lists them. Topics update the next time the Topics pipeline runs.
* **Loop automations:** Destination settings such as Slack channels and webhooks are not included in the template. When replacing an existing Loop automation, `bt` preserves its destination settings. A new Loop automation has no destinations until you configure them in the target project.

### Push flags

| Flag | Env var | Description |
| - | - | - |
| `--file <SOURCE>`, `-f <SOURCE>` | `BRAINTRUST_OBSERVABILITY_TEMPLATE_PUSH_FILE` | Read from a local path, public URL, or `-` for stdin instead of using the positional source |
| `--topics-automation <NAME_OR_ID>` | `BRAINTRUST_OBSERVABILITY_TEMPLATE_PUSH_TOPICS_AUTOMATION` | Connect every imported facet to an existing Topics automation |
| `--force` | `BRAINTRUST_OBSERVABILITY_TEMPLATE_PUSH_FORCE` | Replace matching resources |
| `--yes`, `-y` | `BRAINTRUST_OBSERVABILITY_TEMPLATE_PUSH_YES` | Skip the confirmation prompt |

## Template format

An observability template is a JSON object with a schema version, facets, Topics automation settings, and Loop automations:

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "kind": "active_observability_template",
  "schema_version": 2,
  "facets": [],
  "topics_automations": [],
  "automations": []
}
```

Facet entries include their definitions, any bundled preprocessors, and the name of their Topics automation. Each `topics_automations` entry contains a Topics automation's `name`, `description`, and `config`, without the project-specific `facet_functions` and `topic_map_functions` wiring. Every Topics automation that a facet names must have an entry. Automation entries contain Loop configuration without destination settings. `bt observability template push` validates the template before planning changes to the target project. It also accepts templates with `schema_version` 1, which have no `topics_automations` field.

## Next steps

* Learn how [facets and Topics](https://docs.braintrust.dev/observe/topics.md) classify and group traces.
* Configure [Loop automations](https://docs.braintrust.dev/loop/automations.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.