Cockpit Safety And BEAM Signals

The BeamUp cockpit shows safe operational signals from a managed Erlang-targeted Gleam runtime. It is meant to help you understand production state without exposing private app data or giving remote process-control powers.

Use this tutorial after a successful deploy.

Step 1: Open The App Cockpit

Open the dashboard URL from your invitation, sign in with GitHub, and select an app from /dashboard.

The app cockpit is under:

/dashboard/apps/<app-id>

You do not need another beta code for returning browser login.

Step 2: Identify The Deployment State

At the top of the cockpit, check:

• App URL.
• Active deployment.
• Latest deployment.
• Health state.
• Whether a previous runtime is draining or cleaning up.

This tells you whether the app is serving from the intended deployment and whether a replacement recently happened.

Step 3: Read The Latest Snapshot

The safe runtime snapshot may include:

• Sample time.
• Opaque node label.
• Uptime.
• Process count.
• Total reductions.
• Reductions per second when two consecutive samples from the same runtime prove the rate.
• Total BEAM memory and selected memory buckets.
• Run queue.
• Top mailbox queues by message count.

Use these fields as operating signals, not as full debugging introspection.

Examples:

• Rising process count may indicate workload shape or process churn.
• A high run queue may indicate scheduler pressure.
• A top mailbox queue may point to a bottlenecked process label.
• A missing reductions_per_second value may simply mean the runtime restarted, the counter reset, or BeamUp does not have two compatible samples.

Step 4: Interpret Top Mailbox Queues

Top mailbox entries may include:

• A stable-within-runtime opaque process label.
• A registered name when it passes the safe-name filter.
• Message queue length.
• Reductions.
• Memory estimate.

The label is intentionally limited. Anonymous process labels are stable only for the life of one runtime instance and intentionally change after restart.

Use mailbox queues to decide where to investigate in your application. Do not expect message contents, raw PIDs, distributed-node addresses, or arbitrary process state.

Step 5: Check Snapshot Warnings

If the cockpit shows a snapshot-unavailable warning, treat it as a telemetry warning, not automatic app downtime.

Use these signals together:

• App status.
• Health result.
• Runtime logs.
• Deploy state.
• Snapshot warning.

Sampling can time out or back off without making an otherwise healthy app unhealthy.

Step 6: Understand Cadence And Retention

Managed runtimes sample every 10 seconds. Each in-VM sample has a 500 ms timeout. If sampling times out, BeamUp records a safe warning and backs off to 60 seconds.

Recent samples are retained for 6 hours with a hard cap of 2,160 rows per runtime instance.

BeamUp does not join unrelated runtime series or fabricate rates across runtime restarts.

Step 7: Know The Safety Boundary

The cockpit does not expose:

• Message contents.
• Request bodies, headers, cookies, or user payloads.
• Process dictionaries.
• Stack traces or arbitrary backtraces.
• ETS or Mnesia table names or contents.
• Trace output.
• Process kill, suspend, resume, or other control actions.
• Remote shell, Observer, or arbitrary RPC.
• Erlang cookie values.
• Provider credentials.
• Env values.
• Secret values.

This is intentional. Runtime snapshots are read-only operational samples, not remote Observer.

Step 8: Pair Cockpit Signals With Logs

When the cockpit shows a warning or suspicious signal, fetch logs:

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

For build logs:

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

For a specific runtime deployment:

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

Do not paste private logs, secret values, request payloads, or customer data into public issues or chats.

Step 9: Evaluate Whether The Cockpit Is Useful

After using the cockpit, write down:

• Which signal you looked at first.
• Whether the signal was clear.
• Whether top mailbox queues told you something useful.
• Whether deploy/drain state changed your confidence.
• Whether you wanted an unsafe Observer-style field that BeamUp intentionally hides.
• Whether you would keep this cockpit open while developing or operating the app.
• Whether this cockpit would make BeamUp worth paying for on your real app.

Step 10: What To Do Next

If the app is healthy and the cockpit looks normal, continue using the deploy loop:

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

If a replacement should be reverted:

beamup --app hello-gleam rollback

If you need unsupported capabilities such as message inspection, process control, full Observer, clustering, or hot code upgrades, record that as private beta feedback. Those capabilities are not part of SLC v1.

For reference details, see Runtime Cockpit and Supported Apps And Limitations.