Active Explorer gem — easier Ruby on Rails debugging

Vít Uličný

Published in

Rascasone s.r.o.

5 min readSep 18, 2017

Let me introduce to you our new Ruby gem that I have been working on recently.

It is called Active Explorer (https://github.com/rascasone/active_explorer).

It works like “awesome_print with associations” (in console mode) and like “railroady for runtime data” (in image graph version).

It prints your object data with all associated object in a nice way and with one command. It “explores” your object and its surroundings.

In this blog I will discuss following topics:

TL; DR

In case you don’t have time to read it all:

1. Add this to your Gemfile.

gem `active_explorer`

2. Set a breakpoint and when the program stop, try this in console:

# Console output
ex my_object# Image output (install GraphViz software first)
exf my_object

3. See what happens ;)

Find more examples and complete guide on Github: https://github.com/rascasone/active_explorer

What does it do?

The gem prints out attributes of your object and of all objects associated with itby `has_many` or `belongs_to`. It prints the output:

either to console (like awesome_print)
to an image file (like railroady)

It works only with model objects — i.e. instances of Active Record.

Why did I created it?

When project gets to a certain size I sometimes encounter situations when I am a little bit lost during debugging. I am inspecting many objects that are connected by associations, using several breakpoints. And I need to quickly explore the data — see values of objects and connections to other objects.

For example on our recent project we are working with these classes that describe flow of Customer interactions with Emails and Web forms.

# Customer is someone either addressed by email or a visitor on a web page
class Customer < ActiveRecord::Base
  has_many :greetings
  has_many :requests
end# Greeting email is received by Customer and might lead to Request
class Greeting < ActiveRecord::Base
  belongs_to :customer
  has_many :requests, through: greeting_to_request
end# Association Model that connects Greeting and Request
class GreetingToRequest < ActiveRecord::Base
  belongs_to :greeting
  belongs_to :request
end# Request is created by Customer (either directly through web page or based on Greeting email)
class Request < ActiveRecord::Base
  belongs_to :customer
  has_many :greetings, through: greeting_to_request
  has_many :offers
end# Offer is created in response to Request and consists of several Calculations
class Offer < ActiveRecord::Base
  belongs_to :request
  has_many :calculations
end# Calculation is a part of Offer
class Calculation < ActiveRecord::Base
  belongs_to :offer
  has_many :orders
end# Order is created by Customer based on Calculation
class Order < ActiveRecord::Base
  belongs_to :offer
  has_many :calculations
end

You see that there are many associations and they go deeper and deeper. At several moments when I was examining creation of Calculations I wanted to see what associations to other objects it has. And what the data (attributes) of all the objects look like.

For example I wanted to know about Calculation:

what Request it came from
what Customer was associated with it
whether that Request originated from a Greeting
what Orders were created based on it

I needed to do:

calculation.offer.request
calculation.offer.request.customer
calculation.offer.request.greetings
calculation.orders

A lot of typing. Of course, some things like getting `customer` can be handled by delegation. Also, in Console you can easily repeat last commands. But all this adds up and when I repeated it several times I really wished to have it all in one command and in a clear view.

Now I can do the same with just one command:

ex calculation

And that is just great ;)

I am not saying that you would use it everyday or as much as you use Awesome Print’s `ap` but it is nice feature to have. I use it from time to time when I want to "explore surroundings" of my object and be sure "where I am".

Also I comes handy when you want to discuss something with your colleague and want to have clear view of the situation. Now `exf` comes to play.

How to use it

First of all you need to use it only with Active Record objects. You have two option how to use the gem.

Console output
Image output (using GraphViz library)

Console output

The Console output just uses IRB to display the output.

Command:

ex <your_object>

Example output:

ex calculation# => Console output: Calculation(1232) {:offer_id=>554142781, :company_id=>7}
  -> belongs to Offer(554142781) {:request_id=>980190974, :created_at=>Wed, 22 Jun 2016 14:36:57 CEST +02:00}
      -> belongs to Request(980190974) {:car_cylinder_capacity=>1500, :car_performance=>160}
          -> belongs to Customer(980190974) {:name=>"Marry", :surname=>"Helpful"}
          -> belongs to ZipCode(7828) {:zip_code=>"51101", :city_id=>97942}

Image output

Image output generates a graph of connected objects using the GraphViz software (here is how to install it) and saves it to a file.

Command:

exf <your_object>

Example output:

The file is by default saved in your root.

Plans

Community

First of all I would like to get this gem to community so that it can be thoroughly tested and new ideas can appear. Please if you like or dislike the gem or have suggestions get in touch with me.

Bug hunt

I know about some minor bugs so the bug hunt is necessity. I would also really like to support older versions of Ruby on Rails. Currently the gem works only for version 4.2. I would like to support all 4.x version and soon-to-be released version 5.

Enhancements

I want to make the output nicer and more usable:

colorize
interactive graph
export to other formats? (SVG)
export to online service for sharing possibility? (yuml.me)

Gem creation hints

If you are thinking about creating your own gem — do it. To finish some library and tune it out will help you to be better at coding and you can also help others = Karma!!! ;)

And here is short list of “How to create new gem” guides:

To see my problems and solutions during gem development (and some tips) visit my post Gem development — troubles and solutions.

Thanks for reading.

What is your opinion about the gem? Please leave a comment. Thanks!

On June 22nd, 2016 by Marek Uličný