Real User Monitoring with ExtraHop -- Direct Deployment

bundle
triggers

#1

Direct Deployment 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 directly on your web infrastructure. In this scenario, there is no proxy or load balancer (or you are choosing not to use them) to inject the Boomerang javascript code in to your web pages. Instead, we will include the javascript code directly on your web server(s) and modify the HTML code of your website to include them.

This is the most basic and straightforward method of setting up Real User Monitoring (RUM). 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 web server 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. A common file that all your web pages include, like a footer or header, for us to insert the Boomerang Javascript code into.
  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 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.

Locate and edit a common include file to insert Boomerang

Like I mentioned in Step #3 above, we need to utilize a commonly included file that all your web pages reference to make sure that Boomerang gets inserted in to each page. In our installation, we have a footer page (/var/www/htdocs/include_footer.html – creative, no?) and the last two lines in that file look like this:

</body>
</html>

Let us go ahead and modify it first to insert the Boomerang JavaScript, and go through it line by line after.

    <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>
</html>

So far, so good. The first four lines are the Boomerang Javascript files that provide the needed functionality we require (base, W3C Navigation Timing, Round Trip Timing, and Session GUIDs). The fifth line, through the end, contains the code to initialize Boomerang on each page and sets up some required information in order for things to function properly. In this case, we need to specify the beacon that all the RUM data will be sent back to and define a cookie to be used for the Round Trip Timing metrics. This is finished up with the original </body> and </html> tags to signify the end of the HTML document.

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 insertion part.

Create a beacon page

In line 7: beacon_url: '/boomerang-beacon.html', we specified a URI for our beacon. The beacon is the page in which all of the RUM metrics will be sent and is the URI that the ExtraHop will watch for to provide all of our Real User Monitoring awesomeness. This page can be empty, as it doesn’t do anything except to server as an end point for receiving data.

We need to create it since it doesn’t exist yet. You can use the editor of your choosing to do so, or if you are on a UNIX-like server, you can simply issue the following command:

$ sudo touch /var/www/htdocs/boomerang-beacon.html

That file name is not set in stone. Just make sure it matches whatever you specify in the Javascript you defined for your web site.

Test the Javascript insertion

The easiest way to confirm whether or not you were successful in inserting the Boomerang Javascript is to browse directly to your footer HTML page. In our case, that would be http://www.example.com/include_footer.html. 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, browse to your top-level page and confirm that the footer was included, and by extension, the Boomerang Javascript code as well.

At this point, if you DO NOT SEE IT, we need to make sure the insertion is happening where we expect it to before continuing:

  1. Is the page we have browsed to the same as the one we modified?
  2. Is the web server possibly caching an older copy of the page? If so, can we flush the cache or restart the web server?
  3. Is there a proxy or load balancing tier performing any caching?

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


Real User Monitoring with ExtraHop -- Injection with nginx