Elixir / BEAM runtime

v0.1.12

Diagnostics for Elixir and Erlang/BEAM applications on the runner host or inside Docker containers: toolchain versions, EPMD registrations, BEAM OS process state, Linux /proc memory and process-tree detail, release RPC snapshots, supervisor/process/ETS/allocator/scheduler/port introspection, binary-leak checks, and bounded recon_trace call tracing. Releases are discovered from running BEAM processes; target one by release name, or by container for a release inside Docker.

24 allowed by default 1 need approval by default

Pack ID

elixir-beam

Vendor

emisar

linux

Actions

Required binaries. Install these on the host before relying on the pack. An action that calls a missing binary fails at run time.

erl


              elixir


              epmd


              bash

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below before copying it into the runner's packs dir. That hash covers the exact bytes this page was built from, so a tampered copy is rejected. The command reloads a running daemon itself, so you don't need to restart it manually.

on the runner host

sudo emisar pack install elixir-beam --hash sha256:1420c774fe72267bfb1e1ed1529be8525c3c88655116a23a8b877ebddbcfeaa0

Setup

Inspects Elixir/Erlang runtime state on the runner host and inside Docker containers. No node cookies or application credentials are needed: release actions go through the release's own bin/RELEASE_NAME control script, discovered from the running BEAM process (start with beam.release_targets).

Environment

Set these on the runner host, then add each name to execution.inherit_env so the value reaches the action.

ELIXIR_RELEASE_CTL

Optional override pinning the release control script path, for example /opt/my_app/bin/my_app (with a container argument, the path inside the container). Only needed when discovery cannot see the release; add it to the runner's inherit_env . The release/container action arguments take precedence.

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Inspect protected process state owned by another user.

beam.process_statusbeam.process_limitsbeam.process_memorybeam.process_tree

Grant process-inspection capabilities to the Emisar service

Grant access

sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
sudo rm -f /etc/systemd/system/emisar.service.d/10-elixir-beam-host-access.conf
printf '%s\n' '[Service]' 'AmbientCapabilities=CAP_SYS_PTRACE CAP_DAC_READ_SEARCH' | sudo tee /etc/systemd/system/emisar.service.d/20-elixir-beam-process-inspection.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar

Verify access

systemctl show emisar --property=AmbientCapabilities --value | grep -Fwi cap_sys_ptrace
systemctl show emisar --property=AmbientCapabilities --value | grep -Fwi cap_dac_read_search

Impact: Every Emisar action on this runner can inspect, attach to, and modify processes outside the runner user, and bypass host file read and directory search permissions.

Reach another user's host release control files or the Docker daemon for a containerized release.

beam.release_targetsbeam.release_pidbeam.release_runtimebeam.release_memorybeam.release_applicationsbeam.release_debug_toolsbeam.release_registeredbeam.release_top_processesbeam.release_process_infobeam.release_supervisor_treebeam.release_ets_tablesbeam.release_allocatorsbeam.release_binary_leakbeam.release_scheduler_usagebeam.release_portsbeam.recon_trace_callsbeam.recon_trace_clear

Run the Emisar service as root for host releases

Grant access

sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
sudo rm -f /etc/systemd/system/emisar.service.d/10-elixir-beam-host-access.conf
printf '%s\n' '[Service]' 'User=root' 'Group=root' | sudo tee /etc/systemd/system/emisar.service.d/30-elixir-beam-host-release.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar

Verify access

test "$(systemctl show emisar --property=User --value)" = root

Impact: Every Emisar action on this runner executes as root and can read or change any host file, process, secret, and kernel or service state. Release RPC can inspect and change the selected application's runtime state.

Add the Emisar service user to the docker group for containerized releases

Grant access

sudo rm -f /etc/systemd/system/emisar.service.d/10-elixir-beam-host-access.conf
sudo rm -f /etc/systemd/system/emisar.service.d/30-elixir-beam-host-release.conf
sudo systemctl daemon-reload
sudo usermod -aG docker emisar
sudo systemctl restart emisar

Verify access

test "$(systemctl show emisar --property=User --value)" = emisar
id -nG emisar | tr ' ' '\n' | grep -Fx docker
sudo -u emisar docker info >/dev/null

Impact: Every process running as emisar can control Docker. Docker socket access is effectively root-equivalent because containers can mount and write the host.

Notes

Release actions discover running releases from BEAM process command lines and only ever execute <release_root>/bin/<release_name> of a release that is already running — callers select among live releases but cannot point actions at arbitrary binaries.
When several releases run on one target, pass the release argument (names come from beam.release_targets). For a release inside Docker, pass the container argument.
For a host release, or a runner that diagnoses both host and rootful-Docker releases, apply only the root host-release recipe. For a container-only runner, apply only the Docker-socket recipe; it removes this pack's root override and restores the service's configured emisar user.
Release RPC actions execute fixed, pack-authored expressions only; callers cannot supply arbitrary Elixir code.
If the release control script evaluates runtime config during rpc, the runner service must inherit the same runtime env the release script needs, or those actions will fail before connecting. With the container argument this usually just works: docker exec runs with the container's configured environment.
beam.release_pid reports the PID inside the container's namespace when container is set, not the host PID (find the host PID with beam.processes).
The recon-powered actions (allocators, binary_leak, scheduler_usage, recon_trace) need recon compiled into the release and fail with a clear message otherwise; check with beam.release_debug_tools. The recon_trace action is high-risk because tracing adds runtime overhead and can expose function arguments or return values when explicitly enabled.
There is deliberately no action launching the interactive observer_cli TUI; its dashboards are covered by the release_* snapshot actions (top_processes, ets_tables, allocators, scheduler_usage, ports, memory).

Verify it works

Runs beam.release_targets, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host

sudo emisar pack verify elixir-beam

Install and configure a pack walks through the whole sequence on a host.

Actions 25 total

View on GitHub

beam.elixir_version exec low

elixir --version

Show the installed Elixir and Erlang/OTP versions.
View source on GitHub
beam.epmd_names exec low

epmd -names

List Erlang nodes registered with the local EPMD daemon.
View source on GitHub
beam.erl_system_version exec low

Erlang/OTP system version

Show the installed Erlang/OTP system version.
View source on GitHub
beam.process_limits exec low

BEAM process limits

Show Linux resource limits for a BEAM process.
View source on GitHub
beam.process_memory script low

BEAM process memory summary

Show Linux /proc memory, fd, thread, and mapping counts for a BEAM process.
View source on GitHub
beam.process_status exec low

BEAM /proc status summary

Show selected /proc/PID/status fields for a BEAM process.
View source on GitHub
beam.process_tree script low

BEAM process tree

Show ancestors and descendants for a BEAM OS process without command-line arguments.
View source on GitHub
beam.processes exec low

BEAM process list

List BEAM and Elixir OS processes on the runner host.
View source on GitHub
beam.recon_trace_calls script high

Bounded recon_trace call capture

Trace calls to one existing module/function in the running Elixir release for a bounded time window; tracing adds load while active, and the include_args / include_return flags copy raw arguments and returns — routinely secret-bearing — into the recorded output.
View source on GitHub
beam.recon_trace_clear script medium

Clear recon_trace tracing

Stop all recon_trace tracing in the running Elixir release.
View source on GitHub
beam.release_allocators script low

Elixir release memory allocators

Show BEAM memory allocator utilization for the running Elixir release with recon_alloc — allocated vs used bytes, the usage ratio, and a per-allocator breakdown for fragmentation analysis. Requires recon in the release (check with beam.release_debug_tools).
View source on GitHub
beam.release_applications script low

Elixir release applications

List started OTP applications in the running Elixir release.
View source on GitHub
beam.release_binary_leak script medium

Elixir release binary leak check

Check the running Elixir release for refc binary leaks with recon bin_leak — garbage-collects every process and reports which freed the most binary references. Requires recon in the release (check with beam.release_debug_tools).
View source on GitHub
beam.release_debug_tools script low

Elixir release debug tools

Check whether recon, recon_trace, and observer_cli modules are available in the running release.
View source on GitHub
beam.release_ets_tables script low

Elixir release ETS tables

List ETS tables in the running Elixir release sorted by memory or row count, with owner, type, and a total-usage summary.
View source on GitHub
beam.release_memory script low

Elixir release memory snapshot

Show BEAM memory categories and core counts from the running Elixir release.
View source on GitHub
beam.release_pid script low

Elixir release OS PID

Show the OS PID of the running Elixir release (the PID inside the container's namespace when container is set).
View source on GitHub
beam.release_ports script low

Elixir release BEAM ports

Count open BEAM ports in the running Elixir release by driver, with the port limit — spot socket or port leaks at a glance.
View source on GitHub
beam.release_process_info script low

Elixir release process info

Show selected process_info fields for one BEAM PID in the running release.
View source on GitHub
beam.release_registered script low

Elixir release registered processes

List registered processes in the running Elixir release with lightweight process info.
View source on GitHub
beam.release_runtime script low

Elixir release runtime snapshot

Show a BEAM runtime snapshot from the running Elixir release.
View source on GitHub
beam.release_scheduler_usage script low

Elixir release scheduler usage

Show per-scheduler utilization of the running Elixir release sampled over a bounded window with recon scheduler_usage — the accurate BEAM CPU picture, unlike OS-level CPU of busy-waiting schedulers. Requires recon in the release (check with beam.release_debug_tools).
View source on GitHub
beam.release_supervisor_tree script low

Elixir release supervisor tree

Show a bounded supervisor subtree from the running Elixir release.
View source on GitHub
beam.release_targets script low

Debuggable Elixir releases

List running Elixir releases on the runner host and inside running Docker containers, with the release and container values to pass to the other beam.release_* actions.
View source on GitHub
beam.release_top_processes script low

Elixir release top BEAM processes

List top BEAM processes in the running release by memory, mailbox length, reductions, or heap size.
View source on GitHub

← Back to registry

Pack reference Publish your own