This repository has been archived by the owner on Apr 15, 2019. It is now read-only.
/
howto-3.html
184 lines (168 loc) · 7.16 KB
/
howto-3.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
<!DOCTYPE HTML>
<html>
<head>
<title>Boomerang Howto #3: Measure a user's bandwidth/latency along with page load time</title>
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="../boomerang-docs.css">
</head>
<body>
<span style="float:right;"><a href="../">All Docs</a> | <a href="index.html">Index</a></span>
<h1>Boomerang Howto #3:<br>Measure a user's bandwidth/latency along with page load time</h1>
<p>
See <a href="../use-cases.html#uc-3">use cases #3</a> & <a href="../use-cases.html#uc-5">#5</a> for a description of this requirement.
</p>
<p>
By default, boomerang always measures the user's bandwidth and HTTP latency and adds these numbers to the beacon
that it sends back. In reality, the bandwidth plugin (<code>BOOMR.plugins.BW</code>) does this, but since that's
bundled along with boomerang, the difference is purely academic. There are a few things you need to know in order
to use the bandwidth detection code effectively.
</p>
<p>
First, bandwidth detection through javascsript is not accurate. If the user's network is lossy or is shared with
other users, or network traffic is bursty, real bandwidth can vary over time. The measurement we take is based
over a short period of time, and this may not be representative of the best or worst cases. We try to cover for
that by measuring not just the bandwidth, but also the error value in that measurement.
</p>
<p>
Simply adding boomerang to a page and calling the <code>init()</code> method is sufficient to start the bandwidth
test and beacon its results back to the server. This is the code you'd use:
</p>
<pre>
<script src="boomerang.js" type="text/javascript"></script>
<script type="text/javascript">
BOOMR.init({
beacon_url: "http://yoursite.com/path/to/beacon.php",
BW: {
base_url: "http://base_url/to/bandwidth/images/"
}
});
</script>
</pre>
<p>
The default value of the <code>BW.base_url</code> parameter is <code>images/</code>, so if your bandwidth detection
images are placed in a subdirectory of the current directory called <code>images</code>, then you do not need
to set the <code>BW.base_url</code> parameter. It is a good practice though, as you might have pages in multiple
directories.
</p>
<p>
Now while this is the minimum code required to measure bandwidth and latency and have it beaconed back, it isn't
the best option for your user. The test will run every time the user visits a page on your site even though
their bandwidth probably hasn't changed (apart from regular fluctuations). It's far better to store the bandwidth
in a cookie for a fixed period of time, and read it out of the cookie if it exists. Now it is possible that the
user moves between several networks, eg: a laptop used at home, at work and at a coffee shop. The bandwidth and
latency at these locations may be different, and it's necessary to measure them separately. We detect a change
in network through the user's IP address, so in order to store the user's bandwidth in a cookie, you will need
to tell boomerang what the user's IP address is. You do this through the <code>user_ip</code> parameter.
</p>
<pre>
<script src="boomerang.js" type="text/javascript"></script>
<script type="text/javascript">
BOOMR.init({
beacon_url: "http://yoursite.com/path/to/beacon.php",
user_ip: "<user's ip>",
BW: {
base_url: "http://base_url/to/bandwidth/images/"
}
});
</script>
</pre>
<p>
As far as I know, there's no way in javascript to figure out the user's IP address. You'll have to do this server
side and write the value into your code.
</p>
<h2>IPv4 optimisations</h2>
<p>
If your user has an IPv4 address, then we also strip out the last part of the IP and use that rather than the entire
IP address. This helps if users use DHCP on the same ISP where their IP address changes frequently, but they stay
within the same subnet. If the user has an IPv6 address, we use the entire address.
</p>
<h2>The Cookie</h2>
<p>
You may want to customise the name of the cookie where the bandwidth will be stored. By default this is
set to <code>BA</code>, but you can change it using the <code>BW.cookie</code> parameter.
</p>
<pre>
<script src="boomerang.js" type="text/javascript"></script>
<script type="text/javascript">
BOOMR.init({
beacon_url: "http://yoursite.com/path/to/beacon.php",
user_ip: "<user's ip>",
BW: {
base_url: "http://base_url/to/bandwidth/images/",
cookie: "BW"
}
});
</script>
</pre>
<p>
This cookie is set to expire in 7 days. You can change its lifetime using the <code>BW.cookie_exp</code> parameter.
The value is in seconds. During that time, you can also read the value of the cookie on the server side. Its
format is as follows:
</p>
<pre>
BA=ba=<span class="ni">nnnnnnn</span>&be=<span class="ni">nnn.nn</span>&l=<span class="ni">nnnn</span>&le=<span class="ni">nn.nn</span>&ip=<span class="ni">iiiiii</span>&t=<span class="ni">sssssss</span>;
</pre>
<p>
The parameters are defined as:
</p>
<dl>
<dt>ba</dt>
<dd>[integer] [bytes/s] The user's bandwidth to your server</dd>
<dt>be</dt>
<dd>[float] [bytes/s] The 95% confidence interval margin of error in measuring the user's bandwidth</dd>
<dt>l</dt>
<dd>[float] [ms] The HTTP latency between the user's computer and your server</dd>
<dt>le</dt>
<dd>[float] [ms] The 95% confidence interval margin of error in measuring the user's latency</dd>
<dt>ip</dt>
<dd>[ip address] The user's IPv4 or IPv6 address that was passed as the <code>user_ip</code> parameter to the <code>init()</code> method</dd>
<dt>t</dt>
<dd>[timestamp] The browser time (in seconds since the epoch) when the cookie was set</dd>
</dl>
<p>
These parameters are also sent in the beacon (See <a href="howto-0.html">HOWTO #0</a>), but having them in the
cookie means that you can customise your users experience based on the bandwidth before you serve a request.
</p>
<h2>Disabling the bandwidth check</h2>
<p>
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 bandwidth test uses a lot of bandwidth), or is on
a mobile device that cannot handle the load. In such cases you have two options.
</p>
<ol>
<li>Delete the bandwdith plugin from your copy of boomerang.js</li>
<li>Set the <code>BW.enabled</code> parameter to <code>false</code>:</li>
</ol>
<pre>
<script src="boomerang.js" type="text/javascript"></script>
<script type="text/javascript">
BOOMR.init({
BW: { enabled: false }
});
</script>
</pre>
<p class="perma-link">
The latest code and docs is available on <a href="http://github.com/lognormal/boomerang/">github.com/lognormal/boomerang</a>
</p>
<p id="results">
</p>
<script src="../../boomerang.js" type="text/javascript"></script>
<script src="howtos.js" type="text/javascript"></script>
<script type="text/javascript">
BOOMR.init({
user_ip: '10.0.0.1',
BW: {
base_url: '../../images/',
cookie: 'HOWTO-BA'
},
RT: {
cookie: 'HOWTO-RT'
}
});
</script>
</body>
</html>
<!--
Copyright (c) 2011, Yahoo! Inc. All rights reserved.
Copyrights licensed under the BSD License. See the accompanying LICENSE.txt file for terms.
-->