Erlubi is a simple visualizer for erlang systems using Ubigraph. Ubigraph is a general-purpose dynamic graph visualization software. In general, you can use ubigraph to very easily visualize the supervision tree of an application on the BEAM.

Prerequisites

Before you can use erlubi, you need to install and run the Ubigraph server. I've provided a link to its download page in this episode's Resources section. The rest of this episode assumes you've downloaded and started it, so if you haven't, feel free to pause the episode and go do that.

Project

We're going to use the Phoenix Chat Example project as the application we'll visualize. First, go ahead and clone it:

git clone git@github.com:chrismccord/phoenix_chat_example
cd phoenix_chat_example

Now, we're going to add the erlubi project as a dependency. This is by no means necessary, but it's the easiest way to get this going.

{:erlubi, github: "krestenkrab/erlubi"}

Next, we'll just install all the dependencies:

mix deps.get

Now we'll start an iex session:

iex -S mix

OK, at this point neither the Chat application or the erlubi tracer are running. Erlubi has two modes it can be run in. One is just a general-purpose api to add vertexes, edges, and shapes to the erlubi server. The other will install erlang trace hooks to find out about new processes and links, and draw the graph of them automatically. Since that one's more interesting and has some debugging value, we'll be looking at that one.

We'll start the erlubi tracer:

:erlubi_tracer.run

Now if you look at your ubigraph window, you can see the state of the elixir system. This application's mix.exs file specifies the phoenix application to start, and phoenix specifies cowboy and plug, so all three of those applications, as well as their dependencies, will be started. That's why the graph is already so dense.

You can click in the Ubigraph window and drag to rotate the graph, and you can use the arrow keys on your keyboard to move in and out. Middle clicking and dragging will pan, but that seems a bit buggy. In this view, ports are green, named processes are blue, and all other pids are red.

This is already a fun way to observe a running erlang system, but now let's see what happens when we start up the Phoenix router. Zoom out so that you can see most of the graph, and we'll start it up:

Chat.Router.start

Alright, so now there's this kind of awesome little ball of processes floating around. We can inspect it a bit. Try to zoom in near the center of it.

You can see that all of the pids on the outside of this sphere are linked to the central sphere. This is a web server we're looking at, so you can start to figure out what you think these are - I didn't know when I did this the first time, and I had to dig in a bit. So you can zoom in to the central pid and get its process id. Now you can fire up :observer to look at what that pid is:

:observer.start

OK, so we'll go into processes here and find the pid in question. There you go, you can see it's a :supervisor.ranch_acceptors_sup process, and it's in a gen server loop. Turns out ranch is the socket acceptor pool for cowboy's tcp sockets, so this structure makes sense. It supervises a set number of socket acceptors. Cowboy started this up when we started the router, as a prerequesite.

If you wanted to then look at a flat graph of where this came from, you can open up the "Applications" tab in observer and look at the ranch application. Here, you can see the same general structure, but flat, and on a per-application basis.

Summary

In today's episode, we learned how to visualize an Elixir system in a 3d graph using an Ubigraph server and the erlubi erlang module. I hope you enjoyed this as much as I did when I saw it for the first time. See you soon!

Resources