The Ruby Unbundled Series: Track How Customers Use New Features
Tags: rails, ruby, ahoy, blazer
Published: 2021-03-24 08:19:26

---
title: The Ruby Unbundled Series: Track How Customers Use New Features
published: true
description: Use the Ruby gems ahoy and blazer to track user metrics, usage patterns, and get the most out of your new application features
tags: rails, ruby, Ahoy, blazer
canonical_url: https://blog.engineyard.com/ruby-unbundled-track-how-customers-use-new-features?utm_source=dev.to&utm_medium=canonical-link&utm_campaign=top
//cover_image: https://lh6.googleusercontent.com/iN_KQqhPAoK6QkZnUEDZWO6Hu9YrQTwBlgIN_-5yYvZX4XcV30RN4nbgPsyGYXaBsolN-1Cmc9bQD5hUHNnEHtRQr4A_u38QxN-BynUzzuevfy3xltlOmAFWFgDcFC6BgXj81_Lc
---
By [Darren Broemmer](https://blog.engineyard.com/author/darren-broemmer)

We continue our series on designing and launching new features on Rails by looking at the feature release process. If you missed the first article in this series, [check it out now](https://blog.engineyard.com/ruby-unbundled-design-and-launch-features-in-rails) for essential tips on designing your new feature on Rails.

You’ve worked hard to get your feature out the door, and now it’s available to your customers. Are they using it? What is their experience like? Are usage patterns evolving the way you expected?

You want to have a relentless focus on the customer experience, understand how they use your application, and know about any problems before customers encounter them. There are some great gems that are simple to set up and help facilitate the observability of your customer experience. We will look at two of them in this article, ahoy and blazer.

[Ahoy](https://github.com/ankane/ahoy) is used to track visits to your site and specific user events that you define. [Blazer](https://github.com/ankane/blazer) allows you to easily query and view the metrics data. In fact, blazer can be used to query any data in your database, and it has some nice built-in visualization capabilities for metrics as well.

__Visits and Events__
The ahoy data model is straightforward. A visit is created automatically when a user browses to your site. Events are added using a single line of code. One visit can have zero-to-many events based on what activity you decide to track. Typically, event tracking occurs within a controller action.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ajren0f34iawkn9vm3gb.jpeg)

Once you have metrics around user visits and specific events that occur during their visit, you enable a number of key capabilities for evaluating and fine-tuning your new feature.

• Correlate user metrics to any error trends you might see. This can greatly accelerate root cause analysis, especially when operating a new system or enhancements to it.
• Examine behavioral patterns such as what times of the day or days of the week see certain activity. 
• Be more reactive to customer usage patterns. For example, if a customer puts something in their shopping cart, but does not checkout within a certain time period, you may wish to trigger an event such as a follow-up email. You can define add-cart and check-out events, and then examine how many visits include one but not the other. How much time is between those two events? What did the user do in-between? This is all critical data that can be used to fine-tune the user experience and improve your application.

__The Instant Poll Sample Application__
The application we will use for this series is an Instant Poll application. It adds a poll question that is embedded on the left-hand side panel of our entertainment news website. The code for this project can be found on [GitHub](https://github.com/engineyard/eyk-app-templates/tree/webapp-features).
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/k249plro2d1v3j2roddf.png)

We will track page view events and also poll submission events. This allows us to see how many users visited the page but did (or did not) answer the poll question.

__Installing and Configuring Our Gems__
By default, both gems store information using additional tables in your same application database. However you can customize this if you wish. It's a very quick way to get started and installation is straightforward. The only downside to using the same database for metrics is that if your application runs into performance problems, you may also have trouble accessing the metrics which would help you diagnose the problem. At this stage, we will use the default configuration of additional tables in the primary database configured in the database.yml file.

Start by adding ahoy_matey and blazer to your Gemfile. Then run bundle install. 

<code>gem 'ahoy_matey'
gem 'blazer'</code>

Run the following command to install ahoy. This install adds the visit and event model classes, as well as the corresponding database migration code. 

<code>bin/rails generate ahoy:install</code>

Before running db:migrate, we will also install blazer because it also adds database tables.

<code>bin/rails generate blazer:install</code>

Now go ahead run the db:migrate.

<code>bin/rails db:migrate</code>

Our instant poll application uses Devise for authentication. Ahoy works out-of-the-box with the Devise gem. However, if you use a different authentication mechanism, you can simply tell ahoy who the user is using the following code, where @user is your User model object. With Devise, this is done for you.

<code>ahoy.authenticate(@user)</code>

In a controller, you can now track events using the ahoy.track method. The second parameter can contain any additional properties or metadata you wish to include in the event. These parameters will be stored in a text field in the database.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/a4mdnxbyom1qxmq1yuye.png)
Before we run our application and test this out, let’s add the blazer console to the routes.rb file. Blazer allows us to easily query and see our metrics. Add the following line:

<code>mount Blazer::Engine, at: "blazer"</code>

After starting Rails and logging in, we can use Blazer to see our user metrics. Browse to our mount point, which on my development environment is at http://localhost:3000/blazer. Querying the ahoy_visits table shows us relevant information about the user and their session. We can also save this query as a shortcut to run it again later.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/au676d5ofqewwus75yam.png)
After browsing to the page twice, I ran the following query on the events table. It gave the following results. Note that both events come from the same visit, which is equivalent to a session.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8eu7ar6nubc6frwi6dcm.png)
We have seen how to track events on the server-side. Now let's look at how to accomplish this from the frontend in Javascript. To do this, we need to enable the Ahoy api in the config/initializers/ahoy.rb file, as shown below.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/csulddlxyn24u2dxgvxg.png)
Note that Ahoy also supports [geocoding](https://github.com/ankane/ahoy#geocoding) so that you can see where your users are located. We will not explore that feature in this article, but it is a nice capability from a metrics perspective.

Setting up the Javascript client differs based on your version of Rails. In Rails 6, you will do two things. First, run the following command:

<code>yarn add ahoy.js</code>

Second, you will the following line to app/javascript/packs/application.js:

<code>import ahoy from "ahoy.js";</code>

In Rails 5, simply add the following line to your app/assets/javascripts/application.js file:

<code>//= require ahoy</code>

The API to track events is similar in Javascript. You can add the following code to any page. Again, the second parameter can contain any arbitrary metadata you want to store along with the event. I added this

<code>ahoy.track("PollView", {language: "JavaScript"});</code>

__Metrics Queries and Blazer Visualization__
Aside from being extremely convenient to begin with, here is where Blazer really sets itself apart. If you run a query that returns one or two strings followed by a numeric column, it will automatically graph the result for you. Below is a query I ran to look at events by day, and Blazer created a bar graph in addition to displaying the textual results. The order of columns does matter, but it follows the normal convention for writing GROUP BY queries where the count(*) column is the last one selected.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/f12tal3amah82lnk9hqt.png)
If your first select column is a timestamp, Blazer will create a line graph. Name your numeric column ‘pie’, and Blazer will display a pie chart.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hzclslioqeizjroins1s.png)
Our poll application uses sqlite and MySQL, however Blazer also works with an impressive list of data sources including Amazon Athena, Amazon Redshift, and Elasticsearch.

Blazer has other great features as well including time-series analysis and forecasting using the prophet gem. Simply add prophet-rb to your Gemfile, and include the following in the config/blazer.yml.

<code>forecasting: prophet</code>
Alternatively, use the trend gem to do forecasting using the same pattern.

Here is a simple query that calculates the conversion ratio of poll submissions over page views. There are more advanced metrics calculations you can do, but this gives you an idea about how to get started using these two simple but powerful gems to track customer usage.
![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lmdnevpga1uodrpqy67r.png)

Related Topics:
[Software Architecture](https://blog.engineyard.com/topic/software-architecture), [Ruby on Rails](https://blog.engineyard.com/topic/ruby-on-rails), [developer productivity](https://blog.engineyard.com/topic/developer-productivity), [ruby unbundled](https://blog.engineyard.com/topic/ruby-unbundled)