Better Real User Monitoring with BoomerangJS and Akamai mPulse
In this blog, we'll walk through a few different snippet insertion methods and available optimizations. Akamai's real user monitoring (RUM) solution, mPulse, uses a bit of JavaScript code (an mPulse snippet) and the BoomerangJS library to collect performance data from a user's Web browser. However, the manner in which this snippet is embedded impacts the quantity of data collected and level of effort involved in managing the solution.
The mPulse snippet can be inserted two ways. It can go into pages served from Akamai using Akamai edge injection. Alternatively, origin tag insertion can be employed. We'll examine the benefits and drawbacks of each method to help you select the best implementation for your setup and measurement needs.
Akamai edge injection
Edge injection offers the most benefits. Setup and configuration can take as little as 15 minutes with Property Manager (PM), and Akamai takes care of snippet maintenance. Additional benefits include:
- Use of property variables to easily enable and disable features
- Configuration override options to further refine feature behavior
- The ability to add conditional rules and insert the snippet in different ways for different circumstances (such as IE 11 edge cases)
- Bot Manager (Botman) bot categorization information injected by default
- Middle-mile information injected by default (as shown in the diagram below)
Built-in payment card industry compliance
- A setting to customize resource timing buffer size
- Adaptive acceleration that requires edge injection
Edge injection has a few drawbacks, such as custom snippets that can't be used without resorting to advanced metadata. Also, utilizing other tool(s) for managing third-party tags combined with edge injection adds an additional point of change, unless you wish to omit inserting the snippet using a PM variable and thereby lose out on Botman data.
Botman data includes the following three filters available in the mPulse graphical user interface .
- Bot Manager: Indicates whether or not Bot Manager was enabled for the page visit
- Bot Manager Bot Type: Indicates the bot type as classified by Bot Manager
- Bot Manager Bot Category: Indicates the bot category as defined by Bot Manager
Find additional information on Bot Manager integration with mPulse.
Origin tag insertion
Inserting the mPulse tag at the origin provides you with complete control over how the tag is inserted. Benefits include the ability to use a custom tag snippet and control of all site tags in one place, typically using one tool. The snippet can be inserted at the origin, either by adding it to your site's code directly or by using any tag manager. For more information on this approach, visit set up mPulse at the origin.
There are some drawbacks to origin tag insertion. Most of the long list of edge injection benefits are missing. In addition, few features from the edge injection list can be utilized if the tag and/or site code is modified directly using configuration override JavaScript code. With some careful configuration, however, you can maintain Ion's Adaptive Acceleration feature. See the Multiple content delivery network (CDN) optimization section of this post for more information.
Optimizations
Property Manager variables
With the ability to set variables, PM gives you better control of the behaviors of a given property configuration function. More information on the use of PM variables can be found at variable support.
As of this writing, the following hidden variables can be employed in PM to control snippet insertion and features. These variables can be set globally, as well as within a conditional rule, which enables numerous possibilities.
- PMUSER_MPULSE_BOTMAN
- Controls whether Bot Manager data is added to the beacon
- PMUSER_MPULSE_SNIPPET
- Controls whether the mPulse loader snippet is emitted
- PMUSER_MPULSE_EDGE_METRICS
- Controls whether the edge/origin metrics are calculated and added to the base page HTML when the mPulse snippet is edge injected
- PMUSER_MPULSE_AMP_SUPPORT
- Controls whether the mPulse AMP snippet is emitted
- PMUSER_MPULSE_STATUS_CODE
- Range of HTTP status codes that include the mPulse loader snippet
- PMUSER_MPULSE_CACHE_BUST
- Adds a query string to the Boomerang URL to help bust Boomerang out of visitors' caches
- PMUSER_MPULSE_CONSENT
- Controls whether the Boomerang Consent Inline Plugin is injected
- PMUSER_MPULSE_CONSENT_OPT_REQ
- Controls whether or not consent is required (opt-in)
For more detailed information on available PMUSER variables, please contact your Akamai sales or professional services team.
Configuration overrides
Configuration overrides are JSON strings that turn off or turn on specific Boomerang options. They can accomplish a variety of results but must be used with discretion and care. More information on the mPulse PM behavior can be found at mPulse behavior options, and step six provides a configuration override example.
While not a complete list, below are a few of the more common overrides I've seen employed.
Single page application inclusion and exclusion
This is a helpful override that can be used when dealing with a site that has mixed single page application (SPA) and non-SPA pages. Depending on whether the majority of the site's pages are SPA or not will determine the approach you should use. With the former (majority SPA pages), it's recommended to enable SPA by default and then disable SPA on the non-SPA pages. The opposite approach is recommended for the latter (majority non-SPA pages).
Enable SPA
{
"autorun": true,
"History": {
"enabled": false
}
}
Disable SPA
{
"autorun": false,
"History": {
"enabled": true
}
}
Excluding certain requests from instrumentation
Excluding requests from edge injection is a common use case for undesired iFrame content traffic and/or any time you have a website section or page(s) where instrumenting with mPulse could cause an issue (not common).
The example configuration override below will exclude instrumentation of www.soasta.com and c.go-mpulse.net, as well as URLs that include /api/v1/foobar in their path and the exact URL https://mpulse.soasta.com/dashboard.
{
"xhr_excludes": {
"www.soasta.com": true,
"c.go-mpulse.net": true,
"/api/v1/foobar": true,
"https: //mpulse.soasta.com/dashboard/": true
}
}
Find more information on configuration overrides.
Multiple content delivery network optimization
When dealing with multiple content delivery networks (CDNs) on a single site, inserting the tag at the origin by either adding the snippet to the codebase or using a tag manager will result in RUM data being gathered for pages delivered by all of the CDNs. However, if the site also uses Ion Adaptive Acceleration for Akamai-delivered pages, which requires the mPulse behavior to be injected from the edge, duplicate tags would result.
Whenever the mPulse snippet needs to be injected from the origin instead of the edge, and the site is using adaptive acceleration:
- The mPulse behavior needs to be configured just like it would be for edge injection
- The PMUSER_MPULSE_SNIPPET property variable needs to be added and set to false (be mindful that "false" has to be lowercase)
- The following line of code needs to be added at the top of the mPulse snippet that is being inserted at the origin or via a tag manager (Replace %(AK_ARLID) with the ARLID (a.k.a. File ID) of the property)
(window.BOOMR_mq = window.BOOMR_mq || []).push(["addVar", "ak.ai", "%(AK_ARLID)"]);
Example
<script>
(function() {
(window.BOOMR_mq = window.BOOMR_mq || []).push(["addVar", "ak.ai", "123456"]);
// Boomerang Loader Snippet version 14
if (window.BOOMR && (window.BOOMR.version || window.BOOMR.snippetExecuted)) {
return;
}
...
})();
</script>
The ARLID is the same as the File ID which can be found by reviewing the property configuration's XML:
The loss of additional Akamai-specific data that would normally be included in an injected tag, such as Botman data, is a major downside to this approach. However, ServerTiming data for the CDN edge time and origin time, as well as cache hit data, will still be injected into the pages. It would be desirable for the origin not to inject the tag for pages delivered by Akamai, especially if Botman categorization is needed.
Make the most of real user monitoring data
Quality data collection is paramount for accurate RUM insights. Though the level of configurability that is available can be daunting at times, it's well worth the effort to ensure that a site's mPulse snippet implementation is on target.
See if your websites have any room for improvements in tag insertion, and rest assured that you'll be able to maximize the value of the rich data mPulse can provide.
Resources
