Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 37 ยท Operations and Alternatives

Logging, Drains and Log Parsing

Understand Heroku's Logplex stream, read logs with heroku logs, send them to a log drain, write structured logfmt lines and count errors with a small parser.

On Heroku, an app does not write log files. Dyno disks are temporary, and many dynos run at once, so files would be scattered and lost. Instead every process writes to standard output and standard error, and Heroku's log router, Logplex, collects those streams together with platform logs (router lines, dyno state changes, build output) into one time-ordered stream. This is a core twelve-factor idea: treat logs as an event stream.

Logs cannot be fetched on this site, so commands are read-only and the sample lines are invented. The parser is a runnable stand-in.

Reading logs

Terminal
heroku logs --tail --app my-app
heroku logs --num 500 --app my-app
heroku logs --source app --dyno web.1 --app my-app
heroku logs --source heroku --app my-app

Each line starts with a timestamp, then a source and process (app[web.1], heroku[router], heroku[web.1]), then the message:

TEXT
2026-03-02T09:14:07.512345+00:00 app[web.1]: Started GET "/" for 203.0.113.7
2026-03-02T09:14:07.560111+00:00 heroku[router]: at=info method=GET path="/" dyno=web.1 connect=0ms service=47ms status=200

--source app shows only your code's output, --source heroku only the platform. Logplex keeps only a short buffer (about 1,500 lines) for a limited time; it is not an archive. For history, search and alerts you need a drain.

Log drains

A drain sends the whole stream, as it happens, to another service over syslog (HTTPS or TCP). Many logging add-ons (Papertrail, Better Stack, Datadog and others) set one up for you, or you can point a drain at your own endpoint:

Terminal
heroku drains --app my-app
heroku drains:add https://logs.example.com/ingest --app my-app
heroku drains:remove https://logs.example.com/ingest --app my-app

Choose a drain target by what you need: full-text search, retention time, alert rules, and the cost per gigabyte. Note that a busy app can produce a lot of logs, especially with per-request lines, so set sensible log levels in production.

flowchart LR
    A["Your processes<br/>stdout / stderr"] --> L["Logplex"]
    R["Router and platform"] --> L
    L --> T["heroku logs --tail"]
    L --> D["Log drain"]
    D --> S["Search, dashboards, alerts"]

Everything flows through Logplex; drains give you history and alerts.

Write logs for machines and humans

Plain sentences are fine for a handful of lines, but a search tool works far better with structured logs: key-value pairs (logfmt) or JSON lines. Include the request id so you can follow one request across lines.

TEXT
level=error msg="payment failed" request_id=8601b555 user_id=42 provider=acme code=card_declined

Rules of thumb:

  • One event per line. Stack traces are the exception; many tools join them.
  • Stable keys (user_id, not sometimes uid).
  • Never log passwords, tokens, full card numbers or other personal data. Logs are copied to third parties and retained for months.
  • Log at info in production and raise to debug temporarily through a config var (heroku config:set LOG_LEVEL=debug; changing a config var restarts dynos).
  • Make sure output is unbuffered: Python needs PYTHONUNBUFFERED=1 (the Python buildpack sets it), otherwise lines can appear late or be lost on a crash.
Python Stand-in: emit and parse logfmt

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.

The output counts 3 errors of 5 events and breaks them down as card_declined twice and timeout once. A drain service does exactly this kind of grouping, at scale.

Alerts and what to watch

A useful minimum for production:

  • Rate of 5xx responses (the router status=5xx lines, and H/R error codes).
  • Error-level application logs, grouped by message.
  • Slow requests: service over a threshold.
  • Dyno restarts and crashes (heroku[web.1]: State changed from up to crashed).
  • A heartbeat or uptime check from outside, so you notice when the whole app is down.

Pair logs with an error tracker (Sentry, Honeybadger, Rollbar and similar) that groups exceptions and tells you which release introduced them. Heroku also shows a Metrics tab and can add runtime metrics into the log stream with heroku labs:enable log-runtime-metrics, see router metrics.

Python Stand-in: 5xx rate alert

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.

Only the window that contains the burst of 503 responses crosses the 5 percent threshold. A real alert also needs a minimum number of requests, so a quiet night does not trigger false alarms.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where should a Heroku app write its logs?

    The dyno filesystem is temporary; Logplex collects stdout and stderr from every process.
  2. 2. Why are heroku logs not enough for long-term history?

    Logplex keeps a short buffer; use a drain for retention, search and alerts.
  3. 3. What is a benefit of structured logs?

    Key-value or JSON fields let log tools search and aggregate reliably.
  4. 4. Which command adds a log drain?

    heroku drains:add sends the log stream to the given syslog endpoint.

Summary

  • Apps log to stdout/stderr; Logplex merges app, router and platform logs.
  • heroku logs --tail, --source and --dyno read recent lines; drains keep history.
  • Prefer structured logfmt or JSON with request ids; never log secrets.
  • Alert on 5xx rate, error logs, slow requests and crashes.

Next: Security, Teams and Access