Observability Overview

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
Metrics	Prometheus-style metrics scrape + queries + alerts	Metrics
Traces	Distributed tracing for request paths across services	Traces
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:

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:

.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?”