Periscope - tools for debugging and introspection

Introducing Periscope, which is meant to save you time when working with LiveView. Version 0.4.4 is published to hex.

(feel free to star the repo if you like it!)

Engineers waste a lot of time tracking down the module for the currently-loaded LiveView. I’ve seen people grab random chunks of HTML out of the inspect and soft-search VS Code for that chunk. I’ve also seen people looking at the URL, and then waste five minutes scrolling through the router just to figure out what module they’re on.

Periscope solves this problem. Import it in your ies.exs and spin up your app locally with iex -S mix phx.server. Then type which_liveview. Voila, you now know which liveview you’re on!

Another big waste of time is sticking IO.inspect into random places in a module just to view the socket. Periscope also solves this problem. Just import it and type socket and hey presto, you can view the socket! The socket function returns a socket struct, so you can treat it as one. That means you can type socket.assign to see your current assigns.

Can’t find the assigns or socket you’re looking for, because the currently loaded page is in a component? No problem. component_names/0 returns a list of all active components, making it easy to find your module. You can even type assigns_for(YourAppWeb.SomeLiveView.SomeChildComponent) and view all of the assigns for SomeChildComponent.

Finding the routes for a component can be a bear as well. mix phx.routes gives you routes and HTTP verbs, but not module names. Finding the routes to a module requires going to the router and scrolling through to piece together the route bit by bit. Periscope solves this problem as well: just type paths_and_liveviews and you’ll get a map where each key is a fully-qualified module name and each value is a list of routes to that module. Easy-peasy.


Yesterday I had to work in a Django/Wagtail codebase I am unfamiliar with and my workflow was exactly as described. Having a tool like Periscope would have made my day much more productive.

Certainly will add this to my next Phoenix app. If not for me (who knows the codebase) then for a fellow dev who might not.



Thanks for the encouragement. I’m happy to know that someone already seems some utility in this lib!

Anyhoo, I want everyone to know that version 0.4.5 is up! Documentation is much improved, and I brought back the ability to see components instead of just their names.

Indeed. Periscope.socket is instantly helpful.
What do you think about the following feature:


On each change of the assigns, shows a diff.


Update - now up to version 0.5.6. Fixed a few bugs.

More importantly, introducing a new feature: deep_has_key?/2. Think of it as a version of Map.has_key?/2 that works for nested maps. It’s there because of this: a single socket can have quite a few lines - the webapp I’m currently working on will, if you execute socket, return well over 2000 lines of code. Nobody wants to search all that. deep_has_key?/2 can reach into the socket and assigns and see if a key exists at any point. So if you’re wondering whether client_id (or some such assign) exists in your socket, you can run deep_has_key?(socket, :client_id) and you’ll get a boolean telling you whether that key is anywhere in the socket. It works by flattening the nested maps, taking only the keys, and then searching for the key passed as second arg.

I like this. It will be a little challenging to implement. I’m thinking of spawning a new process and having liveview hooks in the watched socket to notify the watcher whenever the assigns change. If anybody knows a better way, let me know.

1 Like
  • maybe change the LV-behaviour, so no change to the user’s code is necessary. (on each assign to the socket, send it to some debug port). This would be a maintenance nightmare, so ideally that would be part of LV. I think it could be argued, that LV would benefit from such a trace-port. Edit: most likely the better idea: use erlang tracing. Set up a process, that get a message (containing the socket) every time socket changes. There should be a point somewhere in the LV-behaviour that is hit always when socket changes.
  • use polling (like repeatedly typing iex> socket)
1 Like