Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Getting Started

CLI Essentials and Reading Logs

Learn the Heroku CLI commands you will use every day, how Heroku's log stream is formatted, how to filter it, and how to read router lines to debug slow or failing requests.

Once an app is deployed, most of your Heroku work is asking questions: Is it running? What did it just log? What settings does it have? A handful of CLI commands answers almost all of them. This lesson is your cheat sheet, followed by a closer look at the log stream, which is the single most useful debugging tool the platform gives you.

The commands you will use daily

Every command below accepts -a APP (or -r REMOTE) when you are not inside the app's repository.

Command What it does
heroku apps Lists the apps you own or collaborate on
heroku info Shows the app's name, stack, region, web URL, Git URL and owner
heroku ps Lists dynos and their state (up, starting, crashed, idle)
heroku ps:restart Restarts all dynos (or one: heroku ps:restart web.1)
heroku logs --tail Streams logs live
heroku run COMMAND Runs a one-off dyno with the app's code and config, e.g. heroku run node -v
heroku run bash Opens an interactive shell in a temporary dyno
heroku config Lists config vars (see config vars)
heroku releases Lists releases, newest first
heroku open Opens the app's URL in a browser
heroku maintenance:on / :off Shows a maintenance page to visitors
heroku addons Lists add-ons attached to the app
heroku apps:rename NEWNAME Renames the app (the old URL stops working)
heroku help COMMAND Shows usage and flags for any command

Two habits make the CLI friendlier. First, many commands support --json, which prints machine-readable output you can pipe into other tools. Second, heroku help and heroku COMMAND --help are always up to date with your installed version, so when a flag in a blog post does not work, trust the built-in help.

Be careful with destructive commands. heroku apps:destroy deletes the app, its releases and its add-ons' data. The CLI makes you retype the app name to confirm. Never paste a destroy command with --confirm into a script unless you are certain which app it targets.

One-off dynos

heroku run does not run on your web dyno. It starts a separate, temporary dyno using the latest release, runs your command, streams the output back, and throws the dyno away. That is why it is perfect for database migrations, data imports and quick investigations, and why files you create there vanish. One-off dynos are billed for the time they run like any other dyno.

CONSOLE
$ heroku run python manage.py migrate
$ heroku run:detached node scripts/rebuild-index.js

run:detached starts the job without attaching your terminal, and you read its output with heroku logs --dyno run.1234 (the dyno name is printed when it starts).

How the log stream is built

Heroku does not store your logs forever; it keeps a limited recent buffer (around the latest 1,500 lines for heroku logs), and anything older is gone unless you send logs to an external service (see add-ons and the operations chapters). The stream interleaves lines from several sources:

  • app[web.1]: your code's output (stdout and stderr).
  • heroku[web.1]: the platform's own messages about that dyno (starting, state changes, errors).
  • heroku[router]: one line for each HTTP request the router handled.
  • heroku[api] and heroku[slug-compiler]: deploys, config changes and slug compilation.

Each line starts with an ISO timestamp, then the source and dyno, then the message:

TEXT
2025-03-04T10:15:22.431921+00:00 app[web.1]: Listening on 41873
2025-03-04T10:15:25.007712+00:00 heroku[router]: at=info method=GET path="/" host=demo-shop.herokuapp.com request_id=8e1f dyno=web.1 connect=0ms service=12ms status=200 bytes=1420 protocol=https

The router line is a key=value record. The fields you will lean on most are status (the HTTP status), service (milliseconds your app took), connect (time to reach the dyno) and dyno (which one answered). Errors have a different shape: at=error code=H12 desc="Request timeout" tells you the router gave up on a request.

Filtering

Logs get noisy fast. Narrow them down with flags:

CONSOLE
$ heroku logs --tail --source app
$ heroku logs --dyno web.1 -n 200
$ heroku logs --source heroku --ps router

--source app shows only your code's output, --dyno shows a single dyno, -n sets the number of lines to fetch, and --ps filters by process name. For anything more elaborate, pipe the output through grep or send the stream to a search tool.

Stand-in: parse router lines

The program below is a stand-in log analyzer. It parses the router's key=value format and reports slow or failing requests, the kind of check you might run on exported logs. The sample lines are made up for practice.

Python Stand-in: summarize router log lines

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Real Heroku accounts often see the same pattern: a spike of slow service times and then H12 timeouts, which points to a handler that needs to move to a worker.

Stand-in: building a command from options

Typing long commands from memory invites typos. This tiny builder shows how the flags combine, and gives you a model to extend into your own shell aliases.

Python Stand-in: assemble a heroku logs command

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where does a command run when you use heroku run?

    heroku run starts a temporary dyno from the latest release. Files written there disappear when it ends.
  2. 2. Which log source shows one line per HTTP request?

    The router logs a key=value line for every request it handles, including status and service time.
  3. 3. What does the router error code H12 mean?

    H12 is a request timeout: the app did not answer in time (about 30 seconds to the first byte).
  4. 4. How do you see only your own application's output while following logs?

    --source app filters out platform lines and router lines.
  5. 5. Why are logs not a permanent archive on Heroku?

    Heroku keeps a limited recent buffer. For history, use a logging add-on or a log drain.

Summary

  • heroku ps, logs --tail, run, config, releases and info answer most daily questions.
  • heroku run uses a temporary one-off dyno, ideal for migrations and one-time scripts.
  • The log stream mixes app, platform and router lines; router lines carry status and timing as key=value pairs.
  • Filter with --source, --dyno and -n, and drain logs elsewhere if you need history.

Next: Dynos and dyno types