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

# Telemetry and data retention

> Control the telemetry a self-hosted data plane sends to Braintrust's control plane and enable data retention.

These settings control the telemetry your self-hosted data plane sends to Braintrust's control plane, and the service token that enables data retention.

## Enable or disable telemetry

Braintrust can send the following types of telemetry from your self-hosted data plane to Braintrust's control plane:

| Type      | Description                                                                                        |
| --------- | -------------------------------------------------------------------------------------------------- |
| `status`  | Health check information (enabled by default)                                                      |
| `metrics` | System metrics (CPU/memory) and Braintrust-specific metrics like indexing lag (enabled by default) |
| `usage`   | Billing usage telemetry for aggregate usage metrics (enabled by default)                           |
| `memprof` | Memory profiling statistics and heap usage patterns                                                |
| `logs`    | Application logs                                                                                   |
| `traces`  | Distributed tracing data                                                                           |

By default, `status`, `metrics`, and `usage` are enabled. You can change the defaults as follows:

<Note>
  The [Loop runtime](/docs/admin/self-hosting/configure/loop-runtime) always sends `metrics` and `traces` for its own service, in addition to the types you configure here. You can't turn this off while the runtime is enabled. These traces cover the runtime's operation. They don't include LLM calls, tool calls, or the contents of your traces.
</Note>

<Tabs>
  <Tab title="AWS">
    Add the `monitoring_telemetry` variable to your `variables.tf` file, and include the types of telemetry you want to send in the validation condition as a comma-separated list:

    ```bash {19} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    variable "monitoring_telemetry" {
      description = <<-EOT
        The telemetry to send to Braintrust's control plane to monitor your deployment. Should be in the form of comma-separated values.

        Available options:
        - status: Health check information (default)
        - metrics: System metrics (CPU/memory) and Braintrust-specific metrics like indexing lag (default)
        - usage: Billing usage telemetry for aggregate usage metrics
        - memprof: Memory profiling statistics and heap usage patterns
        - logs: Application logs
        - traces: Distributed tracing data
      EOT
      type        = string
      default     = "status,metrics,usage"

      validation {
        condition = var.monitoring_telemetry == "" || alltrue([
          for item in split(",", var.monitoring_telemetry) :
          contains(["metrics", "logs", "traces", "status", "memprof", "usage"], trimspace(item))
        ])
        error_message = "The monitoring_telemetry value must be a comma-separated list containing only: metrics, logs, traces, status, memprof, usage."
      }
    }
    ```
  </Tab>

  <Tab title="GCP / Azure">
    Update the `controlPlaneTelemetry` setting in your Helm `values.yaml` file to include the types of telemetry you want to send:

    ```bash {10} theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    # Global configs
    global:
      orgName: "<your org name on Braintrust>"
      # When createNamespace is true, the namespace will be created and resources will be in global.namespace
      # When createNamespace is false, resources will use .Release.Namespace (the namespace specified during helm install/upgrade)
      createNamespace: false
      namespace: "braintrust"
      namespaceAnnotations: {}
      labels: {}
      controlPlaneTelemetry: "status,metrics,usage,logs,traces,memprof"
    ```
  </Tab>
</Tabs>

Braintrust also has access to endpoints reporting metrics about the backfill and compaction status of Brainstore segments. This is metadata only, no customer data. To disable these endpoints, set the `DISABLE_SYSADMIN_TELEMETRY` environment variable to `true`.

<Warning>
  If you disable telemetry, Braintrust's ability to proactively monitor your deployment and diagnose issues will be significantly limited. Before disabling, consider the impact on support response times.
</Warning>

## Data retention

Data retention requires a [service token](/docs/admin/access-control/manage-permissions#use-service-accounts) so the data plane can query object metadata and look up retention policies configured in your organization.

Braintrust automatically provisions this token when you configure your self-hosted data plane URL in [organization settings](/docs/admin/organizations#configure-api-urls-self-hosted). It is created with read-only permissions on projects and stored securely in your data plane.

To verify or refresh the token, go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="server" /> Service tokens**](https://www.braintrust.dev/app/~/configuration/org/service-tokens). If the token doesn't exist, click **Create**. To rotate it, click **Refresh** — the data plane will start using the new token automatically.

<Note>
  Before configuring retention, review your cloud provider's bucket retention policies. See [Cloud provider retention policies](/docs/admin/data-management/retention#cloud-provider-policies) for details.
</Note>