Logs And Debugging

BeamUp stores recent owner-scoped build logs and runtime stdout/stderr logs. Logs are private app data and may contain application output, so review them before sharing.

Runtime Logs

Fetch recent runtime logs once:

beamup --app hello-gleam logs --no-follow

Follow runtime logs:

beamup --app hello-gleam logs

When stdout and stderr are attached to a terminal, follow mode opens the TUI. In non-TTY plain output, follow mode polls every 500 ms.

Fetch runtime logs for a specific deployment:

beamup --app hello-gleam logs --deployment <deployment-id> --no-follow

JSON performs one fetch and never opens the TUI:

beamup --json --app hello-gleam logs --no-follow

Runtime logs require --app; they do not infer the app from beamup.toml.

Build Logs

Fetch build logs:

beamup --app hello-gleam logs --build --deployment <deployment-id> --no-follow

Build logs require both --app and --deployment.

beamup deploy prints the build-log command for the deployment it created.

Retention And Pagination

Runtime logs are retained for seven days or 10,000 entries per deployment, whichever boundary is reached first. SLC v1 does not promise unlimited runtime log retention or archive older runtime logs.

Runtime log API responses default to 200 entries and cap at 500. CLI output shows explicit boundaries when more retained entries exist or older logs expired. Unknown or expired cursors fail with log_cursor_expired; BeamUp does not silently restart from recent logs and hide the gap.

Build-log reads default to 200 entries and cap at 500.

Truncation

BeamUp never presents truncated logs as complete.

Runtime log event rules:

• Per-entry stored message limit: 64 KiB.
• Larger complete events keep a bounded prefix and suffix with an inline BeamUp truncation marker.
• Per-stream collector read limit: 1 MiB per 500 ms worker pass.
• If an event crosses that read boundary, output marks stream_read_limit and continues from the stored byte cursor on the next pass.

Plain runtime log output prints a marker such as:

<timestamp> stdout [BeamUp: truncated entry_size; original event size: <bytes> bytes]

or:

<timestamp> stderr [BeamUp: truncated stream_read_limit; original event size unavailable]

Multiline OTP And SASL Output

BeamUp stores runtime stdout/stderr as newline-delimited stream entries. This keeps multiline Erlang/OTP and SASL reports readable in order. Exact OS write interleaving across separate stdout and stderr file descriptors is not claimed.

Crash Artifacts

Raw erl_crash.dump downloads are not supported in SLC v1. Unexpected root erl_crash.dump files are deleted by the collector without reading or indexing them. They are not mixed into logs, analytics, build caches, or public artifacts.

Failure Categories

Known deployment failures include:

• missing_gleam_toml: run from a Gleam project root or fix app_root.
• unsupported_target: use an Erlang-targeted Gleam project.
• invalid_config: fix the named beamup.toml field.
• compile_failure: read build logs and fix Gleam compiler errors.
• dependency_or_toolchain_failure: inspect build logs and retry if local supported-toolchain builds succeed.
• missing_env_var: set the required key with beamup env set or beamup env set --secret, then redeploy.
• port_binding_failure: bind to the provided PORT on 0.0.0.0.
• startup_failure: inspect runtime logs and fix the app startup path.
• health_check_failure: make the configured health path return HTTP 2xx.
• unknown_error: keep the request ID for support and inspect linked logs.