forked from YahooArchive/boomerang
/
howto-6.html
245 lines (219 loc) · 9.34 KB
/
howto-6.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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
<!DOCTYPE HTML>
<html>
<head>
<title>Boomerang Howto #6: Configuring boomerang</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 #6: Configuring boomerang</h1>
<p>
To use boomerang, you first include <code>boomerang.js</code> in your html file and
then call the <code>BOOMR.init()</code> method. This should be sufficient to measure
page performance, but may not be useful enough to you as a site owner. You still won't
get data back to your server, and probably won't be able to measure the user's bandwidth
either.
</p>
<p>
In this document we'll look at all the different parameters you can use to configure
boomerang and its built in plugins. If you have additional plugins, consult their
documentation for details on how to configure them.
</p>
<h2>Configuring boomerang</h2>
<p>
To configure boomerang and its plugins, you pass in a configuration object to the <code>init()</code>
method:
</p>
<pre>
BOOMR.init({
key: value,
...
});
</pre>
<p>
boomerang has the following configurable parameters:
</p>
<dl>
<dt>beacon_url</dt>
<dd>
<strong>[highly recommended]</strong>
The URL to beacon results back to. All parameters will be added to this URL's
query string. This URL should not already have a query string component.
There is no default value for this parameter. If not set, no beacon will be sent.
</dd>
<dt>site_domain</dt>
<dd>
<strong>[recommended]</strong>
The domain that all cookies should be set on. Boomerang will try to auto-detect this,
but unless your site is of the <code>foo.com</code> format, it will probably get it
wrong. It's a good idea to set this to whatever part of your domain you'd like to
share bandwidth and performance measurements across.<br>
If you have multiple domains, then you're out of luck. You'll just have to get
separate measurements across them.
</dd>
<dt>user_ip</dt>
<dd>
<strong>[recommended]</strong>
Despite its name, this is really a free-form string used to uniquely identify the user's
current internet connection. It's used primarily by the bandwidth test to determine
whether it should re-measure the user's bandwidth or just use the value stored in the
cookie. You may use IPv4, IPv6 or anything else that you think can be used to identify
the user's network connection.
</dd>
<dt>log</dt>
<dd>
<strong>[optional]</strong>
By default, boomerang will attempt to use the logger component from YUI if it finds it
or firebug if it finds that instead. If it finds neither, it will default to not
logging anything. You can define your own logger by setting the <code>log</code>
parameter to a function that logs messages.<br>
The signature of this function is:
<pre>
function log(oMessage, sLevel, sSource);
</pre>
Where:<dl>
<dt>oMessage</dt> <dd>is the object/message to be logged. It is up to you to decide how to log objects.<dd>
<dt>sLevel</dt> <dd>is the log level, with values of "error", "warn", "info" and "debug"</dd>
<dt>sSource</dt> <dd>is the source of the log message. This will typically be the string "boomerang" followed by the name of a plugin</dd>
</dl>
Note that you can completely disable logging by setting <code>log</code> to <code>null</code>.
</dd>
<dt>autorun</dt>
<dd>
<strong>[optional]</strong>
By default, boomerang runs automatically and attaches its <code>page_ready</code> handler to
the <code>window.onload</code> event. If you set <code>autorun</code> to <code>false</code>,
this will not happen and you will need to call <code>BOOMR.page_ready()</code> yourself.
</dd>
<dt><plugin_name><dt>
<dd>
Each plugin is configured through a sub-object of the config object. The key is the name
of the plugin. In the following sections we'll see how to configure our built-in plugins.
</dd>
</dl>
<pre>
BOOMR.init({
beacon_url: "http://beacons.yoursite.com/path/to/beacon.php",
site_domain: "yoursite.com",
user_ip: "202.54.1.18",
autorun: false
});
</pre>
<h2>Roundtrip plugin</h2>
<p>
All roundtrip plugin configuration items are under the <code>RT</code> namespace.
</p>
<dl>
<dt>cookie</dt>
<dd>
<strong>[optional]</strong>
The name of the cookie in which to store the start time for measuring page load time. The default name is <code>RT</code>.
Set this to a falsy value like <code>null</code> or the empty string to ignore cookies and depend completely on the
WebTiming API for the start time.
</dd>
<dt>cookie_exp</dt>
<dd>
<strong>[optional]</strong>
The lifetime in seconds of the roundtrip cookie. This only needs to live for as long as it takes for a single page to load.
Something like 10 seconds or so should be good for most cases, but to be safe, and to cover people with really slow
connections, or users that are geographically far away from you, keep it to a few minutes. The default is set to 10 minutes.
</dd>
<dt>strict_referrer</dt>
<dd>
<strong>[optional]</strong>
By default, boomerang will not measure a page's roundtrip time if the URL in the <code>RT</code> cookie doesn't match
the current page's <code>document.referrer</code>. This is so because it generally means that the user visited a
third page while their <code>RT</code> cookie was still valid, and this could render the page load time invalid.<br>
There may be cases, though, when this is a valid flow — for example, you have an SSL page in between and the
referrer isn't passed through. In this case, you'll want to set <code>strict_referrer</code> to <code>false</code>
</dd>
</dl>
<pre>
BOOMR.init({
beacon_url: "http://beacons.yoursite.com/path/to/beacon.php",
site_domain: "yoursite.com",
user_ip: "202.54.1.18",
autorun: false,
<em>RT: { </em>
<em> cookie: "MyRT", </em>
<em> cookie_exp: 120 </em>
<em>} </em>
});
</pre>
<h2>Bandwidth plugin</h2>
<p>
All bandwidth plugin configuration items are under the <code>BW</code> namespace.
</p>
<dl>
<dt>base_url</dt>
<dd>
<strong>[recommended]</strong>
By default, the bandwidth plugin looks for its bandwidth measurement images in the <code>images/</code> subdirectory
of the current directory. This may not be true for all pages on your site. You can set the <code>base_url</code>
parameter to the HTTP path of the directory that contains the bandwidth images. This can be an absolute or a relative
URL. If it's relative, remember that it's relative to the page that boomerang is included in and not to the javascript
file.
</dd>
<dt>cookie</dt>
<dd>
<strong>[optional]</strong>
The name of the cookie in which to store the measured bandwidth and latency of the user's network connection.
The default name is <code>BA</code>. See <a href="howto-3.html">Howto #3</a> for more details on the bandwidth cookie.
</dd>
<dt>cookie_exp</dt>
<dd>
<strong>[optional]</strong>
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.<br>
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.
</dd>
<dt>timeout</dt>
<dd>
<strong>[optional]</strong>
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.
</dd>
<dt>nruns</dt>
<dd>
<strong>[optional]</strong>
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 <code>timeout</code> value above.
</dd>
</dl>
<h2>All optional</h2>
<p>
All configuration parameters are optional, but not setting some of them can lead to unexpected or incomplete results,
so they should be set. It is, however, possible to get up and running by doing nothing more than putting your bandwidth
images in the right directory, including the code and calling <code>init()</code>.
</p>
<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>