Real User Monitoring with ExtraHop -- Injection with nginx

triggers
bundle

#1

Injection using nginx of Real User Monitoring with ExtraHop and Boomerang.js

This post will cover how to install and set up Real User Monitoring with ExtraHop and Boomerang.js by injecting the code on the fly with nginx. In this scenario, we will use the ngx_http_sub_module to modify HTTP responses from nginx itself to inject the Booomeran javascript code.

This method falls somewhere between the Direct Deployment method and the Injection with F5 BIG-IP method. It requires you to have the Boomerang Javascript code somewhere on your web server(s), but doesn’t require any modification of the web site code itself. If you are looking for alternative deployment scenarios, please see my Getting Started post.

Requirements

  1. A copy of Boomerang from github. Click the ‘Download ZIP’ link for simplicity sake.
  2. An understanding of your nginx and its configuration. I will be assuming that your web root is located at /var/www/htdocs. The web root is the filesystem location that corresponds to the top level on your web site (e.g. The contents of /var/www/htdocs are what show up when someone browses to http://www.example.com/).
  3. An nginx installation compiled to support the ngx_http_sub_module. This module is not built by default, so your installation may need to be modified.
  4. Review the RUM page on our Solution Bundles Gallery, specifically the Installation Instructions section for information regarding installing the bundle.
  5. Review the documentation for Boomerang and understand how it works.

Install Boomerang on your web server(s)

I am going to assume that you have more than one web server powered by nginx in your environment that is being load-balanced, but if you don’t, then the following steps only have to be performed on your single machine. If you are working within a load-balancing set up, perform the following steps for each web server you want to measure with RUM.

Place the Boomerang source on your web server

Unzip the downloaded Boomerang source somewhere into your web root (/var/www/htdocs/js, where js/ is a top level directory in our web root). You will notice that there are a LOT of files, and we won’t need most of them. For our installation, we only need boomerang.js and the plugins/ directory, we will delete the rest.

Modify your nginx configuration

Referencing the documentation for ngx_http_sub_module, we can see that it is fairly straightforward to modify HTTP responses on the fly. Using the same Javascript code snippet that we used in the Direct Deployment scenario, we can adapt that to a config that will produce the same results without modifying your web site code.

location / {
    sub_filter '</body>' '<script src="/js/boomerang/boomerang.js" type="text/javascript"></script><script src="/js/boomerang/plugins/navtiming.js" type="text/javascript"></script><script src="/js/boomerang/plugins/rt.js" type="text/javascript"></script><script src="/js/boomerang/plugins/GUID.js" type="text/javascript"></script><script type="text/javascript">BOOMR.init({ beacon_url: "/boomerang-beacon.html", RT: { cookie: "EH-RUM-RT" }});</script></body>';
    sub_filter_once on;
}

Note: all the paths specified in the <script> lines are relative to the web root and root of your web site.

That is it, essentially, for the Javascript injection part. Now let’s handle the beacons. Make another modification to your nginx configuration:

location /boomerang-beacon.html {
    return 200;
    #access_log off;
}

This section make sit so you don’t need an actual beacon page on your web server(s). Uncomment the access_log off; line if you would like all the hits to the beacon page to not clutter up your web server logs.

You may need to restart nginx for the changes to take place. Reference your server logs to confirm that nginx started back up properly and did not throw any errors regarding the changes that were just made.

Read the Direct Deployment scenario post if you would like information about the Javascript code that was just specified.

Test the Javascript insertion

The easiest way to confirm whether or not you were successful in injecting the Boomerang Javascript is to browse directly to your website Once we’ve done that, use your browser to view the source code, scroll down to the bottom, and you should see that the Boomerang Javascript is there.

At this point, if you DO SEE IT, good job. That was a pretty advanced thing you just did. Now prepare yourself to bask in the glory of RUM bits.

At this point, if you DO NOT SEE IT, we need to make sure the injection is happening where we expect it to before continuing. I would start with your nginx server logs – make sure that it isn’t reporting errors with the changes to the configuration we made and check to see if there are any hits to the Boomerang Javascript code we are injecting.

Wrapping it all up

If you have made it this far, good job. The last thing to do is to make sure you have the ExtraHop side of the equation set up. For that, head on over to the Real User Monitoring Solution Bundle page for how to finish your configuration. Pay particular attention to the Installation steps that document a potential change in the ExtraHop trigger code to match your installion.

Cheers and good luck!
ryanc