Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Logs

Every Web Application and Background Worker has a log view: a live stream while the app is running, and a snapshot of the most recent lines when it is not. Reading the log snapshot requires view access; streaming logs live (the dashboard’s live view and paas logs --tail) requires Deploy & operate or Promote & roll back — see Access Control.

In the dashboard

Open your app’s Resource page and go to the Logs tab.

While the app is running, logs stream in live automatically — the footer shows a Live indicator, and the Pause button stops the stream and becomes Stream to resume it. If the stream is interrupted (for example, an instance restarts), it reconnects on its own and continues from the new instance.

The viewer also gives you:

  • Level filter — narrow the view to Errors, Warnings, Info, or Debug. Levels are detected from the text of each line, so they are best-effort.
  • Auto-scroll — the view stays pinned to the newest line. Scroll up to read something older and auto-scroll pauses so new lines don’t pull you back down; the Jump to latest button re-pins it.
  • Line buffer — the live view keeps roughly the last 1,000 lines.
  • Instance filter — when the app runs more than one instance, each line shows which instance wrote it, and the Instance menu narrows the view to one of them (or All instances).

When the app is not running — it crashed, failed to boot, or was stopped — the live stream can’t open. The Logs tab falls back to a snapshot of the last log lines, marked Snapshot — resource not running, which is exactly what you want for a post-mortem.

Snapshot logs with the CLI

paas logs prints a snapshot of recent log lines. Select the app with the usual scope flags:

paas logs -o acme -p shop -e production -a web

Add --json to get the raw API response instead of plain log lines. The remaining examples assume the same -o/-p/-e scope flags.

Live streaming with the CLI

Add --tail to follow logs live:

paas logs -a web --tail

The stream follows every running instance of the app, starting from each one’s last 200 lines, and picks up new instances as they start; once more than one instance has logged, each line is prefixed with [instance]. Pass --instance to follow just one. Combining --tail with --container, -n, or --json is a usage error. Press Ctrl+C to stop.

Viewing one instance

By default the snapshot and the stream show every running instance. To see just one, list the app’s instances first:

paas ps -a web

Then pass an instance name to --instance:

paas logs -a web --instance web-6f7c9d4b8-xkq2n -n 200

-n, --num (default 500) controls how many lines the snapshot returns, and --container narrows it within an instance — most apps never need it. These two work only with snapshots; --instance works with both.

While a build is in progress

Right after a deployment there may be no app logs yet, because your new image is still being built. Instead of failing with a bare “no logs” error, the log stream reports the build state:

  • the build hasn’t started yet,
  • the image is still building,
  • the build failed (with the build’s error message),
  • or the image is built but no instance is running yet (rollout pending).

Once the first instance is running, logs flow as usual. To check build and deploymentment status, use paas releases — it lists the environment’s recent deployments and their states — or the deployment history in the dashboard, which refreshes automatically — see Deployments, Health Checks & Rollback.

To read a finished build’s output, open the deployment in the dashboard (its Logs section), or run paas logs --build 42 (add --release for the release command’s log, -a web when the deployment built several apps). Build logs are kept for the Environment’s last 1,000 deployments.

Next steps