# Logs and Releases

> Use logs and the release timeline to debug deploys and runtime behavior.

When an app misbehaves, two questions answer most of it:

1. **What release is live?** — because that tells you what changed.
2. **What do the logs say?** — because that tells you what's failing now.

## Releases

Every deploy creates a new release. Every config var change creates a new release. A release ties together:

* the built image
* the active process formation
* the effective config (your vars + add-on-injected vars)
* the set of attached add-ons

That makes releases the right unit for "when did this start failing?" — you can almost always pin a regression to a specific release boundary.

## Streaming logs

```bash
watasu logs --app my-app
```

This tails recent app output across all processes. It's the fastest way to see a deploy fail, a worker crash, or a boot error.

Use `watasu logs` for the immediate-feedback case. For broader exploration — wider time windows, structured filters, correlations across signals — use Grafana logs (see [Observability → Logs](https://docs.watasu.io/observability/logs.md)).

## Reading a deploy failure

When a deploy fails, the build and release output streams to your terminal during `git push watasu main`. If you missed it, `watasu logs` will catch the post-build symptoms.

The most common patterns:

| Symptom                                | Likely cause                                                         |
| -------------------------------------- | -------------------------------------------------------------------- |
| Build fails immediately                | Buildpack didn't detect your app, or `Dockerfile` syntax error       |
| Build succeeds, release fails          | `release` process failed — usually a migration                       |
| Release succeeds, app crashes on start | Missing config var, failed dependency, or app didn't bind to `$PORT` |
| App boots but returns 503              | Wrong process name, app bound to `127.0.0.1` instead of `0.0.0.0`    |

For a longer list, see [Troubleshooting → Common Issues](https://docs.watasu.io/troubleshooting/common-issues.md).

## A debugging sequence that works

When you're not sure what broke:

1. Tail logs: `watasu logs --app my-app`
2. Confirm the formation: `watasu pods --app my-app` — is everything actually scaled?
3. Confirm config: `watasu config --app my-app` — is the var you expect actually set?
4. Confirm add-ons: `watasu addons --app my-app` — is everything ready?

If the failure pattern lines up with a deploy you just made, the answer is usually in the diff of that release.

## Where else logs live

`watasu logs` is the app log stream. For everything else there's the observability stack:

* **Grafana logs** — search and filter across longer time windows
* **Metrics** — pod CPU/memory, restarts, OOMKills, queue depth, request latency
* **Traces** — request paths across services and add-ons

See [Observability Overview](https://docs.watasu.io/observability/overview.md) for how the four signals fit together.

[View this page on the web](https://docs.watasu.io/apps/logs-and-releases/)