Spectator

Spectator is a BEAM observer tool written in Gleam, that plays well with gleam_otp processes.

Features

So far, spectator has the following features:

• Show processes in a sortable table
• Tag individual processes for easy identification
• Show process details
• Show OTP process state
• Suspend / resume OTP processes
• List ETS tables
• View content of ETS tables
• List of active ports
• Clickable links between resources
• Dashboard with basic statistics
• Inspect other BEAM nodes

Use Spectator in Development

You can install spectator as a dependency in your project, and run it as part of your application to inspect your app in development.

gleam add spectator

For details on how to do this, see the package README

Use Spectator in Production

You can use spectator to inspect the BEAM node running your deployed application by running spectator as a standalone app, and connecting it to the erlang node your application is running on via distribution.

The standalone spectator application is available as a docker image via ghcr.io/jonasgruenwald/spectator, and as an escript via the releases page.

The repo contains a full example of how to use spectator to inspect an app deployed via docker.

First, ensure your application has an Erlang name and cookie set, for example by setting the ERL_FLAGS environment variable before your application is started:

ERL_FLAGS="-sname myapp -setcookie mycookie"

If your application is running in a docker container, put both your applications container, and the container running spectator on the same docker network, and ensure that your applications container has its hostname set to a value you know.

Start spectator, and click ‘Change Target’ in the top right corner of the application.

Enter the details of the node you wish to inspect, the name should be the name you set via -sname, followed by @, and then the hostname.

Finally, click ‘Connect’, to inspect the your application node.

Please note that all connection information, including the cookie, is stored plainly in the URL query parameters of the spectator application.

Considerations

Please be aware of the following implications of running spectator:

• Spectator may slow down your system
  All displayed processes are probed in the configured interval using Erlang’s process_info/2 function which puts a temporary lock on the process being infoed. If the process is handling a lot of messages, this may have performance implications for the system
• Spectator will send system messages to selected processes
  In order to get a selected processes OTP state, spectator needs to send it system messages. If you select a process that is not handling these messages properly, spectator may fill up its message queue, as it is sending a new message every tick in the configured interval. If the processes message queue is over a certain size, spectator will stop sending new messages, however the process may never handle the already queued up messages
• Spectator will create atoms dynamically
  When you choose to connect to other Erlang nodes, spectator needs to convert the node name and cookie you provide into atoms. Therefore it is possible to exhaust the memory of the BEAM instance running spectator using its user interface, as atoms are never garbage collected.

Further documentation can be found at https://hexdocs.pm/spectator.