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

# OTel Collector

> Install and manage the OpenTelemetry collector in your Kubernetes clusters.

Go to **OTel Collector** in the sidebar to manage collectors across all your clusters.

## Collector status

Each cluster card shows a status badge:

| Status            | Meaning                                                          |
| ----------------- | ---------------------------------------------------------------- |
| **Healthy**       | Gateway and node collector pods are running and sending data     |
| **Degraded**      | Collector is running but reporting errors (check the error card) |
| **Installing**    | Helm install is in progress                                      |
| **Error**         | Installation failed or pods crashed                              |
| **Not installed** | No collector deployed to this cluster yet                        |

## Install a collector

1. Open the OTel Collector page.
2. Find the cluster card and click **Install Collector**.
3. Obsy runs `helm install` in the `obsy-system` namespace. The process takes 60–120 seconds.
4. The status badge changes to **Healthy** once all pods are running.

<Note>
  You need at least one observability platform connected (Datadog or Grafana) before installing. The collector config includes your platform's export endpoint and API credentials.
</Note>

## Reinstall / update

If you've changed sampling settings or connected a new platform, click **Reinstall Collector** on the cluster card. Obsy runs a Helm upgrade with the updated config. Active data collection continues during the upgrade (rolling update).

## Collector health card

The **OTel Collector Health** card on the cluster detail shows live metrics read from your observability platform:

| Metric             | What it means                                 |
| ------------------ | --------------------------------------------- |
| **Spans accepted** | Traces received by the gateway per minute     |
| **Spans sent**     | Traces successfully exported to your platform |
| **Failed exports** | Spans dropped due to export errors            |
| **Memory usage**   | Gateway process RSS memory                    |
| **Queue size**     | Number of spans queued waiting for export     |
| **CPU usage**      | Gateway process CPU seconds                   |

If the platform connection is healthy but metrics show zero, ensure the collector has been running for at least 5 minutes and check the exporter config is pointing to the right endpoint.

## Pipeline diagram

The **Your OTel Pipeline** diagram on the OTel Collector page shows the live state of your pipeline — which processors are active, whether custom drop rules are configured, and whether sampling is enabled and at what rate.

## Error messages

If the collector fails to install, an **OTel Collector Error** card appears on the cluster detail with the raw Helm error and a human-readable explanation. Common causes:

| Error                                                                        | Likely cause                                                           |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `cannot install in namespace: already exists`                                | A previous install attempt partially succeeded; click **Reinstall**    |
| `invalid configuration: service::pipelines: must have at least one exporter` | Platform credentials are missing or expired; reconnect in Integrations |
| `pending-upgrade: another operation in progress`                             | A previous upgrade timed out; Obsy auto-recovers on the next sync      |

## Uninstall

To remove the collector from a cluster:

```bash theme={null}
helm uninstall obsy-collector -n obsy-system
kubectl delete namespace obsy-system
```

Obsy does not automatically uninstall when you remove a cluster from the platform.