The bandwidth plugin measures the bandwidth and latency of the user's network connection to your server.
The measurement Boomerang takes is based over a short period of time, and this may not be representative of the best or worst cases. Boomerang tries to account for that by measuring not just the bandwidth, but also the error value in that measurement.
For information on how to include this plugin, see the Building tutorial.
The bandwidth images are located in the
images/ folder. You need to copy all
of these images to a location on your HTTP server.
You may put these images on your CDN, but be aware that this could result in increased CDN charges. You will need to configure your CDN to ignore the query string when caching these images.
Once Boomerang has been added to your page and
BOOMR.init has been called,
the bandwidth test will start once the page loads.
If you want the page load beacon to include the results of the bandwidth test,
true will force boomerang
to wait for the test to complete before sending the beacon.
If you do not turn on the
you will only receive bandwidth results if they were cached in a cookie by a
previous test run.
will use it to detect if the visitor has changed networks. See
BW.user_ip for details.
If your visitor has an IPv4 address, then Boomerang will also strip out the last part of the IP and use that rather than the entire IP address. This helps if visitors use DHCP on the same ISP where their IP address changes frequently, but they stay within the same subnet.
If the visitor has an IPv6 address, we use the entire address.
The bandwidth results are stored within a cookie. This helps ensure the bandwidth test isn't repeated for the same user repeatedly (slowing down their experience).
You can customise the name of the cookie where the bandwidth will be stored via
By default this is set to
This cookie is set to expire in 7 days. You can change its lifetime using
During that time, you can also read the value of the cookie on the server side. Its format is as follows:
The parameters are defined as:
ba[integer] [bytes/s] The user's bandwidth to your server
be[float] [bytes/s] The 95% confidence interval margin of error in measuring the user's bandwidth
l[float] [ms] The HTTP latency between the user's computer and your server
le[float] [ms] The 95% confidence interval margin of error in measuring the user's latency
ip[ip address] The user's IPv4 or IPv6 address that was passed as the user_ip parameter to the init() method
t[timestamp] The browser time (in seconds since the epoch) when the cookie was set
Disabling the bandwidth check
Finally, there may be cases when you want to completely disable the bandwidth test -- perhaps you know that your user is on a slow network, or pays by the byte (the andwidth test uses a lot of bandwidth), or is on a mobile device that cannot handle the load.
In such cases you have two options:
- Delete the bandwdith plugin (
- Set the
Bandwidth and latency are measured by downloading fixed-size images from a server and measuring the time it took to download them. We run it in the following order:
- First, download a 32 byte gif 10 times serially. This is used to measure latency.
- We discard the first measurement because that pays the price for the TCP handshake (3 packets) and TCP slow-start (4 more packets). All other image requests take two TCP packets (one for the request and one for the response). This gives us a good idea of how much time it takes to make a HTTP request from the browser to our server.
- Once done, we calculate the arithmetic mean, standard deviation and standard
error at 95% confidence for the 9 download times that we have. This is
the latency number (
lat) and confidence intervl (
lat_err) that we beacon back to our server.
- Next, download images of increasing size until one of the times out
- We choose image sizes so that we can narrow down on a bandwidth range as soon as possible.
- Image timeouts are set at between 1.2 and 1.5 seconds. If an image times
out, we stop downloading larger images, and retry the largest image 4
more times. We then calculate the bandwidth for the largest 3 images
that we downloaded. This should result in 7 readings unless the test
timed out before that. We calculate the median, standard deviation and
standard error from these values and this is the bandwidth (
bw) and confidence interval (
bw_err) that we beacon back to our server.
This plugin adds the following parameters to the beacon:
bw: User's measured bandwidth in bytes per second
bw_err: 95% confidence interval margin of error in measuring user's bandwidth
lat: User's measured HTTP latency in milliseconds
lat_err: 95% confidence interval margin of error in measuring user's latency
bw_timeTimestamp (seconds since the epoch) on the user's browser when the bandwidth and latency was measured
Stops the bandwidth test immediately and attempts to calculate bandwidth and latency from values that it has already gathered.
This method is called automatically if the bandwidth test times out.
It is better to set the timeout value appropriately when calling the
Initializes the plugin.
Name Type Description
Name Type Argument Description
By default, this is set to the empty string, which has the effect of disabling the bandwidth plugin. Set the
base_urlparameter to the HTTP path of the directory that contains the bandwidth images to enable this test.
This can be an absolute or a relative URL.
The trailing / is required.
The name of the cookie in which to store the measured bandwidth and latency of the user's network connection.
The default name is
The lifetime in seconds of the bandwidth cookie.
The default is set to 7 days. This specifies how long it will be before we run the bandwidth test again for a user, assuming their IP address doesn't change within this time.
You probably do not need to change this setting at all since the bandwidth of a given network connection typically does not change by an order of magnitude on a regular basis.
Note that if you're doing some kind of real-time streaming, then chances are that this bandwidth test isn't right for you, so setting this cookie to a shorter value isn't the right solution.
The timeout in seconds for the entire bandwidth test.
The default is set to 15 seconds.
The bandwidth test can run for a long time, and sometimes, due to network errors, it might never complete. The timeout forces the test to complete at that time. This is a hard limit.
If the timeout fires, we stop further iterations of the test and attempt to calculate bandwidth with the data that we've collected at that point.
Increasing the timeout can get you more data and increase the accuracy of the test, but at the same time increases the risk of the test not completing before the user leaves the page.
The number of times the bandwidth test should run.
The default is set to 5.
The first test is always a pilot to figure out the best way to proceed with the remaining tests. Increasing this number will increase the tests accuracy, but at the same time increases the risk that the test will timeout.
It should take about 2-4 seconds per run, so consider this value along with the timeout value above.
By default, boomerang will skip the bandwidth test over an HTTPS connection.
Establishing an SSL connection takes time, which could skew the bandwidth results. If all your traffic is sent over SSL, then running the test over SSL probably gets you what you want.
If you set
true, boomerang will run the test instead of skipping.
By default, the bandwidth plugin will not block boomerang from sending a beacon, so the results will not be included in the broadcast with default settings.
If you set
block_beaconto true, boomerang will wait for the results of the test before sending the beacon.
The user's IP address, for detecting if networks change.
Whether or not this plugin is complete
trueif the plugin is complete
Starts the bandwidth test. This method is called automatically when boomerang's
BOOMR#event:page_readyevent fires, so you won't need to call it yourself.