Skip to main content
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.
Observability templates are in public preview and can change before reaching general availability.
All bt observability subcommands accept the shared bt global flags.

​
bt observability template pull

Pull facets, their Topics automation settings, and Loop automations from a project:
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

​
bt observability template push

Push a template to a project from a local file, a public URL, or stdin:
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

​
Template format

An observability template is a JSON object with a schema version, facets, Topics automation settings, and Loop 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