# Observability Overview

> How logs, metrics, traces, and Grafana fit together on Watasu.

Watasu's observability is one Grafana per app, fed by three signals: **logs**, **metrics**, and **traces**. You attach the signals you want; Grafana shows up automatically the first time you do.

## The four pieces

| Add-on  | What it gives you                                     | Read more                                                  |
| ------- | ----------------------------------------------------- | ---------------------------------------------------------- |
| Logs    | Centralized log collection, queryable in Grafana      | [Logs](https://docs.watasu.io/observability/logs.md)       |
| Metrics | Prometheus-style metrics scrape + queries + alerts    | [Metrics](https://docs.watasu.io/observability/metrics.md) |
| Traces  | Distributed tracing for request paths across services | [Traces](https://docs.watasu.io/observability/traces.md)   |
| Grafana | The shell — dashboards, exploration, alerting UI      | This page                                                  |

## Grafana shows up automatically

You don't provision Grafana separately. The first time you attach a logs, metrics, or traces add-on to an app, Watasu creates a Grafana workspace for that app and wires the signal up as a data source.

That means a typical first observability step is:

```bash
watasu addons:create logs --app my-app
watasu addons:create metrics --app my-app
watasu addons:create traces --app my-app
```

After the first one, Grafana exists. Each subsequent one adds a data source.

## Persistence

Grafana is persistent. Dashboards, folders, alert rules, and saved explorations survive across restarts and releases. You don't lose them by redeploying.

The Grafana workspace also **persists when you remove all the observability data add-ons**. If you deprovision Logs, Metrics, and Traces, the Grafana workspace stays around (with its dashboards intact) until you explicitly remove it. That's deliberate — your dashboards aren't tied to a specific signal's lifecycle. To remove Grafana, deprovision it explicitly via the dashboard or CLI after the data add-ons are gone.

## Dashboards from your repository

Commit exported Grafana dashboard JSON under `.watasu/dashboards` and Watasu
will keep it synchronized with the app's Grafana workspace after every
successful release:

```text
.watasu/
└── dashboards/
    ├── overview.json
    └── api/
        └── latency.json
```

Subdirectories become Grafana folders, so `api/latency.json` is placed in the
`api` folder. Every file must be a JSON object with a non-empty `title` and a
stable `uid` containing 1-40 letters, numbers, dashes, or underscores. The
limits are 128 dashboards, 750 KB per file, and 5 MB for the complete bundle.

There is no configuration file or per-environment switch. Repository dashboards
are active whenever that app or review app already has Grafana. Dashboard files
do not provision Grafana by themselves: if the app has no Grafana workspace,
the release still succeeds and nothing is created. If Grafana is attached
later, Watasu applies the dashboards from the current release.

Removing a JSON file removes the repository-managed dashboard on the next
successful release. Dashboards you created manually with other UIDs are left
alone. Watasu keeps old repository-created folders instead of deleting them,
because they may contain dashboards you created manually.

Use these datasource placeholders in exported dashboards instead of pinning a
workspace-specific datasource UID:

| Placeholder              | Grafana datasource    |
| ------------------------ | --------------------- |
| `$watasu.metrics`        | Metrics               |
| `$watasu.runtime`        | Watasu Runtime        |
| `$watasu.object.storage` | Watasu Object Storage |
| `$watasu.logs`           | Logs                  |
| `$watasu.traces`         | Traces                |

Watasu rewrites the placeholders to Grafana inputs and binds any available
matching datasource when it reconciles the dashboard.

## Access

Access to an app's Grafana follows access to the app. People who can read the app can read the dashboards; people who can operate the app can edit dashboards and alerts.

## When to use what

Each signal answers a different kind of question:

* **Logs** — what did the app actually print?
* **Metrics** — how much, how often, how fast, over time?
* **Traces** — where did this single slow request spend its time?

Most incidents touch all three: the alert fires from a metric, you check logs to see what's failing, and you pull a trace to see where the slowness is.

## App logs vs. Grafana logs

There are two log surfaces and they're for different jobs:

|             | `watasu logs`                    | Grafana logs                         |
| ----------- | -------------------------------- | ------------------------------------ |
| Latency     | Live tail                        | Indexed and queryable                |
| Time window | Recent                           | Long retention                       |
| Filtering   | Process                          | Labels, structured fields, full-text |
| Best for    | Active debugging during a deploy | Historical search and dashboards     |

Use `watasu logs` for "I just pushed and something's wrong." Use Grafana for "what was happening Tuesday at 3am?"

[View this page on the web](https://docs.watasu.io/observability/overview/)