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

# Manage Install Telemetry

> Enable or disable install telemetry and choose your organization default.

Choose which customer installs send application logs, metrics, and traces to your observability backend.
Before enabling collection for the first time, complete the [BYOC telemetry setup](/guides/byoc/telemetry.md).

Telemetry is disabled by default at the org level. You can change that default and override it for individual
installs. Existing and new installs without an override follow the current org default.

## Set the org default

As an **org admin**, open the profile menu in your Nuon BYOC dashboard. Under **Org settings**, select
**Manage telemetry**, change **Enable telemetry by default**, and select **Save settings**.

![Manage telemetry modal for Acme, showing Enable telemetry by default turned on and the Save settings button](https://mintcdn.com/nuoninc/VjHGD7J9AKXb1ZNp/images/guides/install-telemetry/org-default.png?fit=max\&auto=format\&n=VjHGD7J9AKXb1ZNp\&q=85\&s=edf3d852120af00717bd271a6bb7a7f5)

Manage the telemetry default for installs without an override.

Install-specific overrides stay unchanged, so turning off the org default does not disable installs explicitly
set to enabled.

## Enable or disable an install

**Using Nuon Dashboard**

1. Open the install and select **Settings**.
2. Under **Configuration**, find **Telemetry** and select **Manage telemetry**.
3. Set **Telemetry forwarding** to **On**, **Off**, or **Use org default (On/Off)**, then select **Save settings**.

The card shows the effective forwarding policy and whether it comes from the org default or an install override.
The modal also shows collector access, issued credential metadata for org admins, app-declared collector
configuration, and runner-specific prerequisites. These are configuration details, not delivery health.

The stack provisioning step's **Application telemetry (optional)** section opens the same modal. Its settings
describe the current install, not the historical stack version. **Runner telemetry export (optional)** is separate:
it exports runner audit logs and telemetry using a cloud secret, not an application collector bootstrap Secret.

If forwarding is managed by an install config file, its policy control is read-only. Change and sync the install
config instead. Credential lifecycle actions remain separate from forwarding policy.

**Using Install Config Files**

Add this section to the [install config](/guides/install-configs.md) and sync your changes:

```toml install.toml theme={null}
[telemetry]
enabled = true
```

Set `enabled = false` to disable telemetry for that install, even when the org default is enabled.
For a new install that should follow the org default, leave out the telemetry section.

> [!NOTE]
>
> Removing `[telemetry]` or `enabled` from an existing install config preserves its current setting; it does not
> restore the org default.

Collectors apply settings on their next refresh, without restarting the runner. An in-cluster collector refreshes
settings and renews relay access directly with the Nuon control plane, even while the runner is stopped. A
runner-bound collector cannot forward data while its runner is down. Already-issued relay credentials can remain
valid for up to ten minutes after forwarding is disabled or collector access is revoked.

If your app template uses a [toggleable component](/guides/toggleable-components.md) to collect telemetry, that component must
also be enabled. The install telemetry setting controls forwarding, not component deployment.

## Set up an optional in-cluster collector

Use an in-cluster collector to keep collecting application telemetry while the install runner is stopped.

### Configure the app

1. Add Nuon's
   [telemetry-agent Helm chart](https://github.com/nuonco/charts/tree/main/charts/telemetry-agent) as an optional
   app component. Set `apiURL` to `{{ .nuon.runner.api_url }}` and `installID` to `{{ .nuon.install.id }}`.

2. Define an optional string [install input](/guides/configuring-inputs-and-secrets.md#inputs) with
   `sensitive = true` and pass its value to the chart's `bootstrapToken` value.

3. Add this label to exactly one collector component so the dashboard can find it:

   ```toml theme={null}
   [labels]
   "nuon.co/telemetry-collector" = "true"
   ```

4. Commit and push to the git branch your [app branch](/guides/app-branches.md) tracks to publish the app config.

### Enable an install

1. As an org admin, open **Manage telemetry → In-cluster collector (optional)** and select
   **Create bootstrap credential**. The default expiry is one year.
2. Save the one-time token in the collector's sensitive install input. For config-managed installs, update
   the input in the [install config](/guides/install-configs.md) and sync it. Do not commit the token.
3. With the runner online, enable the collector component and roll out the updated install configuration.
4. Route application OTLP exporters to the collector's cluster-local endpoint using your app config.
5. Set **Telemetry forwarding** to **On** (or inherit an enabled org default) and verify fresh data in your
   backend before stopping the runner.

### Rotate or remove collector access

1. Before expiry, select **Create bootstrap credential** to issue a replacement.
2. Update the same sensitive install input, sync if config-managed, and roll out the collector with the runner online.
3. Verify collection, then select **Revoke credential** for the old token.

To remove access entirely, select **Remove collector access**. This revokes all collector credentials and removes
the managed Nuon account; it does not uninstall the component or change forwarding policy.

## Check collection

Generate some application activity and look for recent data in your backend, filtered by the install's
`nuon.install.id` resource attribute. The dashboard shows configured forwarding and setup metadata, not delivery health.

For the complete set of identity attributes and delivery behavior, see
[Install Telemetry](/concepts/install-telemetry.md).

## Stop collection

Set forwarding to **Off** using either method above. Stop or reconfigure application exporters too, so they do not
keep sending to an unavailable collector. Disabling forwarding keeps collector access, deployment, private ingress,
and queue storage in place; it does not delete data already stored in the backend.

Before shutting down the central relay, disable telemetry on the installs using it, including any explicit
overrides. Then coordinate with Nuon to disable the relay. For backend credential rotation, see
[the setup guide](/guides/byoc/telemetry.md#change-your-backend-or-rotate-credentials).

## Troubleshooting

### I cannot change the install setting

If the modal says **Managed by install config**, edit and sync the install config. Otherwise, retry failed settings
reads or check install permissions. A missing runner or private endpoint does not block saving forwarding policy.
For runner-bound collection only, update the stack or re-enable its ingress using the
[setup guide](/guides/byoc/telemetry.md#3-check-the-install-endpoint). In-cluster collection does not need that ingress.

### Telemetry is enabled, but no data appears

First identify the collection path. For the runner path, check that the runner is active and the exporter uses the
install's private endpoint. For the in-cluster path, check the collector component's deployment and bootstrap
credential expiry; runner availability is not required.
For either path, check that the application is emitting data, allow time for settings refresh and collector startup,
and confirm that Nuon has configured the relay and the backend accepts the intended signals.

For connection timeouts, check network access to the private endpoint. For backend authentication failures, check
the BYOC backend secrets with Nuon; do not add backend credentials to workloads.

### I cannot find the telemetry controls

Use an up-to-date dashboard. Org-level **Manage telemetry** and collector credential actions require an org admin.
Install settings still show setup-required and load-error states when relay configuration is unavailable.

If you need help, send Nuon the install ID, signal type, sample timestamp, and sanitized error details. Do not send
credentials or sensitive telemetry payloads.


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