12 | All boomerang utility functions are under the BOOMR.utils namespace.
13 | To access any of the following, dereference the BOOMR.utils object. eg: use BOOMR.utils.getCookie()
14 | to call the getCookie() method.
15 |
24 | Gets the value of the cookie identified by sName.
25 |
sName. This may be the empty string.null if the cookie wasn't found or if sName was empty.
36 | Sets the cookie named sName to the serialized value of oSubCookies.
37 |
null, it will
60 | use the value of site_domain that was configured during the call to BOOMR.init().
61 | You probably want to set this to null.
62 | 70 | Note that the entire cookie name and value needs to be less than 4000 characters. 71 |
72 | 73 |
75 | The BOOMR.plugins.RT plugin uses this function like this:
76 |
78 | if(!BOOMR.utils.setCookie(
79 | impl.cookie,
80 | { s: t_start, r: url },
81 | impl.cookie_exp,
82 | "/",
83 | null
84 | )) {
85 | BOOMR.error("cannot set start cookie", "rt");
86 | return this;
87 | }
88 |
89 |
90 | true if the cookie was set successfullyfalse if the cookie was not set successfully
100 | Parse a cookie string returned by getCookie() and split it into its constituent subcookies.
101 |
104 | The BOOMR.plugins.BW plugin calls this function like this:
105 |
107 | var cookies = BOOMR.utils.getSubCookies(BOOMR.utils.getCookie(impl.cookie)); 108 |109 |
null if sCookie was not set or did not contain valid subcookies.
119 | Removes the cookie identified by sName by nullifying its value, and making it a session cookie.
120 |
123 | Nothing useful. 124 |
125 |
130 | Convenience method that plugins can call to configure themselves with the config object passed in to their init()
131 | method.
132 |
init() method.BOOMR.plugins object.
150 | The BOOMR.plugins.RT plugin uses this method like this:
151 |
153 | BOOMR.utils.pluginConfig(impl, config, "RT", ["cookie", "cookie_exp", "strict_referrer"]); 154 |155 | 156 |
true if at least one property was set.false if no properties were set or if the oConfig object was not set.166 | The latest code and docs is available on github.com/lognormal/boomerang 167 |
168 | 169 | 170 | 171 | 175 | -------------------------------------------------------------------------------- /doc/api/BW.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |
12 | The bandwidth plugin measures the bandwidth and latency of the user's network connection to your
13 | server. The bandwidth API is encapsulated within the BOOMR.plugins.BW namespace.
14 |
18 | All bandwidth plugin configuration items are under the BW namespace.
19 | The full configuration object is described in Howto #6 — Configuring boomerang.
20 |
images/ subdirectory
26 | of the current directory. This may not be true for all pages on your site. You can set the base_url
27 | parameter to the HTTP path of the directory that contains the bandwidth images. This can be an absolute or a relative
28 | URL. If it's relative, remember that it's relative to the page that boomerang is included in and not to the javascript
29 | file.
30 | BA. See Howto #3 for more details on the bandwidth cookie.
37 | timeout value above.
68 | 80 | Called by the BOOMR.init() method to configure the bandwidth 81 | plugin. 82 |
83 |BOOMR.init(). See the Configuration section for details.
87 |
90 | a reference to the BOOMR.plugins.BW object, so you can chain methods.
91 |
97 | Starts the bandwidth test. This method is called automatically when boomerang's 98 | page_ready event fires, so you won't need to call it 99 | yourself. 100 |
101 |
103 | a reference to the BOOMR.plugins.BW object, so you can chain methods.
104 |
110 | Stops the bandwidth test immediately and attempts to calculate bandwidth and latency
111 | from values that it has already gathered. This method is called automatically if the
112 | bandwidth test times out. It is better to set the timeout value appropriately
113 | when calling the BOOMR.init() method.
114 |
117 | a reference to the BOOMR.plugins.BW object, so you can chain methods.
118 |
124 | Called by BOOMR.sendBeacon() to determine if the bandwidth plugin has 125 | finished what it's doing or not. 126 |
127 |true if the plugin has completed.false if the plugin has not completed.138 | This plugin adds the following parameters to the beacon: 139 |
140 |150 | The latest code and docs is available on github.com/lognormal/boomerang 151 |
152 | 153 | 154 | 155 | 159 | -------------------------------------------------------------------------------- /doc/api/DNS.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | Note: The DNS plugin hasn't been tested. Your help in testing it is appreciated. 13 |
14 |
15 | The DNS plugin measures the latency of DNS lookups from the user's browser to your server.
16 | The DNS API is encapsulated within the BOOMR.plugins.DNS namespace.
17 |
20 | Note that the DNS plugin requires some amount of server-side set up. See 21 | Howto #8 for details on how to set this up. 22 |
23 | 24 |31 | Called by the BOOMR.init() method to configure the DNS 32 | plugin. There is only one configurable option: 33 |
34 |base_url parameter tells the DNS plugin where it can find its DNS testing
39 | images. This URL must contain a wildcard character which will be replaced with a random
40 | string. The images will be appended to this string without any other modification. If you
41 | have any pages served over HTTPS, then this URL should be configured to work over HTTPS as
42 | well as HTTP. The protocol part of the URL will be automatically changed to fit the current
43 | document.
44 |
47 | BOOMR.init({
48 | DNS: {
49 | base_url: "http://*.yoursite.com/images/"
50 | }
51 | });
52 |
53 | 54 | In the above code, * will be replaced with a random string. 55 |
56 | 57 |
59 | a reference to the BOOMR.plugins.DNS object, so you can chain methods.
60 |
63 | The DNS test will not run if a base_url is not configured.
64 |
70 | Called by BOOMR.sendBeacon() to determine if the DNS plugin has 71 | finished what it's doing or not. 72 |
73 |true if the plugin has completed.false if the plugin has not completed.84 | This plugin adds the following parameter to the beacon: 85 |
86 |92 | The latest code and docs is available on github.com/lognormal/boomerang 93 |
94 | 95 | 96 | 97 | 101 | -------------------------------------------------------------------------------- /doc/api/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 |34 | The latest code and docs is available on github.com/lognormal/boomerang 35 |
36 | 37 | 38 | 39 | 43 | -------------------------------------------------------------------------------- /doc/api/ipv6.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | Note: The IPv6 plugin hasn't been tested. Your help in testing it is appreciated. 13 |
14 |
15 | The IPv6 plugin measures various IPv6 related metrics. It is encapsulated within
16 | the BOOMR.plugins.IPv6 namespace. This plugin tries to do a few things:
17 |
25 | This plugin needs a server that has an IPv6 address, and a DNS name to point to it. 26 | Additionally, the server needs to be configured to serve content requested 27 | from the IPv6 address and should not require a virtual host name. This means 28 | that you probably cannot use shared hosting that puts multiple hosts on the 29 | same IP address. 30 |
31 | 32 |34 | All configuration parameters are within the IPv6 namespace. 35 |
36 |http://fe80::1/image-i.png.
39 | If not specified, the test will abort.59 | Called by the BOOMR.init() method to configure the DNS 60 | plugin. See the Configuration section for details. 61 |
62 |
63 | BOOMR.init({
64 | IPv6: {
65 | ipv6_url: "http://fe80::1/images/image-i.png"
66 | host_url: "http://yoursite-6.com/images/image-i.png"
67 | }
68 | });
69 |
70 |
71 |
73 | a reference to the BOOMR.plugins.IPv6 object, so you can chain methods.
74 |
77 | The IPv6 test will not run if a ipv6_url is not configured.
78 |
84 | Called by BOOMR.sendBeacon() to determine if the IPv6 plugin has 85 | finished what it's doing or not. 86 |
87 |true if the plugin has completed.false if the plugin has not completed.
98 | This plugin adds two parameters to the beacon, both prefixed with ipv6_:
99 |
110 | The latest code and docs is available on github.com/lognormal/boomerang 111 |
112 | 113 | 114 | 115 | 119 | -------------------------------------------------------------------------------- /doc/api/navtiming.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | Note: The Navigation Timing plugin hasn't been tested. Your help in testing it is appreciated. 13 |
14 |
15 | The Navigation Timing plugin collects metrics collected by modern user agents that support the
16 | W3C Navigation Timing specification. The Navigation
17 | Timing API is encapsulated within the BOOMR.plugins.NavigationTiming namespace.
18 |
21 | Note that the Navigation Timing plugin isn't included by default in boomerang.js. See 22 | Howto #9 for details on how to include the plugin in your boomerang 23 | deployment. 24 |
25 | 26 |
33 | Called by the BOOMR.init() method to configure the Navigation Timing
34 | plugin. The Navigation Timing plugin doesn't require any configuration parameters, since it simply
35 | reads values out of the browser's window.performance object (if available) and adds them to the
36 | beacon query string.
37 |
41 | a reference to the BOOMR.plugins.NavigationTiming object, so you can chain methods.
42 |
45 | If the user agent being examined doesn't implement the Navigation Timing spec, the plugin won't 46 | add any parameters to the beacon. 47 |
48 |53 | Called by BOOMR.sendBeacon() to determine 54 | if the Navigation Timing plugin has finished what it's doing or not. 55 |
56 |true if the plugin has completed.false if the plugin has not completed.67 | The NavigationTiming plugin adds the following parameters to the beacon. Each maps onto a attribute from the 68 | browser's NavigationTiming API. 69 |
70 || Beacon parameter | 73 |NavigationTiming attribute | 74 |
|---|---|
nt_red_cnt | window.performance.navigation.redirectCount |
nt_nav_type | window.performance.navigation.type |
nt_nav_st | window.performance.timing.navigationStart |
nt_red_st | window.performance.timing.redirectStart |
nt_red_end | window.performance.timing.redirectEnd |
nt_fet_st | window.performance.timing.fetchStart |
nt_dns_st | window.performance.timing.domainLookupStart |
nt_dns_end | window.performance.timing.domainLookupEnd |
nt_con_st | window.performance.timing.connectStart |
nt_con_end | window.performance.timing.connectEnd |
nt_req_st | window.performance.timing.requestStart |
nt_res_st | window.performance.timing.responseStart |
nt_res_end | window.performance.timing.responseEnd |
nt_domloading | window.performance.timing.domLoading |
nt_domint | window.performance.timing.domInteractive |
nt_domcontloaded_st | window.performance.timing.domContentLoadedEventStart |
nt_domcontloaded_end | window.performance.timing.domContentLoadedEventEnd |
nt_domcomp | window.performance.timing.domComplete |
nt_load_st | window.performance.timing.loadEventStart |
nt_load_end | window.performance.timing.loadEventEnd |
nt_unload_st | window.performance.timing.unloadEventStart |
nt_unload_end | window.performance.timing.unloadEventEnd |
nt_ssl_st | [optional] window.performance.secureConnectionStart |
101 | The latest code and docs is available on github.com/lognormal/boomerang 102 |
103 | 104 | 105 | 106 | 110 | -------------------------------------------------------------------------------- /doc/boomerang-docs.css: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2011, Yahoo! Inc. All rights reserved. 3 | * Copyrights licensed under the BSD License. See the accompanying LICENSE.txt file for terms. 4 | */ 5 | 6 | body { font-size: 0.9em; background-color: #eeeee4; padding: 5% 10% 15% 10%; margin: 0; font-family: "Trebuchet MS",Trebuchet,Tahoma,Verdana,Sans-Serif; } 7 | a { color: #571; } 8 | a:hover, a:active { color: #350; } 9 | h1 { padding-left: .8in; text-indent: -.8in; } 10 | h2, h2 a, h3, h3 a, h4, h4 a { color:#793; } 11 | 12 | p#results { background-color: #ffa; border: solid 2px #d82; padding: 1em; position: absolute; width: 25%; overflow: hidden; white-space: pre;} 13 | p#results:hover { width: auto; } 14 | div#dynamic-content { font-size: 0.5em; border: solid 3px #9a5; padding: 1em; margin: 1em 10% 1em 40%; text-align: justify; color: #9a8; } 15 | div#dynamic-content > p:first-child { font-size: 2em; } 16 | 17 | dd strong { color: #a43; background-color: #ddc; } 18 | dd h3 { color: black; margin-left: -0.8em; } 19 | 20 | dl.api {border-bottom: solid 1px #aaa; } 21 | dl.api > dt { font-weight: bolder; border-top: solid 1px #aaa; padding: 3px; } 22 | dl.api > dd { font-size: 0.9em; color: #222; } 23 | dl.api > dd > ul { padding-bottom: 0.5em; } 24 | 25 | p.perma-link { margin-top: 4em; font-size: 0.9em; } 26 | 27 | pre { line-height:1.4em; font-size: 1.1em; margin-right: 4%; padding: 1em 1em 1em 1.5em; background-color: #bba; border-left: solid 5px #9a5; } 28 | pre em { background-color: #ccb; color: #a32; font-style: normal; padding: 2px;} 29 | pre span.comment { background-color: #ccb; color: #56a; padding: 2px;} 30 | 31 | pre span.ni { color: #886; } 32 | 33 | a.fn { position: relative; top: -0.4em; font-size: 0.7em; text-decoration: none; } 34 | #footnotes { font-size: 0.8em; width: 50%; text-align: justify; border-top: solid 1px #888; padding-right: 0.5em; margin: 3em 0 0 0;} 35 | #footnotes li { margin-bottom: 0.8em; } 36 | -------------------------------------------------------------------------------- /doc/community.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 |12 | boomerang is an opensource javascript library released under the BSD license. 13 | It depends on its community to keep it alive. 14 |
15 | 16 |18 | The source code is on github at github.com/lognormal/boomerang. Feel 19 | free to fork it and contribute to it. You can also get a tarball 20 | or zip archive of the code. 21 |
22 | 23 |25 | Use github's issue tracking system to report or follow bugs or to 26 | discuss features and get support. 27 |
28 | 29 |31 | Other opensource devs have incorporated boomerang into their own projects. The following is a partial list: 32 |
33 |13 | This use case is based on Google Chrome's prerender 14 | capabilities introduced with Chrome 13. The code to include on a page is the same regardless 15 | of whether you use prerender or not, so this howto will not cover that. However, to enable 16 | prerendering of a particular page, you include that page's URL as a link element in the current 17 | document. For example, we include this code in the HEAD of the current page: 18 |
19 |20 | <link rel="prerender" href="howto-10-page%232.html"> 21 |22 |
23 | This tells Chrome to prefetch howto-10-page#2.html and all its assets, and to
24 | start rendering it in the background, invisible to the user. When the user eventually clicks
25 | on a link to that document, it should show up immediately.
26 |
28 | As performance concious engineers, however, we'd like to know how long it all took. In 29 | particular, the numbers we care about are: 30 |
31 |38 | Let's hope you've spent enough time reading this page to allow page#2's rendering to complete. 39 |
40 | 41 |42 | Go to Page #2 now to see the results of the page load test. 43 |
44 | 45 |46 | The latest code and docs is available on github.com/lognormal/boomerang 47 |
48 | 49 |50 |
51 | 52 | 53 | 54 | 64 | 65 | 66 | 70 | -------------------------------------------------------------------------------- /doc/howtos/howto-10-page#2.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | This use case is based on Google Chrome's prerender 13 | capabilities introduced with Chrome 13. We use two pages for this use case. This is page #2 of the 14 | example. See Page #1 for the full explanation. 15 |
16 | 17 |18 | If you clicked the link to this page from Page #1, you should see 19 | page performance results show up below. It may take a while if this is the first time you're doing 20 | the test since testing your bandwidth takes about 6 seconds. You can also click the link to Page #1 21 | to see the same output on Page #1. 22 |
23 | 24 |25 | In the box below, if rt.start is set to cookie, you should see the following numbers: 26 |
27 |34 | If rt.start is set to navigation (or something else), then t_done is the same as t_prerender. If t_prerender is not set, then this 35 | page wasn't prerendered, and t_done is the actual perceived load time. 36 |
37 | 38 |39 | The latest code and docs is available on github.com/lognormal/boomerang 40 |
41 | 42 |43 |
44 | 45 | 46 | 47 | 57 | 58 | 59 | 63 | -------------------------------------------------------------------------------- /doc/howtos/howto-1a-page#1.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | See use case #1 for a description of this requirement. 13 |
14 |15 | We use two pages for this use case. They may be any two pages on your site, and the code you put into them 16 | is identical, so you could just put it on all pages on your site. Assuming you're starting out with nothing, 17 | this is what you do: 18 |
19 |
24 | <script src="boomerang.js" type="text/javascript"></script>
25 | <script type="text/javascript">
26 | BOOMR.init({
27 | user_ip: "<user's ip address>",
28 | beacon_url: "http://yoursite.com/path/to/beacon.php"
29 | });
30 | </script>
31 |
32 | 33 | This should be sufficient to measure page load time on all but the very first page that a user visits on 34 | your site. You'll need to get the user's IP address using some server-side programming 35 | language like PHP, Python or C#. This is necessary in order to save bandwidth calculations 36 | across requests, and makes it a little easier on your users. 37 |
38 | 39 |40 | Go to Page #2 now to see the results of the page load test. 41 |
42 | 43 |
45 | If you've been doing this website thing for a while, chances are that you use a CDN
46 | to host your javascript, and have several subdirectories with pages. If you do that,
47 | then change the link to boomerang.js above to point to the absolute location
48 | of that file. You will also need to tell boomerang where to find its bandwidth testing
49 | images. Your init() call will then change to this:
50 |
52 | BOOMR.init({
53 | user_ip: "<user's ip address>",
54 | beacon_url: "http://yoursite.com/path/to/beacon.php",
55 | BW: {
56 | base_url: "http://yoursite.com/path/to/bandwidth/images/"
57 | }
58 | });
59 |
60 | 61 | Note, that you point to the image directory. It is recommended that you put these 62 | images on a server that you want to measure the user's bandwidth and latency to. 63 | In most cases this will be your own server, however, there may be cases where you'd 64 | want to put them on a CDN and measure bandwidth and latency to those servers instead. 65 | This decision is left up to you. We recommend putting them on your own server. 66 |
67 | 68 |69 | Go to Page #2 now to see the results of the page load test. 70 |
71 | 72 |73 | The latest code and docs is available on github.com/lognormal/boomerang 74 |
75 | 76 |77 |
78 | 79 | 80 | 81 | 93 | 94 | 95 | 99 | -------------------------------------------------------------------------------- /doc/howtos/howto-1a-page#2.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | See use case #1 for a description of this requirement. 13 |
14 |15 | We use two pages for this use case. This is page #2 of the example. See Page #1 16 | for full explanation. 17 |
18 | 19 |20 | If you clicked the link to this page from Page #1, you should see 21 | page performance results show up below. It may take a while if this is the first time you're doing 22 | the test since testing your bandwidth takes about 6 seconds. You can also click the link to Page #1 23 | to see the same output on Page #1. 24 |
25 | 26 |27 | The latest code and docs is available on github.com/lognormal/boomerang 28 |
29 | 30 |31 |
32 | 33 | 34 | 35 | 47 | 48 | 49 | 53 | -------------------------------------------------------------------------------- /doc/howtos/howto-1b-page#1.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | See use case #1 for a description of this requirement. 13 |
14 |
15 | We use two pages for this use case. They may be any two pages on your site, and the code you put into them
16 | is identical, so you could just put it on all pages on your site. Unlike case 1a, in this case, we do not
17 | allow the beacon to fire when the onload event fires. Instead, we fire the page_ready event
18 | when we determine that the page is ready. We also set the autorun parameter to false to stop
19 | boomerang from running automatically.
20 |
26 | <script src="boomerang.js" type="text/javascript"></script>
27 | <script type="text/javascript">
28 | BOOMR.init({
29 | user_ip: "<user's ip address>",
30 | beacon_url: "http://yoursite.com/path/to/beacon.php",
31 | autorun: false
32 | });
33 | </script>
34 |
35 |
36 | The rest of your page will load normally. When you determine (through javascript, perhaps) that your
37 | page is usable by a user browsing your website, you need to fire the page_ready event like this:
38 |
41 | BOOMR.page_ready(); // Tell boomerang that the page is now usable 42 |43 | 44 |
45 | As in howto-1a, you need to populate the user_ip field using a back end programming language.
46 |
49 | Go to Page #2 now to see the results of the page load test. 50 |
51 | 52 |53 | The latest code and docs is available on github.com/lognormal/boomerang 54 |
55 | 56 |57 |
58 | 59 | 60 | 61 | 77 | 78 | 79 | 83 | -------------------------------------------------------------------------------- /doc/howtos/howto-1b-page#2.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | See use case #1 for a description of this requirement. 13 |
14 |15 | We use two pages for this use case. This is page #2 of the example. See Page #1 16 | for full explanation. 17 |
18 | 19 |
20 | If you clicked the link to this page from Page #1, you should see
21 | page performance results show up below. We introduce an artificial delay of 750ms to show how you can
22 | fire the page_ready event after the page has loaded. It may take a while if this is the
23 | first time you're doing the test since testing your bandwidth takes about 6 seconds. You can also click
24 | the link to Page #1 to see the same output on Page #1.
25 |
28 | The latest code and docs is available on github.com/lognormal/boomerang 29 |
30 | 31 |32 |
33 | 34 | 35 | 36 | 52 | 53 | 54 | 58 | -------------------------------------------------------------------------------- /doc/howtos/howto-2.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | See use case #2 for a description of this requirement. 13 |
14 |15 | This document attempts to load some content using XHR and measures the time it took to load that 16 | content using boomerang. This is how you do it: 17 |
18 |
23 | <script src="boomerang.js" type="text/javascript"></script>
24 | <script type="text/javascript">
25 | BOOMR.init({
26 | user_ip: "<user's ip address>",
27 | beacon_url: "http://yoursite.com/path/to/beacon.php",
28 | auto_run: false
29 | });
30 | </script>
31 |
32 |
33 |
34 | Next fetch your content. Right before the call to fetch content, start the timer. The load time timer is called
35 | t_done. In the callback function where the content has been fetched, call the done()
36 | method. This measures and beacons back the response time. I use YUI 3 in the code below, but you could use
37 | anything you like.
38 |
41 | YUI().use("io-base", function(Y) {
42 | var uri = "dynamic-content.txt";
43 |
44 | function complete(id, o) {
45 | var html = o.responseText;
46 | document.getElementById("dynamic-content").innerHTML = html;
47 | BOOMR.plugins.RT.done(); // Tell boomerang to measure time and fire a beacon
48 | };
49 |
50 | Y.on('io:complete', complete);
51 |
52 | BOOMR.plugins.RT.startTimer("t_done"); // Start measuring download time
53 | var request = Y.io(uri);
54 | });
55 |
56 |
57 | 58 | The latest code and docs is available on github.com/lognormal/boomerang 59 |
60 | 61 |62 |
63 | 64 |12 | See use cases #3 & #5 for a description of this requirement. 13 |
14 | 15 |
16 | By default, boomerang always measures the user's bandwidth and HTTP latency and adds these numbers to the beacon
17 | that it sends back. In reality, the bandwidth plugin (BOOMR.plugins.BW) does this, but since that's
18 | bundled along with boomerang, the difference is purely academic. There are a few things you need to know in order
19 | to use the bandwidth detection code effectively.
20 |
23 | First, bandwidth detection through javascsript is not accurate. If the user's network is lossy or is shared with 24 | other users, or network traffic is bursty, real bandwidth can vary over time. The measurement we take is based 25 | over a short period of time, and this may not be representative of the best or worst cases. We try to cover for 26 | that by measuring not just the bandwidth, but also the error value in that measurement. 27 |
28 | 29 |
30 | Simply adding boomerang to a page and calling the init() method is sufficient to start the bandwidth
31 | test and beacon its results back to the server. This is the code you'd use:
32 |
34 | <script src="boomerang.js" type="text/javascript"></script>
35 | <script type="text/javascript">
36 | BOOMR.init({
37 | beacon_url: "http://yoursite.com/path/to/beacon.php",
38 | BW: {
39 | base_url: "http://base_url/to/bandwidth/images/"
40 | }
41 | });
42 | </script>
43 |
44 |
45 | The default value of the BW.base_url parameter is images/, so if your bandwidth detection
46 | images are placed in a subdirectory of the current directory called images, then you do not need
47 | to set the BW.base_url parameter. It is a good practice though, as you might have pages in multiple
48 | directories.
49 |
52 | Now while this is the minimum code required to measure bandwidth and latency and have it beaconed back, it isn't
53 | the best option for your user. The test will run every time the user visits a page on your site even though
54 | their bandwidth probably hasn't changed (apart from regular fluctuations). It's far better to store the bandwidth
55 | 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
56 | user moves between several networks, eg: a laptop used at home, at work and at a coffee shop. The bandwidth and
57 | latency at these locations may be different, and it's necessary to measure them separately. We detect a change
58 | in network through the user's IP address, so in order to store the user's bandwidth in a cookie, you will need
59 | to tell boomerang what the user's IP address is. You do this through the user_ip parameter.
60 |
63 | <script src="boomerang.js" type="text/javascript"></script>
64 | <script type="text/javascript">
65 | BOOMR.init({
66 | beacon_url: "http://yoursite.com/path/to/beacon.php",
67 | user_ip: "<user's ip>",
68 | BW: {
69 | base_url: "http://base_url/to/bandwidth/images/"
70 | }
71 | });
72 | </script>
73 |
74 |
75 | 76 | 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 77 | side and write the value into your code. 78 |
79 | 80 |82 | 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 83 | IP address. This helps if users use DHCP on the same ISP where their IP address changes frequently, but they stay 84 | within the same subnet. If the user has an IPv6 address, we use the entire address. 85 |
86 | 87 |
89 | You may want to customise the name of the cookie where the bandwidth will be stored. By default this is
90 | set to BA, but you can change it using the BW.cookie parameter.
91 |
94 | <script src="boomerang.js" type="text/javascript"></script>
95 | <script type="text/javascript">
96 | BOOMR.init({
97 | beacon_url: "http://yoursite.com/path/to/beacon.php",
98 | user_ip: "<user's ip>",
99 | BW: {
100 | base_url: "http://base_url/to/bandwidth/images/",
101 | cookie: "BW"
102 | }
103 | });
104 | </script>
105 |
106 |
107 |
108 | This cookie is set to expire in 7 days. You can change its lifetime using the BW.cookie_exp parameter.
109 | The value is in seconds. During that time, you can also read the value of the cookie on the server side. Its
110 | format is as follows:
111 |
114 | BA=ba=nnnnnnn&be=nnn.nn&l=nnnn&le=nn.nn&ip=iiiiii&t=sssssss; 115 |116 |
117 | The parameters are defined as: 118 |
119 |user_ip parameter to the init() method135 | These parameters are also sent in the beacon (See HOWTO #0), but having them in the 136 | cookie means that you can customise your users experience based on the bandwidth before you serve a request. 137 |
138 | 139 |141 | Finally, there may be cases when you want to completely disable the bandwidth test. Perhaps you know that 142 | your user is on a slow network, or pays by the byte (the bandwidth test uses a lot of bandwidth), or is on 143 | a mobile device that cannot handle the load. In such cases you have two options. 144 |
145 |BW.enabled parameter to false:
150 | <script src="boomerang.js" type="text/javascript"></script>
151 | <script type="text/javascript">
152 | BOOMR.init({
153 | BW: { enabled: false }
154 | });
155 | </script>
156 |
157 |
158 | 159 | The latest code and docs is available on github.com/lognormal/boomerang 160 |
161 | 162 |163 |
164 | 165 | 166 | 167 | 179 | 180 | 181 | 185 | -------------------------------------------------------------------------------- /doc/howtos/howto-4.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 7 | 8 | 22 |34 | See use case #4 for a description of this requirement. 35 |
36 |
37 | Up until now we've measured the time it takes for a page to become usable by the user. It may also be
38 | useful to measure the time it took for various components within the page to load and match that up with
39 | the full page load time. boomerang provides additional timers that you can configure to measure separate
40 | parts of your page. You use the startTimer() and endTimer() methods of the
41 | roundtrip (BOOMR.plugin.RT) plugin to do this.
42 |
45 | In the following examples, you'll need to make sure that boomerang.js is loaded and the
46 | init() method called before you call any of these methods, so perhaps putting it at the
47 | top of your page is a good idea. We'll see later how to work around this.
48 |
51 | First, identify sections of your page that you want to measure. Call startTimer() before
52 | and endTimer() after. Each timer has its own name. The names are free-form strings,
53 | but stay simple to be efficient. Stick to alphanumeric characters and underscores, and limit names
54 | to around 5 characters, eg: t_ads, t_head, t_js. The following
55 | names are reserved: t_done, t_page, t_resp.
56 |
59 | Make sure you've included boomerang.js before starting the timers. 60 |
61 | 62 |
63 | <html>
64 | <head>
65 | <script src="boomerang.js" type="text/javascript"></script>
66 | <script type="text/javascript">
67 | BOOMR.init({
68 | beacon_url: "http://yoursite.com/path/to/beacon.php"
69 | });
70 | BOOMR.plugins.RT.startTimer("t_head");
71 | </script>
72 | <title>page title</title>
73 | <meta http-equiv="Content-type" content="text/html; charset=utf-8">
74 | <link rel="stylesheet" type="text/css" href="../boomerang-docs.css">
75 | <script type="text/javascript">
76 | BOOMR.plugins.RT.endTimer("t_head").startTimer("t_body");
77 | </script>
78 | </head>
79 | <body>
80 | page body here
81 | <script type="text/javascript">
82 | BOOMR.plugins.RT.endTimer("t_body");
83 | </script>
84 | </body>
85 | </html>
86 |
87 |
88 |
89 | Your timers will now be included in the beacon along with t_done.
90 |
93 | Notice in the second invocation how we chain the calls to endTimer and startTimer.
94 | This is possible for most methods that you call since they return a reference to the object. Note
95 | that the timer methods are run on the BOOMR.plugins.RT object, so they return a reference
96 | to that object and not to the BOOMR object.
97 |
101 | Now we've said for years that putting javascript at the bottom of your document is good for
102 | performance, so asking you to load boomerang at the top may not be the best advice. You can
103 | still measure in-page times though, and then report them to boomerang once it has loaded.
104 | You do this using the BOOMR.plugins.RT.setTimer() method. This method takes
105 | two parameters — the timer name and its value in milliseconds. The code above will
106 | change to this:
107 |
110 | <html>
111 | <head>
112 | <script type="text/javascript">
113 | var t_pagestart=new Date().getTime();
114 | </script>
115 | <title>page title</title>
116 | <meta http-equiv="Content-type" content="text/html; charset=utf-8">
117 | <script type="text/javascript">
118 | var t_headend = new Date().getTime();
119 | </script>
120 | </head>
121 | <body>
122 | page body here
123 | <script type="text/javascript">
124 | var t_jsstart = new Date().getTime();
125 | </script>
126 | <script src="boomerang.js" type="text/javascript"></script>
127 | <script type="text/javascript">
128 | BOOMR.init({
129 | beacon_url: "http://yoursite.com/path/to/beacon.php"
130 | });
131 | var t_bodyend = new Date().getTime();
132 | BOOMR.plugins.RT.setTimer("t_head", t_headend - t_pagestart).
133 | setTimer("t_body", t_bodyend - t_headend).
134 | setTimer("t_js", t_bodyend - t_jsstart);
135 | </script>
136 | </body>
137 | </html>
138 |
139 |
140 | 141 | The latest code and docs is available on github.com/lognormal/boomerang 142 |
143 | 144 |145 |
146 | 149 | 150 | 153 | 154 | 155 | -------------------------------------------------------------------------------- /doc/howtos/howto-5.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | See use case #5 for a description of this requirement. 13 |
14 |
15 | There will be several occassions when you need to add more information to the beacon that's sent
16 | back to the server. For example, you may want to tag the beacon with a page_id or
17 | you may want to do A/B testing and tag the beacon with a parameter specifying which bucket this
18 | beacon is for. You can achieve all this using the BOOMR.addVar() method.
19 |
22 | Before you use this method, remember that each plugin adds its own parameters and you shouldn't 23 | overwrite these with your own values. See Howto #0 for a list of 24 | parameters set by boomerang's built-in plugins. Other plugins may add their own parameters, 25 | consult the documentation of the plugin to find out what these are. 26 |
27 | 28 |
29 | BOOMR.addVar("page_id", 123);
30 |
31 |
32 | 33 | The parameter name must be a string. We recommend only using alphanumeric characters and underscores, 34 | but you can really use anything you like. Parameter values may only be numbers or strings, ie, 35 | something that you can put into a URL. 36 |
37 | 38 |39 | If you need to set multiple parameters, you can pass in an object instead: 40 |
41 | 42 |
43 | BOOMR.addVar({
44 | "bucket": "test#1",
45 | "page_id": 123
46 | });
47 |
48 |
49 |
50 | Make sure you've included boomerang.js before calling BOOMR.addVar().
51 |
55 | The beacon will include all variables that you add in the URL. Both keys and values will be 56 | URI encoded. Your back end application will need to understand the passed in parameters. 57 |
58 | 59 |60 | http://yoursite.com/path/to/beacon.php?bucket=test%231&page_id=123&t_done=..... 61 |62 | 63 |
65 | You can also remove a parameter that you've added (or that a plugin has added) from the beacon.
66 | To do this, call the BOOMR.removeVar() method. This method takes in a list of
67 | name, and removes all of them from the parameter list. Any name that isn't in the parameter
68 | list is ignored.
69 |
72 | // don't send the stooges to the server
73 | BOOMR.removeVar("larry", "moe", "curly");
74 |
75 |
76 |
78 | You can also this as a crude way to prevent the beacon from firing. Inside your before_beacon
79 | event handler, simply remove all parameters.
80 |
83 | BOOMR.subscribe('before_beacon', function(o) {
84 | var p_names = [], k;
85 |
86 | if( "t_done" in o ) {
87 | return;
88 | }
89 |
90 | // t_done is not set, so don't beacon
91 | for(k in o) {
92 | if(o.hasOwnProperty(k)) {
93 | p_names.push(k);
94 | }
95 | }
96 |
97 | // removeVar accepts either a list or an array
98 | BOOMR.removeVar(p_names);
99 | });
100 |
101 |
102 | 103 | The latest code and docs is available on github.com/lognormal/boomerang 104 |
105 | 106 |107 |
108 | 109 | 110 | 126 | 127 | 128 | -------------------------------------------------------------------------------- /doc/howtos/howto-7.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | See use case #9 for a description of this requirement. 13 |
14 | 15 |16 | There are two types of beacon abuse you may need to protect against: 17 |
18 |25 | There's nothing you can do in javascript to prevent denial of service attacks, but you can configure 26 | your server to rate limit beacons originating from a single IP. You typically shouldn't be receiving 27 | beacons faster than a user can open websites. You'll also want to do some operating system/web server 28 | level configurations to detect abusive access patterns. The majority of these are beyond the scope of 29 | this document, but we have a few tips on building your beaconing back end to protect you from an attack. 30 |
31 | 32 |
33 | Most developers will create a back end script that they use as the beacon_url parameter
34 | of boomerang. The problem here is that since these requests cannot be cached, this script will run
35 | on every beacon request, and will consume web server resources, and probably database resources on
36 | every request. During a denial of service attack, this can bring your servers down.
37 |
40 | A better way to handle it is to have a lightweight web server running on your beaconing server, and
41 | have this server configured to only respond to requests for the beacon URL. It should send back a
42 | HTTP 204 response to all beacon requests. This is easy enough to configure within the
43 | server and means that it doesn't have to do a disk lookup for any request. The server will still
44 | write the request to its access logs, and this should include all query string parameters and cookies.
45 |
48 | Periodically - say once an hour or once a day (depending on the volume of beacons), you can batch process 49 | your logs and figure out your actual beacon parameters from there, discarding any obviously fake or 50 | abusive beacons. The actual code to extract data from a beacon is the same regardless of whether you 51 | do it on every request or as a batch. See Howto #0 for more information 52 | on extracting data from a beacon. 53 |
54 | 55 |56 | There's much 57 | more 58 | information online about DoS attacks 59 | and how to protect yourself from them. 60 |
61 | 62 |64 | The most common reason for this kind of abuse is that someone really liked your page design and copied 65 | it to their own server, including the boomerang javascript, only they didn't update the beacon_url, 66 | so it still beacons to your server. You probably don't want this. 67 |
68 | 69 |70 | The easiest way to fix this is to just check the referrer of all requests and block any that don't 71 | come from your own domain. This works for the clueless abuser case, but not for the intentional 72 | abuser. 73 |
74 | 75 |
76 | The intentional abuser is someone who will try to exploit all URLs to your site just to see if they
77 | can get something out of it. What they try isn't really important. There's only one legitimate way
78 | of using your beacon, and you should block all other uses. The best way to do this is through a
79 | nonce or a
80 | crumb.
81 | This is a string that is valid for one use only. It probably includes the current timestamp and a
82 | validity period as part of its hash. You generate it on every page requests and add it to boomerang
83 | using the BOOMR.addVar() method. On your beacon server, you then validate the nonce
84 | before accepting the beacon. If you're batch processing, you'd use the timestamp of the request and
85 | not the time that you're running the batch job in order to validate the nonce.
86 |
89 | BOOMR.addVar("nonce", "125a7b79de989876cce970f0768a07"); // your nonce will be different
90 |
91 |
92 | 93 | While the nonce can protect you from someone hitting your beacon URL directly, it does mean that your 94 | main page cannot be cached, since the nonce will change on every request. 95 |
96 | 97 |98 | The nonce also doesn't protect you from someone pulling the beacon out of your page — with a valid 99 | nonce, then modifying the beacon parameters and sending it off to your server. Protecting against this 100 | requires you to sign the parameters in the beacon, but this isn't something that you can do in javascript. 101 | I do not know of a general purpose solution to this problem. 102 |
103 | 104 |105 | The latest code and docs is available on github.com/lognormal/boomerang 106 |
107 | 108 |109 |
110 | 111 | 112 | 113 | 125 | 126 | 127 | -------------------------------------------------------------------------------- /doc/howtos/howto-8.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | See use case #7 for a description of this requirement. 13 |
14 |15 | Note: The DNS plugin hasn't been tested. Your help in testing it is appreciated. 16 |
17 |18 | Measuring DNS requires some server-side set up. The entire set up was 19 | documented in detail 20 | by Yahoo! engineer Carlos Bueno, so go read his post for everything you'll need to set 21 | this up. In brief, the points he covers are: 22 |
23 |A.gif
27 | and B.gif (from the images/ subdirectory) as fast as possible.
28 | Make sure that KeepAlive, Nagle, and any caching headers are turned off.dns.js along with boomerang.js (you can just concatenate the two
30 | files)35 | Steps 1 and 2 are complicated, and if you don't have full control over your DNS server (eg: you use 36 | Dreamhost), then it may be impossible for you to do this. If you can go forward, read on. 37 |
38 | 39 |40 | To configure the plugin, you only need to tell it where to get its images from. Unlike the bandwidth 41 | plugin though, this URL needs a wildcard: 42 |
43 |
44 | <script src="boomerang.js" type="text/javascript"></script>
45 | <script src="dns.js" type="text/javascript"></script> <!-- concatenate with boomerang.js for better performance -->
46 | <script type="text/javascript">
47 | BOOMR.init({
48 | user_ip: "<user's ip address>",
49 | beacon_url: "http://yoursite.com/path/to/beacon.php",
50 | DNS: {
51 | base_url: "http://*.yoursite.com/images/"
52 | }
53 | });
54 | </script>
55 |
56 |
57 | 58 | If you've set things up correctly, this should measure your DNS latency within a margin of error. 59 | We could run the test multiple times to find out what this error is, but for now we'll just do 60 | it once. 61 |
62 | 63 |64 | The latest code and docs is available on github.com/lognormal/boomerang 65 |
66 | 67 |68 |
69 | 70 | 71 | 72 | 84 | 85 | 86 | -------------------------------------------------------------------------------- /doc/howtos/howto-9.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |The W3C Navigation Timing API is an interface implemented by modern browsers that 13 | provides broad and deep data related to the performance of page loads. At the time 14 | of this writing, it is supported by the following browsers:
15 | 16 |The navtiming.js plugin doesn't require any configuration options as it simply 23 | reads data out of the browser (if available) and adds it to the beacon query 24 | string.
25 | 26 |You will have to build your own version of boomerang.js since it
27 | isn't one of the default plugins. To do this, run make in the
28 | boomerang directory with the following option:
31 | make PLUGINS=navtiming.js 32 |33 | 34 |
Then you can include the new boomerang file (don't forget to run it through 35 | your favorite Javascript minifier first) as you normally would.
36 | 37 |The new query parameters and the browser attributes they map 38 | to are shown below. More information about the definition of each attribute can be found 39 | in the W3C Navigation Timing specification.
40 | 41 || Boomerang beacon parameter | 44 |Navigation Timing attribute | 45 |
|---|---|
nt_red_cnt | window.performance.navigation.redirectCount |
nt_nav_type | window.performance.navigation.type |
nt_nav_st | window.performance.timing.navigationStart |
nt_red_st | window.performance.timing.redirectStart |
nt_red_end | window.performance.timing.redirectEnd |
nt_fet_st | window.performance.timing.fetchStart |
nt_dns_st | window.performance.timing.domainLookupStart |
nt_dns_end | window.performance.timing.domainLookupEnd |
nt_con_st | window.performance.timing.connectStart |
nt_con_end | window.performance.timing.connectEnd |
nt_req_st | window.performance.timing.requestStart |
nt_res_st | window.performance.timing.responseStart |
nt_res_end | window.performance.timing.responseEnd |
nt_domloading | window.performance.timing.domLoading |
nt_domint | window.performance.timing.domInteractive |
nt_domcontloaded_st | window.performance.timing.domContentLoadedStart |
nt_domcontloaded_end | window.performance.timing.domContentLoadedEnd |
nt_domcomp | window.performance.timing.domComplete |
nt_load_st | window.performance.timing.loadEventStart |
nt_load_end | window.performance.timing.loadEventEnd |
nt_unload_st | window.performance.timing.unloadEventStart |
nt_unload_end | window.performance.timing.unloadEventEnd |
71 | The latest code and docs is available on github.com/lognormal/boomerang 72 |
73 | 74 |75 |
76 | 77 | 78 | 79 | 91 | 92 | 93 | -------------------------------------------------------------------------------- /doc/howtos/howtos.js: -------------------------------------------------------------------------------- 1 | // Since we don't set a beacon_url, we'll just subscribe to the before_beacon function 2 | // and print the results into the browser itself. 3 | BOOMR.subscribe('before_beacon', function(o) { 4 | var html = "", t_name, t_other, others = []; 5 | 6 | if(!o.t_other) o.t_other = ""; 7 | 8 | for(var k in o) { 9 | if(!k.match(/^(t_done|t_other|bw|lat|bw_err|lat_err|u|r2?)$/)) { 10 | if(k.match(/^t_/)) { 11 | o.t_other += "," + k + "|" + o[k]; 12 | } 13 | else { 14 | others.push(k + " = " + o[k]); 15 | } 16 | } 17 | } 18 | 19 | if(o.t_done) { html += "This page took " + o.t_done + " ms to load12 | The following is a list of all items identified in the use case document and then some. 13 |
14 |36 | The latest code and docs is available on github.com/lognormal/boomerang 37 |
38 | 39 | 40 | 43 | 44 | 45 | -------------------------------------------------------------------------------- /doc/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 |12 | boomerang always comes back, except when it hits something. 13 |
14 |16 | boomerang is a piece of javascript that you add to your web pages, where it measures 17 | the performance of your website from your end user's point of view. It has the ability 18 | to send this data back to your server for further analysis. With boomerang, you find 19 | out exactly how fast your users think your site is. 20 |
21 |22 | boomerang is opensource and released under the BSD license, 23 | and we have a whole bunch of documentation about it. 24 |
25 |37 | boomerang comes to you from the Exceptional Performance 38 | team at Yahoo!, aided by the Yahoo! 39 | Developer Network. 40 |
41 |
12 | 全てのユーティリティ関数は名前空間 BOOMR.utils のもとに定義されています。以降のメソッドにアクセスするには BOOMR.utils オブジェクトを参照してください。例: getCookie() メソッドを呼び出すには BOOMR.utils.getCookie() を使用します。
13 |
22 | sName をキーとした Cookie の値を取得します。
23 |
sName に結びつく Cookie の文字列。空の文字列の場合もあります。sName が空だった場合は null を返します。
34 | シリアライズ化された oSubCookies の値に sName の名前をつけて Cookie をセットします。
35 |
null をセットした場合、BOOMR.init() が呼び出されて設定された site_domain の値が使用されます。大抵の場合 null をセットすることになるでしょう。
53 | 60 | 全体の名前と値が4000文字未満である必要があることを注意してください。 61 |
62 | 63 |
65 | BOOMR.plugins.RT プラグインはこの関数をこのようにして使います:
66 |
68 | if(!BOOMR.utils.setCookie(
69 | impl.cookie,
70 | { s: t_start, r: url },
71 | impl.cookie_exp,
72 | "/",
73 | null
74 | )) {
75 | BOOMR.error("cannot set start cookie", "rt");
76 | return this;
77 | }
78 |
79 |
80 | true を返しますfalse を返します
90 | getCookie() によって取得した Cookie の文字列をパースし、サブ Cookie とした構成で切り分けます。
91 |
94 | BOOMR.plugins.BW プラグインはこの関数をこのようにして使います:
95 |
97 | var cookies = BOOMR.utils.getSubCookies(BOOMR.utils.getCookie(impl.cookie)); 98 |99 |
sCookie がセットされていないか有効なサブ Cookie が含まれていない場合は null を返します。
109 | sName にセットされた値を無効化して Cookie を削除し、セッション Cookie をつくります。
110 |
113 | なし 114 |
115 |
120 | init() メソッドに渡された設定オブジェクトと一緒に設定するためにプラグインが呼び出せる便利なメソッドです。
121 |
init() メソッドに渡された設定オブジェクト。BOOMR.plugins オブジェクト内でのプラグインの名前。
139 | BOOMR.plugins.RT プラグインはこのメソッドをこのようにして使います:
140 |
142 | BOOMR.utils.pluginConfig(impl, config, "RT", ["cookie", "cookie_exp", "strict_referrer"]); 143 |144 | 145 |
true を返します。false を返します。155 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 156 |
157 | 158 | 159 | 160 | 164 | -------------------------------------------------------------------------------- /doc/ja/api/BW.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |
12 | 帯域幅プラグインはサーバーへのユーザーのネットワークコネクションの帯域幅と遅延を測定します。帯域幅 API は BOOMR.plugins.BW に内包されます。
13 |
17 | bandwidth プラグインの全ての設定は BW の名前空間の下に入ります。設定オブジェクトについては 使用方法 #6 — boomerang の設定 をご覧ください。
18 |
images/ サブディレクトリーから見つけます。これはあなたのサイト上の全てのページで正しいとは限りません。画像があるディレクトリーのパスを base_url パラメーターで設定ができます。絶対 URL または相対 URL で指定ができます。相対パスの場合、JavaScript ファイルからではなく boomerang が読み込まれたページからの相対パスになることを覚えておいてください。
24 | BA です。詳細は 使用方法 #3 をご覧ください。Cookie を無視して開始時間を完全に WebTiming API に依存させるには、ここに null のような偽の値か空文字を指定します。
30 | timeout の値よりも超えるように考慮しなければなりません。
49 | 61 | 帯域幅プラグインを設定するために BOOMR.init() メソッドによって呼び出されます。 62 |
63 |BOOMR.init() を通して渡された設定オブジェクト。詳しくは 設定項目の説明 をご覧ください。
67 |
70 | BOOMR.plugins.BW オブジェクトへの参照。メソッドチェーンをサポートします。
71 |
77 | 帯域幅テストを開始します。 78 | このメソッドは page_ready イベントが発生したときに自動的に呼び出されます。もし必要であれば自分で呼び出してもかまいません。 79 |
80 |
82 | BOOMR.plugins.BW オブジェクトへの参照。メソッドチェーンをサポートします。
83 |
89 | すぐに帯域幅のテストを中断して、すでに収集した値から帯域幅と遅延を計算します。このメソッドは帯域幅のテストが中断されると自動的に呼び出されます。BOOMR.init() メソッドを呼び出すときに適切な timeout 値を設定することを推奨します。
90 |
93 | BOOMR.plugins.BW オブジェクトへの参照。メソッドチェーンをサポートします。
94 |
100 | 帯域幅プラグインが終了したのかどうかを確認するために BOOMR.sendBeacon() によって呼び出されます。 101 |
102 |true を返します。false を返します。113 | このプラグインはビーコンに次のパラメーターを追加します: 114 |
115 |125 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 126 |
127 | 128 | 129 | 130 | 134 | -------------------------------------------------------------------------------- /doc/ja/api/DNS.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | 注意: この DNS プラグインはまだテストされていません。テストに協力してくれる方を歓迎します。 13 |
14 |
15 | DNS プラグインはブラウザーからサーバーへの DNS ルックアップの遅延を測定します。 DNS API は BOOMR.plugins.DNS に内包されます。
16 |
19 | 注意: この DNS プラグインはいくつかのサーバー側の準備が必要になります。詳しくは 使用方法 #8 をご覧ください。 20 |
21 | 22 |29 | DNS プラグインを設定するために BOOMR.init() メソッドによって呼び出されます。これは1つのオプションだけ設定できます: 30 |
31 |base_url パラメーターは DNS のテスト画像がどこにあるかを指定します。この URL にはランダムな文字列に置き換えられるワイルドカードを含まれている必要があります。画像は他の変更はせずにこの文字列に追加されます。もし HTTPS のページの場合は、この URL も同様に HTTP と HTTPS 上で動作するように設定する必要があります。URL のプロトコル部分は現在のドキュメントに合わせて自動的に変わります。
36 |
39 | BOOMR.init({
40 | DNS: {
41 | base_url: "http://*.yoursite.com/images/"
42 | }
43 | });
44 |
45 | 46 | 上の例では * がランダムな文字列に置き換えられます。 47 |
48 | 49 |
51 | BOOMR.plugins.DNS オブジェクトへの参照。メソッドチェーンをサポートします。
52 |
55 | base_url が設定されていなければ DNS テストは実行されません。
56 |
62 | DNS プラグインが終了したのかどうかを確認するために BOOMR.sendBeacon() によって呼び出されます。 63 |
64 |true を返します。false を返します。75 | このプラグインはビーコンに次のパラメーターを追加します: 76 |
77 |83 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 84 |
85 | 86 | 87 | 88 | 92 | -------------------------------------------------------------------------------- /doc/ja/api/RT.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |
12 | roundtrip プラグインはページの読み込み時間を測定したりページにタイマーを連動させたりします。この API は BOOMR.plugins.RT に内包されます。
13 |
18 | roundtrip プラグインの全ての設定は RT の名前空間の下に入ります。設定オブジェクトについては 使用方法 #6 — boomerang の設定 に記載しています。
19 |
RT になります。
26 | document.referrer に RT Cookie が一致しなければページの往復時間は測定しません。これは RT Cookie がまだ有効な状態で3番目のページを訪れたからということを意味し、ページの読み込み時間は無効となる可能性があります。strict_referrer を false にすればいいでしょう。
39 | 51 | roundtrip プラグインを設定するために呼び出される BOOMR.init() メソッドです。 52 |
53 |BOOMR.init() を通して渡された設定オブジェクト。詳しくは 設定項目の説明 をご覧ください。
57 |
60 | BOOMR.plugins.RT オブジェクトへの参照。メソッドチェーンをサポートします。
61 |
67 | sName に指定された名前のタイマーを開始します。タイマーはミリ秒でカウントされます。boomerang のビーコンの測定結果を記録を終えるには endTimer() を呼び出す必要があります。
68 |
オプションとなる2番目のパラメーターである nValue はタイマーの開始時間とするタイムスタンプをミリ秒で指定します。これは boomerang が読み込まれる前にタイマーを開始する必要がある場合に便利です。
82 | startTimeer と endTimer の使用例は 使用方法 #4 をご覧くさい。 83 |
84 |
86 | BOOMR.plugins.RT オブジェクトへの参照。メソッドチェーンをサポートします。
87 |
90 | startTimer("t_page") を呼び出すと endTimer("t_resp") を呼び出す副作用があります。これらのタイマーは通常（できるだけ近い）読み込んだ最初の byte から onload（t_page）までと onbeforeunload から最初の byte の時間（t_resp）を使います。明示的に startTimer("t_resp") を呼び出す必要はありません。
91 |
97 | sName に指定された名前のタイマーを停止します。endTimer() が呼び出される前にタイマーが開始している必要はありません。この名前のタイマーが開始していない場合、前のページの unload 時間を代わりに使用します。これはページ間の時間の測定を可能にします。
98 |
111 | startTimeer と endTimer の使用例は 使用方法 #4 をご覧くさい。 112 |
113 |
115 | BOOMR.plugins.RT オブジェクトへの参照。メソッドチェーンをサポートします。
116 |
122 | 明示的な時間を測定するために sName に指定された名前のタイマーをセットします。
123 | boomerang が読み込まれる前にページ内の時間を計測していて、それらの値をビーコンに含めるために roundtrip プラグインへ渡す必要がある場合はこのメソッドを使う必要があります。setTimer() を呼び出す前に startTimer() や endTimer() を呼び出す必要はありません。もしそうした場合、古い値は無視され関数に渡された値が使用されます。
124 |
138 | BOOMR.plugins.RT オブジェクトへの参照。メソッドチェーンをサポートします。
139 |
145 | 通常は boomerang の page_ready イベントが発生した時に自動的に呼び出されますが、onload イベントとは関係ない状態の読み込み時間を測定するために明示的に呼び出すこともできます。 146 |
147 |
148 | このメソッドはページの読み込み時間を計算し、ビーコンを送信する十分な値かどうかを判断します。その時に sendBeacon メソッドを通してBOOMR オブジェクトに知らせます。
149 |
153 | done() メソッドの明示的な呼び出し方の例は 使用方法 #2 をご覧ください。
154 |
158 | BOOMR.plugins.RT オブジェクトへの参照。メソッドチェーンをサポートします。
159 |
170 | roundtrip プラグインが終了したのかどうかを確認するために BOOMR.sendBeacon() によって呼び出されます。 171 |
172 |true を返します。false を返します。183 | このプラグインはビーコンに次のパラメーターを追加します: 184 |
185 |name|value になります。r と異なり、strict_referrer が明示的にオフになっている場合のみ設定されます。196 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 197 |
198 | 199 | 200 | 201 | 205 | -------------------------------------------------------------------------------- /doc/ja/api/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 |33 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 34 |
35 | 36 | 37 | 38 | 42 | -------------------------------------------------------------------------------- /doc/ja/api/ipv6.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | 注意:この IPv6 プラグインはまだテストされていません。テストに協力してくれる方を歓迎します。 13 |
14 |
15 | IPv6 プラグインは IPv6 に関する様々なメトリクスを測定します。IPv6 API は BOOMR.plugins.IPv6 に内包されます。このプラグインはいくつかの事を試そうとします:
16 |
24 | このプラグインは IPv6 アドレスを持ったサーバーと DNS がそのサーバーを指している必要があります。さらに、サーバーは IPv6 アドレスからのリクエストを処理できるように設定されている必要があり、バーチャルホスト名は必要ありません。これはおそらく、同じ IP アドレス上に複数のホストを共有してホスティングできないということになります。 25 |
26 | 27 |29 | 全ての設定は IPv6 の名前空間の下に入ります。 30 |
31 |http://fe80::1/image-i.png 。もし指定されていなければ、テストは中止されます。51 | IPv6 プラグインを設定するために BOOMR.init() メソッドによって呼び出されます。詳しくは 設定項目の説明 をご覧ください。 52 |
53 |
54 | BOOMR.init({
55 | IPv6: {
56 | ipv6_url: "http://fe80::1/images/image-i.png"
57 | host_url: "http://yoursite-6.com/images/image-i.png"
58 | }
59 | });
60 |
61 |
62 |
64 | BOOMR.plugins.IPv6 オブジェクトへの参照。メソッドチェーンをサポートします。
65 |
68 | IPv6 テストは ipv6_url が設定されていないと実行されません。
69 |
75 | IPv6 プラグインが終了したのかどうかを確認するために BOOMR.sendBeacon() によって呼び出されます。 76 |
77 |true を返します。false を返します。
88 | このプラグインはビーコンに2つのパラメーターを追加します。ともに ipv6_ のプレフィックスがつきます:
89 |
98 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 99 |
100 | 101 | 102 | 103 | 107 | -------------------------------------------------------------------------------- /doc/ja/api/navtiming.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | 注意:この Navigation Timing プラグインはまだテストされていません。テストに協力してくれる方を歓迎します。 13 |
14 |
15 | Navigation Timing プラグインは W3C Navigation Timing の仕様をサポートしているモダンなユーザーエージェントによって回収されたメトリクスを回収します。Navigation Timing API は BOOMR.plugins.NavigationTiming に内包されます。
16 |
19 | 注意 Navigation Timing プラグインはデフォルトでは boomerang.js には含まれていません。詳しい boomerang へのプラグインの含め方については 使用方法 #9 をご覧ください。 20 |
21 | 22 |
29 | Navigation Timing プラグインを設定するために BOOMR.init() メソッドによって呼び出されます。
30 | Navigation Timing プラグインは設定パラメーターを必要としないため、シンプルにブラウザーの window.performance オブジェクト（もしあれば）から値を参照して、それらをビーコンのクエリー文字に追加します。
31 |
35 | BOOMR.plugins.NavigationTiming オブジェクトへの参照。メソッドチェーンをサポートします。
36 |
39 | ユーザーエージェントが Navigation Timing の仕様を実装していない場合、プラグインはビーコンにパラメーターを追加しません。 40 |
41 |46 | Navigation Timing プラグインが終了したのかどうかを確認するために BOOMR.sendBeacon() によって呼び出されます。 47 |
48 |true を返します。false を返します。59 | Navigation Timing プラグインはビーコンに次のパラメーターを追加します。それぞれブラウザーの Navigation Timing API の属性に対応しています。 60 |
61 || ビーコンパラメーター | 64 |Navigation Timing 属性 | 65 |
|---|---|
nt_red_cnt | window.performance.navigation.redirectCount |
nt_nav_type | window.performance.navigation.type |
nt_nav_st | window.performance.timing.navigationStart |
nt_red_st | window.performance.timing.redirectStart |
nt_red_end | window.performance.timing.redirectEnd |
nt_fet_st | window.performance.timing.fetchStart |
nt_dns_st | window.performance.timing.domainLookupStart |
nt_dns_end | window.performance.timing.domainLookupEnd |
nt_con_st | window.performance.timing.connectStart |
nt_con_end | window.performance.timing.connectEnd |
nt_req_st | window.performance.timing.requestStart |
nt_res_st | window.performance.timing.responseStart |
nt_res_end | window.performance.timing.responseEnd |
nt_domloading | window.performance.timing.domLoading |
nt_domint | window.performance.timing.domInteractive |
nt_domcontloaded | window.performance.timing.domContentLoaded |
nt_domcomp | window.performance.timing.domComplete |
nt_load_st | window.performance.timing.loadEventStart |
nt_load_end | window.performance.timing.loadEventEnd |
nt_unload_st | window.performance.timing.unloadEventStart |
nt_unload_end | window.performance.timing.unloadEventEnd |
nt_ssl_st | [オプション] window.performance.secureConnectionStart |
91 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 92 |
93 | 94 | 95 | 96 | 100 | -------------------------------------------------------------------------------- /doc/ja/community.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 |12 | boomerang は BSD ライセンス のもとでリリースされたオープンソースの JavaScript ライブラリーです。コミュニティ上の活動もそれに依存します。 13 |
14 | 15 |17 | ソースコードは GitHub の github.com/lognormal/boomerang に公開されています。自由に fork して貢献してください。また、ソースコードの tarball や zip アーカイブ も取得できます。 18 |
19 | 20 |22 | バグの報告や機能のディスカッションには GitHub の issue tracking system を利用します。 23 |
24 | 25 | 26 | 27 | 31 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-10-page#1.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |13 | このユースケースは Google Chrome 13 に実装された prerender 機能をベースにしています。 14 | ページに読み込むコードはあなたが prerender を利用するかどうかに関わらず同じになります。この使用方法はそれらを配慮していません。 15 | しかしながら、特定のページの prerender を有効にするには、元のドキュメントにあるリンク要素としてそのページの URL を含めます。 16 | 例えば、元のページの HEAD の中にこのようなコードを埋め込みます: 17 |
18 |19 | <link rel="prerender" href="howto-10-page%232.html"> 20 |21 |
22 | これは howto-10-page#2.html と全てのそのリソースを先読みすることを Chrome に明示して、ユーザーが見えないバックグランドでレンダリングを開始します。
23 | ユーザーがドキュメントのリンクをクリックすると、すぐに表示されます。
24 |
26 | パフォーマンスを気にするエンジニアなら、その全体でどれくらい時間を要したか知りたくなると思います。個別には次のような点が気になると思います: 27 |
28 |35 | それでは、あなたが2番目のページのレンダリングを完了するために、このページを十分時間をかけて読んだことに期待しましょう。 36 |
37 | 38 |39 | ページの読み込みテスト結果を確認するために 2番目のページ に移動してください。 40 |
41 | 42 |43 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 44 |
45 | 46 |47 |
48 | 49 | 50 | 51 | 61 | 62 | 63 | 67 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-10-page#2.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | このユースケースは Google Chrome 13 に実装された prerender 機能をベースにしています。このユースケースのために2つのページを使います。このページはサンプルの2番目のページになります。詳しい説明は 1番目のページ をご覧ください。 13 |
14 | 15 |16 | 1番目のページ からこのページへクリックしていれば、下の方にパフォーマンスの結果が確認できるはずです。もしこれが帯域幅のテスト以来の初回のテストなら6秒ほど時間がかかるかもしれません。1番目のページからリンクをクリックすれば同じ結果を確認できます。 17 |
18 | 19 |20 | 下のボックス内で、rt.start に cookie が設定されていれば、次のようなことが確認できるはずです: 21 |
22 |29 | もし rt.start に navigation（かそれ以外）が設定してあれば、t_done は t_prerender と同じになります。もし t_prerender が設定されていなければ、このページは prerender されておらず、t_done は実際の読み込み時間と認識されています。 30 |
31 | 32 |33 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 34 |
35 | 36 |37 |
38 | 39 | 40 | 41 | 51 | 52 | 53 | 57 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-1a-page#1.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | この要件の説明は ユースケース #1 をご覧ください。 13 |
14 |15 | このユースケースのために2つのページを使います。あなたのサイト上の2つのページに同じコードを埋め込みます。最初から始める場合はこのようになります: 16 |
17 |
22 | <script src="boomerang.js" type="text/javascript"></script>
23 | <script type="text/javascript">
24 | BOOMR.init({
25 | user_ip: "<user's ip address>",
26 | beacon_url: "http://yoursite.com/path/to/beacon.php"
27 | });
28 | </script>
29 |
30 | 31 | これはあなたのサイトにきたユーザーが訪れた一番最初のページを除いて、ページの読み込み時間の測定には十分なものになります。PHP や Python、C# といったようなサーバーサイドの言語を使ってユーザーの IP アドレスを取得する必要があります。これはリクエスト間の帯域幅を計算した結果を保存するために必要になります。 32 |
33 | 34 |35 | ページの読み込みテストの結果を見るには ページ #2 へ移動してください。 36 |
37 | 38 |
40 | 長い間ウェブサイトをやっていると JavaScript を CDN を使ってホスティングしたり、サブディレクトリーをもったページがあったりする場合があります。そういった場合は、boomerang.js へのリンクを絶対パスに変更します。帯域幅のテスト用の画像の場所も boomerang に設定する必要があります。init() をこのようにして呼び出します:
41 |
43 | BOOMR.init({
44 | user_ip: "<user's ip address>",
45 | beacon_url: "http://yoursite.com/path/to/beacon.php",
46 | BW: {
47 | base_url: 'http://yoursite.com/path/to/bandwidth/images/"
48 | }
49 | });
50 |
51 | 52 | 注意、これは画像ディレクトリの場所を示します。あなたがユーザーの帯域幅や遅延を測定したいサーバー上に画像を配置することを推奨します。これはほとんど場合はあなたのサーバー上で行うことになるとは思いますが、もしかすると代わりにそれらのファイルを CDN に置いて帯域幅や遅延を測定したい場合もあるかもしれません。判断は任せますが、あなたのサーバー上に配置することをおすすめします。 53 |
54 | 55 |56 | ページの読み込みテストの結果を見るには ページ #2 へ移動してください。 57 |
58 | 59 |60 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 61 |
62 | 63 |64 |
65 | 66 | 67 | 68 | 80 | 81 | 82 | 86 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-1a-page#2.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | この要件の説明は ユースケース #1 をご覧ください。 13 |
14 |15 | このユースケースでは2つのページを使います。これはサンプルの2番目のページになります。詳しい説明は 1番目のページ をご覧ください。 16 |
17 | 18 |19 | 1番目のページ からリンクをクリックして遷移すると、下にパフォーマンスの結果が確認できるはずです。初回のテストの場合は帯域幅のテストから約6秒ほどかかる場合があります。1ページ目へのリンクをクリックして1ページへ戻っても同様の結果を確認できます。 20 |
21 | 22 |23 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 24 |
25 | 26 |27 |
28 | 29 | 30 | 31 | 43 | 44 | 45 | 49 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-1b-page#1.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | この要件の説明は ユースケース #1 をご覧ください。 13 |
14 |
15 | このユースケースのために2つのページを使います。あなたのサイト上の2つのページに同じコードを埋め込みます。今回のケースでは 1a とは違い、onload イベントが発生したときにビーコンを送信させません。代わりに決めたページが準備完了となる時点で page_ready イベントを発生させます。また、自動的に実行された boomerang を停止するために autorun パラメーターを false にできます。
16 |
22 | <script src="boomerang.js" type="text/javascript"></script>
23 | <script type="text/javascript">
24 | BOOMR.init({
25 | user_ip: "<user's ip address>",
26 | beacon_url: "http://yoursite.com/path/to/beacon.php",
27 | autorun: false
28 | });
29 | </script>
30 |
31 |
32 | 残りのページはそのまま読み込まれます。ユーザーがページを表示しページが有効となったときに、次のように page_ready イベントを発生させる必要があります。
33 |
36 | BOOMR.page_ready(); // Tell boomerang that the page is now usable 37 |38 | 39 |
40 | 使用方法 1a のときのようにバックエンドの言語を使って user_ip を追加する必要があります。
41 |
44 | ページの読み込みテストの結果を見るには ページ #2 へ移動してください。 45 |
46 | 47 |48 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 49 |
50 | 51 |52 |
53 | 54 | 55 | 56 | 72 | 73 | 74 | 78 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-1b-page#2.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | この要件の説明は ユースケース #1 をご覧ください。 13 |
14 |15 | このユースケースでは2つのページを使います。これはサンプルの2番目のページになります。詳しい説明は 1番目のページ をご覧ください。 16 |
17 | 18 |
19 | 1番目のページ からリンクをクリックして遷移すると、下にパフォーマンスの結果が確認できるはずです。ページが読み込まれた後に page_ready イベントを発生できるかを伝えるために意図的に750msの遅延を挿入します。初回のテストの場合は帯域幅のテストから約6秒ほどかかる場合があります。1ページ目へのリンクをクリックして1ページへ戻っても同様の結果を確認できます。
20 |
23 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 24 |
25 | 26 |27 |
28 | 29 | 30 | 31 | 47 | 48 | 49 | 53 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-2.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | この要件の説明は ユースケース #2 をご覧ください。 13 |
14 |15 | このドキュメントは XHR を使っていくつかのコンテンツの読み込みを試し、boomerang を使ってそのコンテンツの読み込みかかった時間を測定します。次のようにして行ないます: 16 |
17 |
22 | <script src="boomerang.js" type="text/javascript"></script>
23 | <script type="text/javascript">
24 | BOOMR.init({
25 | user_ip: "<user's ip address>",
26 | beacon_url: "http://yoursite.com/path/to/beacon.php",
27 | auto_run: false
28 | });
29 | </script>
30 |
31 |
32 |
33 | 次にあなたのコンテンツを取得します。コンテンツの取得を呼び出す直前にタイマーが開始します。読み込み時間のタイマーは t_done と呼ばれます。コンテンツの取得が終わったときのコールバック関数の中で done() メソッドが呼び出されます。この測定とビーコンがレスポンスタイムを返します。以下は YUI 3 を使ったコードですが、あなたの好きな書き方をしてもいいです。
34 |
37 | YUI().use("io-base", function(Y) {
38 | var uri = "dynamic-content.txt";
39 |
40 | function complete(id, o) {
41 | var html = o.responseText;
42 | document.getElementById("dynamic-content").innerHTML = html;
43 | BOOMR.plugins.RT.done(); // Tell boomerang to measure time and fire a beacon
44 | };
45 |
46 | Y.on('io:complete', complete);
47 |
48 | BOOMR.plugins.RT.startTimer("t_done"); // Start measuring download time
49 | var request = Y.io(uri);
50 | });
51 |
52 |
53 | 54 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 55 |
56 | 57 |58 |
59 | 60 |12 | この要件の説明は ユースケース #3 と #5 をご覧ください。 13 |
14 | 15 |
16 | 初期状態では boomerang は常にユーザーの帯域幅と HTTP の遅延を測定し、それらの数値を送信するビーコンに追加します。実際には、帯域幅プラグイン（BOOMR.plugins.BW）がこれを行いますが、boomerang の中にバンドルされているもので、違いは単なる伝統的なものです。帯域幅を効率的に検出するためにいくつか知っておくべきことがあります。
17 |
20 | まず JavaScript による帯域幅の検知は正確ではありません。もしユーザーのネットワークが損失が多かったり、他のユーザーと共有していたら、もしくはネットワークのトラフィックが集中的だったら。実際の帯域幅は時間の経過とともに変化します。私たちが測定するのは短時間のものを基準としたもののため、これが最善か最悪の代表的なケースにはならないかもしれません。帯域幅以外の測定もカバーしようとしますが、その測定でもエラーの値も返します。 21 |
22 | 23 |
24 | 帯域幅のテストを開始するには単純にページに boomerang を追加して init() メソッドを呼び出すだけで十分です。そうするとビーコンがサーバーに結果を送ります。このようなコードを使います:
25 |
27 | <script src="boomerang.js" type="text/javascript"></script>
28 | <script type="text/javascript">
29 | BOOMR.init({
30 | beacon_url: "http://yoursite.com/path/to/beacon.php",
31 | BW: {
32 | base_url: "http://base_url/to/bandwidth/images/"
33 | }
34 | });
35 | </script>
36 |
37 |
38 | BW.base_url パラメーターの初期値は images/ です。もし帯域幅を検出する画像が現在のディレクトリーの images サブディレクトリーにある場合は、BW.base_url パラメーターを設定する必要はありません。複数のディレクトリーがあることもあるかもしれませんが、そのときは良い実践になるでしょう。
39 |
42 | これが帯域幅と遅延を測定してビーコンを返すために必要となる最小限のコードです。あなたのユーザーにとっては最善のオプションではありません。テストはユーザーの帯域幅がほとんど変わっていないのにも関わらず、サイト上のページに訪れるたびに毎回実行されます。一定期間、帯域幅を Cookie に格納しておくとはるかに良くなり、もしその Cookie があればそこから取得します。現在、ユーザーは複数のネットワーク間を移動できます。例えばラップトップを自宅で使ったり、職場やコーヒーショップで使ったり。これらの帯域幅や遅延は場所によって異なるかもしれないため、これらを切り分けて測定することが大切です。私たちはユーザーの IP アドレスを通してネットワークの変更を判断し、Cookie にユーザーの帯域幅を格納するため、boomerang にユーザーの IP アドレスを伝える必要があります。これを user_ip パラメーターを使って行ないます。
43 |
46 | <script src="boomerang.js" type="text/javascript"></script>
47 | <script type="text/javascript">
48 | BOOMR.init({
49 | beacon_url: "http://yoursite.com/path/to/beacon.php",
50 | user_ip: "<user's ip>",
51 | BW: {
52 | base_url: "http://base_url/to/bandwidth/images/"
53 | }
54 | });
55 | </script>
56 |
57 |
58 | 59 | 私の知る限りでは、JavaScript でユーザーの IP アドレスを算出する方法はありません。これはサーバーサイドで行ってあなたのコードに記述しなければなりません。 60 |
61 | 62 |64 | もしユーザーが IPv4 アドレスを持っていた場合、私たちは IP の最後の部分を除去して、完全な IP アドレスよりもそれを使用します。これはユーザーが同じ ISP 上の DHCP を使用している場合、IP アドレスは頻繁に変更されますが、同じサブネット内に留まるため効果がでます。もしユーザーが IPv6 アドレスを持っている場合はアドレス全体を使用します。 65 |
66 | 67 |
69 | 帯域幅が格納される Cookie の名前をカスタマイズしたい場合もあると思います。初期値は BA になっていますが、これは BW.cookie パラメーターで変更することができます。
70 |
73 | <script src="boomerang.js" type="text/javascript"></script>
74 | <script type="text/javascript">
75 | BOOMR.init({
76 | beacon_url: "http://yoursite.com/path/to/beacon.php",
77 | user_ip: "<user's ip>",
78 | BW: {
79 | base_url: "http://base_url/to/bandwidth/images/",
80 | cookie: "BW"
81 | }
82 | });
83 | </script>
84 |
85 |
86 |
87 | この Cookie は7日間有効です。BW.cookie_exp パラメーターを使って有効期限の変更もできます。値は秒です。その間、サーバーサイドで Cookie の値も取得することができます。フォーマットは以下の通りです:
88 |
91 | BA=ba=nnnnnnn&be=nnn.nn&l=nnnn&le=nn.nn&ip=iiiiii&t=sssssss; 92 |93 |
94 | 定義されているパラメーター: 95 |
96 |init() メソッドに user_ip パラメーターとして渡されたユーザーの IPv4 アドレスまたは IPv6 アドレス112 | これらのパラメーターはビーコンに送信されます（使用方法 #0 をご覧ください）が、Cookie にこれらを持っているということはリクエストを処理する前に帯域幅をもとにユーザーエクスペリエンスをカスタマイズできるということを意味します。 113 |
114 | 115 |117 | 最後に、帯域幅のテストを完全に無効にしたい場合があるかもしれません。おそらくあなたはユーザーが遅いネットワークを使っていたり、バイト単位で料金を払っていたり（帯域幅のテストはたくさんの帯域幅を使用します）、モバイルデバイスを使っていたりして読み込みきれないことを考えていると思います。その場合は2つの方法があります。 118 |
119 |BW.enabled パラメーターを false にする:
124 | <script src="boomerang.js" type="text/javascript"></script>
125 | <script type="text/javascript">
126 | BOOMR.init({
127 | BW: { enabled: false }
128 | });
129 | </script>
130 |
131 |
132 | 133 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 134 |
135 | 136 |137 |
138 | 139 | 140 | 141 | 153 | 154 | 155 | 159 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-4.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 7 | 8 | 22 |34 | この要件の説明は ユースケース #4 をご覧ください。 35 |
36 |
37 | 今まではページがユーザーによって有効になったときの時間を測定していました。また、これはページ全体の読み込み時間に遅れずにページ内の異なるコンポーネントにかかる時間を測定するには役立つかもしれません。boomerang はページの一部分を測定するための設定が可能なタイマーを追加する機能を提供します。これを行うには roundtrip（BOOMR.plugin.RT）プラグインの startTimer() と endTimer() メソッドを使用します。
38 |
41 | 以下の例では、boomerang.js が読み込まれているかの確認とこれらのメソッドを呼び出す前に init() メソッドが呼び出されているか確認する必要があります。おそらくページの先頭にそれを配置するといいでしょう。これをどう使うかはこの後確認します。
42 |
45 | まず最初に、あなたが測定したいページの領域を決めます。前で startTimer() を、後で endTimer() を呼び出します。それぞれのタイマーには自身の名前を持ちます。名前は自由な文字列でつけられますが、効率的にするためにシンプルな名前がいいでしょう。英数字とアンダースコアで、最大5文字の名前にしてください。例えば、t_ads、t_head、t_js といった感じです。また、次の名前は予約されています: t_done、t_page、t_resp
46 |
49 | タイマーを開始する前に boomerang.js が読み込まれていることを確認してください。 50 |
51 | 52 |
53 | <html>
54 | <head>
55 | <script src="boomerang.js" type="text/javascript"></script>
56 | <script type="text/javascript">
57 | BOOMR.init({
58 | beacon_url: "http://yoursite.com/path/to/beacon.php"
59 | });
60 | BOOMR.plugins.RT.startTimer("t_head");
61 | </script>
62 | <title>page title</title>
63 | <meta http-equiv="Content-type" content="text/html; charset=utf-8">
64 | <link rel="stylesheet" type="text/css" href="../../boomerang-docs.css">
65 | <script type="text/javascript">
66 | BOOMR.plugins.RT.endTimer("t_head").startTimer("t_body");
67 | </script>
68 | </head>
69 | <body>
70 | page body here
71 | <script type="text/javascript">
72 | BOOMR.plugins.RT.endTimer("t_body");
73 | </script>
74 | </body>
75 | </html>
76 |
77 |
78 |
79 | タイマーは t_done と一緒にビーコンに読み込まれます。
80 |
83 | endTimer と startTimer をチェーンして呼び出すときは順番に注意してください。ほとんどのメソッドはオブジェクトの参照を返すためこれが可能になります。タイマーのメソッドは BOOMR.plugins.RT オブジェクト上にあることも注意してください。メソッドの返り値はそのオブジェクトであって、BOOMR オブジェクトではありません。
84 |
88 | 私たちは何年もパフォーマンスのためにドキュメントの下に JavaScript を配置すると良いと言ってきました。いいアドバイスではないかもしれませんが、ドキュメントの上部で boomerang を読み込んでください。そうすればページ内で時間を測定できます。読み込みが終われば1度だけ boomerang にそれらの結果を渡します。これは BOOMR.plugins.RT.setTimer() メソッドを使って行ないます。このメソッドは2つのパラメーターを取ります — タイマーの名前とミリ秒の時間の値です。コードはこのようになります:
89 |
92 | <html>
93 | <head>
94 | <script type="text/javascript">
95 | var t_pagestart=new Date().getTime();
96 | </script>
97 | <title>page title</title>
98 | <meta http-equiv="Content-type" content="text/html; charset=utf-8">
99 | <script type="text/javascript">
100 | var t_headend = new Date().getTime();
101 | </script>
102 | </head>
103 | <body>
104 | page body here
105 | <script type="text/javascript">
106 | var t_jsstart = new Date().getTime();
107 | </script>
108 | <script src="boomerang.js" type="text/javascript"></script>
109 | <script type="text/javascript">
110 | BOOMR.init({
111 | beacon_url: "http://yoursite.com/path/to/beacon.php"
112 | });
113 | var t_bodyend = new Date().getTime();
114 | BOOMR.plugins.RT.setTimer("t_head", t_headend - t_pagestart).
115 | setTimer("t_body", t_bodyend - t_headend).
116 | setTimer("t_js", t_bodyend - t_jsstart);
117 | </script>
118 | </body>
119 | </html>
120 |
121 |
122 | 123 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 124 |
125 | 126 |127 |
128 | 131 | 132 | 135 | 136 | 137 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-5.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | この要件の説明は ユースケース #5 をご覧ください。 13 |
14 |
15 | サーバーに送ったビーコンに多くの情報を追加しなければならない場合はたびたびあると思います。例えば、page_id と一緒にビーコンにタグをつけたり、A/B テストを行ったり、ビーコンのためにバケットを指定するパラメーターと一緒にビーコンにタグをつけたりしたいかもしれません。これらを BOOMR.addVar() メソッドを使って実現することができます。
16 |
19 | このメソッドを使う前に、それぞれのプラグインは自身のパラメーターを追加すること、これらをあなた自身で上書きする必要がないことを覚えておいてください。boomerang にビルトインされているプラグインが設定するパラメーターの一覧は 使用方法 #0 をご覧ください。その他のプラグインは自身のパラメーターを追加するかもしれません。その場合はプラグインのドキュメントを参考にしてください。 20 |
21 | 22 |
23 | BOOMR.addVar("page_id", 123);
24 |
25 |
26 | 27 | パラメーターの名前は文字列でなければなりません。英数字とアンダースコアのみを使用することを推奨しますが、好きなものを使ってかまいません。パラメーターの値は数値か文字列になりますので、URL の中に置き換えることができます。 28 |
29 | 30 |31 | もし複数のパラメーターが必要なら、代わりにオブジェクトを使って渡します: 32 |
33 | 34 |
35 | BOOMR.addVar({
36 | "bucket": "test#1",
37 | "page_id": 123
38 | });
39 |
40 |
41 |
42 | BOOMR.addVar() を呼び出す前に boomerang.js が読み込まれているか確認してください。
43 |
47 | ビーコンは URL の中に追加した値を全て含めます。キーと値はともに URL エンコードされます。バックエンドのアプリケーションはパラメーターが渡されることを知っておく必要があります。 48 |
49 | 50 |51 | http://yoursite.com/path/to/beacon.php?bucket=test%231&page_id=123&t_done=..... 52 |53 | 54 |
56 | あなたが追加した（またはプラグインが追加した）パラメーターをビーコンから削除することもできます。これを行うには BOOMR.removeVar() メソッドを呼び出します。このメソッドは名前のリストを取り、パラメーターのリストから全てを削除します。パラメーターのリストにない名前は無視されます。
57 |
60 | // don't send the stooges to the server
61 | BOOMR.removeVar("larry", "moe", "curly");
62 |
63 |
64 |
66 | ビーコンの発生を止める大ざっぱな方法もあります。before_beacon イベントハンドラーの中で、全てのパラメーターを単純に削除します。
67 |
70 | BOOMR.subscribe('before_beacon', function(o) {
71 | var p_names = [], k;
72 |
73 | if( "t_done" in o ) {
74 | return;
75 | }
76 |
77 | // t_done is not set, so don't beacon
78 | for(k in o) {
79 | if(o.hasOwnProperty(k)) {
80 | p_names.push(k);
81 | }
82 | }
83 |
84 | // removeVar accepts either a list or an array
85 | BOOMR.removeVar(p_names);
86 | });
87 |
88 |
89 | 90 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 91 |
92 | 93 |94 |
95 | 96 | 97 | 113 | 114 | 115 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-6.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |
12 | boomerang を使用するためには最初に boomerang.js を HTML の中に読み込み、BOOMR.init() メソッドを呼び出します。ページのパフォーマンスを測定するにはこれで十分のはずですが、サイトの管理者として十分役立つとは限りません。これだけではまだサーバーに送ったデータを取得することはできませんし、ユーザーの帯域幅も測定できません。
13 |
15 | このドキュメントでは、あなたが使用できる boomerang の設定とビルトインのプラグインのパラメーターの違いについて説明します。もし追加のプラグインを使っている場合はその設定についてはプラグインのドキュメントを参考にしてください。 16 |
17 | 18 |
20 | boomerang とそのプラグインを設定するには、init() メソッドに設定オブジェクトを渡します。
21 |
23 | BOOMR.init({
24 | key: value,
25 | ...
26 | });
27 |
28 | 29 | boomerang には以下のパラメーターがあります: 30 |
31 |foo.com の形式の場合を除き、実際には取得に失敗します。これはドメイン間で共有する帯域幅やパフォーマンスを測定したいときに役立ちます。log パラメーターを設定することで自身のロガーを定義することができます。57 | function log(oMessage, sLevel, sSource); 58 |59 | どこに:
log に null を設定することでログの記録を無効にできます。
65 | window.onload イベントに page_ready ハンドラーが登録されます。もし autorun を false にすると、これは起こらず、BOOMR.page_ready() を自分で呼び出す必要があります。
71 |
81 | BOOMR.init({
82 | beacon_url: "http://beacons.yoursite.com/path/to/beacon.php",
83 | site_domain: "yoursite.com",
84 | user_ip: "202.54.1.18",
85 | autorun: false
86 | });
87 |
88 |
89 |
91 | roundtrip プラグインの全ての設定は RT の名前空間の下に入ります。
92 |
RT になります。
99 | document.referrer に RT Cookie が一致しなければページの往復時間は測定しません。これは RT Cookie がまだ有効な状態で3番目のページを訪れたからということを意味し、ページの読み込み時間は無効となる可能性があります。strict_referrer を false にすればいいでしょう。
112 |
117 | BOOMR.init({
118 | beacon_url: "http://beacons.yoursite.com/path/to/beacon.php",
119 | site_domain: "yoursite.com",
120 | user_ip: "202.54.1.18",
121 | autorun: false,
122 | RT: {
123 | cookie: "MyRT",
124 | cookie_exp: 120
125 | }
126 | });
127 |
128 |
129 |
132 | bandwidth プラグインの全ての設定は BW の名前空間の下に入ります。
133 |
images/ サブディレクトリーから見つけます。これはあなたのサイト上の全てのページで正しいとは限りません。画像があるディレクトリーのパスを base_url パラメーターで設定ができます。絶対 URL または相対 URL で指定ができます。相対パスの場合、JavaScript ファイルからではなく boomerang が読み込まれたページからの相対パスになることを覚えておいてください。
140 | BA です。詳細は 使用方法 #3 をご覧ください。Cookie を無視して開始時間を完全に WebTiming API に依存させるには、ここに null のような偽の値か空文字を指定します。
146 | timeout の値よりも超えるように考慮しなければなりません。
165 |
171 | 全ての設定パラメーターはオプションですが、それらのうちいくつかを設定しないと予期しないまたは不完全な結果が起こる可能性があるため、設定すべきです。しかしながら、正しいディレクトリーに帯域幅テストの画像を置けば、コードを読み込んで init() を呼び出せば実行はできます。
172 |
175 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 176 |
177 | 178 |179 |
180 | 181 | 182 | 183 | 195 | 196 | 197 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-7.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | この要件の説明は ユースケース #9 をご覧ください。 13 |
14 | 15 |16 | 防ぐ必要がある不正なビーコンは2種類あります: 17 |
18 |25 | DoS 攻撃を防ぐために JavaScript にできることは何もありませんが、あなたのサーバーに1つの IP からのビーコンを送る制限する設定はできます。通常ウェブサイトを開けるユーザーよりも速くビーコンを受信するべきではありません。不正なアクセスパターンを見つけるために、システムのオペレーションやウェブサーバーの設定を変えたくなるでしょう。これらの大半はこのドキュメントの範囲を越えていますが、攻撃から守るためのヒントをいくつか紹介します。 26 |
27 | 28 |
29 | ほとんどの開発者は boomerang の beacon_url パラメーターを使用するバックエンドのスクリプトをつくると思います。ここで問題になるのはこれらのリクエストはキャッシュされないということです。スクリプトはビーコンのリクエストのたびに実行され、ウェブサーバーやデータベースのリソースを消費します。DoS 攻撃によって、あなたのサーバーをダウンさせることが可能になります。
30 |
33 | それをコントロールする良い方法としては、ビーコンサーバー上で動作する軽量なウェブサーバーを用意すること、このサーバーをビーコンの URL のリクエストだけに応答するように設定することです。全てのビーコンのリクエストには HTTP 204 のレスポンスを返すべきです。これはサーバー内の簡単な設定することで、リクエストごとにディスクの検索をさせる必要がないことを意味します。サーバーはリクエストをアクセスログに書き込みます。ここに全ての QueryString やパラメーター、Cookie を含める必要があります。
34 |
37 | 定期的に - 1時間に1回や1日に1回（ビーコンのボリュームに依存します）、ログをバッチ処理すればそこから実際のビーコンのパラメーターを見つけだせます。明らかに不正なビーコンは破棄します。ビーコンからデータを抽出するための実際のコードは全てのリクエストに対して行うかバッチ処理で行うかに関わらず同じです。ビーコンからのデータの抽出については 使用方法 #0 をご覧ください。 38 |
39 | 40 |41 | オンライン上にある DoS 攻撃とその対策の仕方についての さらに 多くの 情報 も参考にしてください。 42 |
43 | 44 |
46 | この場合の最も一般的な理由はあなたのページデザインを気に入った誰かがそれを自身のサーバーにコピーしてしまうことです。boomerang の JavaScript を含み、beacon_url も更新されていないとあなたのサーバーへビーコンが送信され続けます。きっと望まないことでしょう。
47 |
50 | この問題を解決する最も簡単な方法は全てのリクエストのリファラーをチェックし、あなたのドメインからではないリクエストをブロックすることです。これを知らない不正ユーザーには効果がありますが、悪意のある不正ユーザーには効果がありません。 51 |
52 | 53 |
54 | 悪意のあるユーザーはあなたのサイトの何かが得られる全ての URL を悪用しようとします。何に使うかは彼らにとって重要ではありません。これらはあなたのビーコンの正しい使用ではありませんし、全てブロックするべきです。最善の対策は nonce や crumb を通すことです。これは1度だけ有効な文字列です。これにはハッシュの一部として現在のタイムスタンプと有効期限が含まれています。これをページのリクエスト毎に生成し、BOOMR.addVar() メソッドを使って boomerang に追加させます。ビーコンサーバー上で、ビーコンを受け取る前に nonce を検証します。もしバッチ処理を行っているなら、nonce を検証するために実行しているバッチ処理の時間ではなくリクエストのタイムスタンプを使うべきです。
55 |
58 | BOOMR.addVar("nonce", "125a7b79de989876cce970f0768a07"); // your nonce will be different
59 |
60 |
61 | 62 | nonce はビーコンの URL を直接叩くものから守れますが、nonce はリクエスト毎に変更されるため、あなたのページはキャッシュできないことを意味します。 63 |
64 | 65 |66 | nonce はあなたのページからビーコンを抜き取るものからは守れません — 正しい nonce と一緒にその時はビーコンのパラメーターを変更してあなたのサーバーに送信してきます。これを防ぐにはビーコンのパラメーターを登録する必要がありますが、これは JavaScript ではできません。この問題に対する一般的な解決方法は今のところ分かりません。 67 |
68 | 69 |70 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 71 |
72 | 73 |74 |
75 | 76 | 77 | 78 | 90 | 91 | 92 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-8.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | この要件の説明は ユースケース #7 をご覧ください。 13 |
14 |15 | 注意: この DNS プラグインはまだテストされていません。テストに協力してくれる方を歓迎します。 16 |
17 |18 | DNS の測定にはサーバーサイドの準備がいくつか必要になります。その準備については Yahoo! のエンジニアである Carlos Bueno による ドキュメント に詳しく書かれていますので、目を通してください。要点として彼が挙げているものは: 19 |
20 |A.gif と B.gif という名前の画像（ images/ のサブディレクトリーから）をできるだけ速く受け取れるようにウェブサーバーの準備をします。KeepAlive や Nagle などのキャッシュのためのヘッダーがオフになっていることを確認してください。boomerang.js と一緒に dns.js を読み込みます（2つのファイルを結合しても構いません）。28 | ステップ1とステップ2は複雑なうえ、あなたの DNS サーバーは完全にコントロールできない（例えば Dreamhost を使っている）場合、これらを行うのは難しいかもしれません。もし可能であれば、読み進めてください。 29 |
30 | 31 |32 | プラグインを設定するために画像をどこから取得するかを伝える必要があります。帯域幅プラグインとは違い、URL にワイルドカードが必要になります: 33 |
34 |
35 | <script src="boomerang.js" type="text/javascript"></script>
36 | <script src="dns.js" type="text/javascript"></script> <!-- concatenate with boomerang.js for better performance -->
37 | <script type="text/javascript">
38 | BOOMR.init({
39 | user_ip: "<user's ip address>",
40 | beacon_url: "http://yoursite.com/path/to/beacon.php",
41 | DNS: {
42 | base_url: "http://*.yoursite.com/images/"
43 | }
44 | });
45 | </script>
46 |
47 |
48 | 49 | 正しく設定できれば、これで誤差範囲内で DNS の遅延が測定できるはずです。エラーを調べるためにテストを複数実行できますが、今のところ1回しか行ないません。 50 |
51 | 52 |53 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 54 |
55 | 56 |57 |
58 | 59 | 60 | 61 | 73 | 74 | 75 | -------------------------------------------------------------------------------- /doc/ja/howtos/howto-9.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 |12 | 注意:この Navigation Timing プラグインはまだテストされていません。テストに協力してくれる方を歓迎します。 13 |
14 | 15 |W3C Navigation Timing API はページの読み込みのパフォーマンスデータを広く深く提供するモダンブラウザーに実装されているインターフェースです。これを書いている時点では次のブラウザーがサポートしています:
16 | 17 |navtiming.js プラグインは設定のオプションを必要とせず、ブラウザー（がサポートしていれば）の値からデータをシンプルに取得し、それらをビーコンのクエリーに追加します。
24 | 25 |でフォルトのプラグインではないため、あなた自身で boomerang.js をビルドする必要があります。これを行うには、次のオプションを指定して boomerang のディレクトリーで make を実行してください:
28 | make PLUGINS=navtiming.js 29 |30 | 31 |
そうすると新しい boomerang のファイル（好きな JavaScript 圧縮ツールに通すことを忘れないでください）をあなたが通常使うものにできます。
32 | 33 |新しいクエリーパラメーターとブラウザーの属性は次のように対応しています。それぞれの属性ごとの定義は W3C Navigation Timing 仕様 をご覧ください。
34 | 35 || ビーコンパラメーター | 38 |Navigation Timing 属性 | 39 |
|---|---|
nt_red_cnt | window.performance.navigation.redirectCount |
nt_nav_type | window.performance.navigation.type |
nt_nav_st | window.performance.timing.navigationStart |
nt_red_st | window.performance.timing.redirectStart |
nt_red_end | window.performance.timing.redirectEnd |
nt_fet_st | window.performance.timing.fetchStart |
nt_dns_st | window.performance.timing.domainLookupStart |
nt_dns_end | window.performance.timing.domainLookupEnd |
nt_con_st | window.performance.timing.connectStart |
nt_con_end | window.performance.timing.connectEnd |
nt_req_st | window.performance.timing.requestStart |
nt_res_st | window.performance.timing.responseStart |
nt_res_end | window.performance.timing.responseEnd |
nt_domloading | window.performance.timing.domLoading |
nt_domint | window.performance.timing.domInteractive |
nt_domcontloaded | window.performance.timing.domContentLoaded |
nt_domcomp | window.performance.timing.domComplete |
nt_load_st | window.performance.timing.loadEventStart |
nt_load_end | window.performance.timing.loadEventEnd |
nt_unload_st | window.performance.timing.unloadEventStart |
nt_unload_end | window.performance.timing.unloadEventEnd |
64 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 65 |
66 | 67 |68 |
69 | 70 | 71 | 72 | 84 | 85 | 86 | -------------------------------------------------------------------------------- /doc/ja/howtos/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 |12 | 以下は ユースケース の中であげられている項目です。 13 |
14 |38 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 39 |
40 | 41 | 42 | 45 | 46 | 47 | -------------------------------------------------------------------------------- /doc/ja/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 |26 | ブーメランは必ずもどってくる、何かにぶつからない限り。 27 |
28 |30 | boomerang は小さな JavaScript からなり、あなたのウェブページに埋め込まれ、ユーザーの視点からあなたのウェブページのパフォーマンスを測定する場となります。さらに解析するには取得したデータをあなたのサーバーに送信する必要があります。boomerang を使えば、ユーザーがあなたのサイトがどれくらい速度で見ているかを正確に知ることができます。 31 |
32 |33 | boomerang は BSD ライセンス のもとでオープンソースとして公開されています。我々は boomerang に関する多くのドキュメントを提供します。 34 |
35 |47 | boomerang は Yahoo! Developer Network の協力のもと Yahoo! の Exceptional Performance チームにより開発されています。 48 |
49 |14 | 私たちはユーザーがリソースにリクエストを始めてから、そのリソースがユーザーにとって完全に有効になるまでの時間を往復（round trip）時間として定義します。私たちが測定できるものは HTML ページのリソースでなおかつ、私たちがコントロールできるページ上からのクリックまたは画面遷移によってリクエストされたリソースに限ります。 15 |
16 |17 | 往復時間はしたがって、リンクをユーザーがクリックしてからユーザーによってページが参照されるまでの時間となります。多くの場合、これは前のページの onbeforeunload イベントが発生してから現在のページの onload イベントが発生するまでを測定すれば問題ありません。いくつかのケースでは違うかもしれませんが、私たちはこれらのイベントを開発者が決められるようにします。 18 |
19 |20 | どのように測定するか。 21 |
22 |
25 | window.onbeforeunload イベントに関数をアタッチする。
26 |
28 | この関数で時間（ms）を取得し、現在のページの URL と一緒にセッション Cookie に保存します。 29 |
30 |
33 | window.onload イベントに関数をアタッチする。
34 |
36 | この関数で時間（ms）を取得し、前のページの onbeforeunload イベントハンドラーで保存された Cookie を探します。もし Cookie が見つからずブラウザーが WebTiming API を実装しているか検証します。もし WebTiming API を実装していればそこからのデータを使うようにします。どちらも見つからなければそこで終了します [1] 。 37 |
38 |
39 | もし Cookie が見つかった場合、Cookie の中に保存された URL と現在のページの document.referrer を検証します。もしこのふたつが違った場合、ユーザーが二つのページの間で三つ目のページに訪れたかもしれないため測定は失敗し、そこで終了します [2] 。
40 |
42 | もしここまで実行できていれば、Cookie から時間を取り出して Cookie を削除します。二つの時間の差を測定し、これがページの往復（Round trip）時間となります。 43 |
44 |51 | 帯域幅と遅延はサーバー上の固定サイズの画像のダウンロードとそれらをダウンロードするためにかかった時間によって測定します。次のようにして実行します: 52 |
53 |56 | 最初に 32 byte の GIF を10回続けてダウンロードします。これを遅延の測定に使用します。 57 |
58 |59 | 1回目の測定結果は TCP のハンドシェイク（3パケット）と TCP のスロースタート（4パケット以上）を消費するため破棄します。他の全ての画像のリクエストは TCP の2パケット（リクエストの1パケットとレスポンスの1パケット）を消費します。これはブラウザーからサーバーへの HTTP リクエストにどれくらい時間がかかっているかの良い目安になります。 60 |
61 |62 | それが済むと平均値を計算し、9回のダウンロードによって得られた標準偏差と標準誤差は95%信頼できる値となります。これがビーコンによってサーバーから返ってきた遅延の値になります。 63 |
64 |68 | 次はタイムアウトが発生するまで画像のサイズを大きくしていきダウンロードします。 69 |
70 |71 | できるだけ早く帯域幅の範囲で画像のサイズを絞り込みます。詳しいことは boomerang.js のコメントをご覧ください。 72 |
73 |74 | 画像のタイムアウトを1.2秒から1.5秒の間に設定します。もしタイムアウトした場合、それより大きい画像のダウンロードをやめて、その時点で最も大きい画像のダウンロードを4回以上試します [3] 。ダウンロードした最も大きい画像3つから帯域幅を計算します。 75 | それよりも前にタイムアウトしない限りこれによって7つの結果が得られるはずです [4] 。中間値を計算し、これらの値から得られた標準偏差と標準誤差がビーコンによってサーバーから帰ってきた帯域幅になります。 76 |
77 |81 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 82 |
83 | 84 |BW.nruns パラメーターを使って設定できます。boomerang の詳しい設定は Howto #6 をご覧ください。
95 | 12 | これは boomerang について発表された私たちが把握している資料の一覧です。もしあなたが書いた資料やここにない資料をご存知でしたら、この一覧に追加するので私たちに教えてください。 13 |
14 |12 | これらは boomerang を使用できるいくつかの方法です。これはライブラリーが実際に全てのユースケースをサポートしているかの確認に役立ちます。 13 |
14 | 15 |17 | 私たちはユーザーがページを読み込むために要した時間を計測する手段を必要としています。通常これはユーザーがリンクをクリック（またはブラウザーに URL を入力）してからページが使用可能になるまでの時間を指します。 18 |
19 |20 | リンクがあなたのコントロールできる領域にあればクリックされた時間を記録するのは簡単ですが、ユーザーがブラウザーに URL を入力して Enter キーを押したときの正確な時間を伝えるのは簡単ではありません。そこで私たちがコントロールできるページ上のリンクのクリックに注力します。 21 |
22 |23 | ページが使用可能になる時間が分からないことのうちの一つになります。ほとんどのページではこれは onload イベントが発生した時点となりますが、実際にはページが使用可能となる前に onload イベントが発生する（例えば、多くのコンテンツが JavaScript によって読み込まれている）可能性もあります。また、onload イベントが発生する前にページが使用可能となる（例えば、隠されたリソースがページ下部に埋め込まれた JavaScript によって読み込まれる）場合もあります。これらのどちらのケースにおいても、ページの開発者は自分のページが利用可能になる時のより良いアイデアを持ち、自分のライブラリーにこのイベントを発生させられるようにすべきです。 24 |
25 |26 | これを4つのユースケースに切り分けます: 27 |
28 | 29 |48 | 多くのウェブサイトは動的にコンテンツを読み込むことがあります。例えば、スライドショーに使う画像やタブを使ったコンテンツは JavaScript を通して読み込まれます。証券相場では定期的に XHR を使ってバックエンドのウェブサービスから自らリフレッシュする場合がありますし、ウェブメールサービスは JavaScript を使ってサーバーに新しいメッセージを確認したり選択されたメッセージをダウンロードしたりします、などなど。 49 |
50 |51 | これら全てのケースでブラウザーはダウンロードが開始されたとき、また完了したときのイベントを発生させることができません。開発者が必要なときに呼び出せるようなメソッドやイベントをライブラリーは公開する必要があります。 52 |
53 |54 | 使用方法 #2 をご覧ください。 55 |
56 | 57 |59 | ユーザーは様々なインターネット接続を使ってウェブを参照するため、全てのユーザーの統計学的な数値を表すために複数のユーザーのページの読み込み時間を常に集めることはできません。しかしユーザーの回線帯域幅を知っていることから、似たようなユーザーからデータを集め、ネットワーク接続のタイプごとにユーザーの統計的な数値として使用できます。 60 |
61 |62 | 使用方法 #3 をご覧ください。 63 |
64 | 65 | 66 |68 | 多くのウェブサイトは異なるバックエンドサービスから読み込まれる別々のコンポーネントによって構成されていることがあります。例えば私のホームページには dopplr、upcoming、twitter、delicious、flickr といったウィジェットがあります。今ではページ全体の読み込み時間が重要であり、これこそがユーザーにはページのパフォーマンスとして認識されます。これはページ全体の測定の一部にすぎませんが、便利で各コンポーネントの個別の読み込み時間を測定するためにも有益です。つまりこれはページの読み込み時間を各コンポーネントの読み込み時間に切り分けることを可能にし、ページ内の各コンポーネントの分析を行ないます。 69 |
70 |71 | これを行うには開発者がライブラリーを使ってページにタイマーを追加できるようになっている必要があります。これらのタイマーはページ全体の読み込みとともにビーコンを送る必要があります。 72 |
73 |74 | 使用方法 #4 をご覧ください。 75 |
76 | 77 | 78 |80 | ネットワークの遅延はページのダウンロード時間が大きな要因です。それは TCP 接続を確立し、HTTP リクエストを生成するいくつかのパケットを必要とするため、HTTP の遅延は単純な ping よりも高くなってしまいます。また HTTP リクエストと実際のページのコンテンツに関係のないレスポンスヘッダーがオーバーヘッドに関係します。 81 |
82 |83 | ユーザーの HTTP の遅延を測定することはページ全体の並列化されたコンポーネントのダウンロードが与える影響の良い指標を提供してくれます。 84 |
85 |86 | 使用方法 #3 をご覧ください。 87 |
88 | 89 | 90 |92 | パフォーマンスの解析をしているとき、それは2つ以上のデザインの異なるページのパフォーマンスを比較する A/B テストを行うときに便利です。 93 | これらのページには同じ URL があるかもしれないため、その一連のテストからページを識別しビーコンのデータをもとに必要なときにいくつかの情報が追加されます。 94 |
95 |96 | ライブラリーは追加情報を各ページにタグをつける機能を開発者に提供するべきです。 97 |
98 |99 | 使用方法 #5 をご覧ください。 100 |
101 | 102 | 103 |105 | DNS の遅延は DNS のリクエストを行うためにどれくらい時間がかかるかを教えてくれます。これは Web サーバーや DNS の設定、ユーザーの ISP の DNS サーバーがどのような構成になっているか、など様々な要因によって影響を受ける可能性があります。この遅延の測定で私たちは一つのページ上で安全にルックアップした多くのドメインの目安を得られます。これらは私たちがルックアップできる DNS の数と複数のドメインが私たちにもたらす並列性を交換することになります。HTTP の遅延と DNS の遅延は一緒にユーザーのためにこの点がどこにあるかを私たちに教えてくれます。 106 |
107 |108 | 使用方法 #8 をご覧ください。 109 |
110 | 111 | 112 |114 | トラフィックが高いサイトの場合、全てのリクエストではなくランダムなサンプルだけ測定した方が便利です。私たちはサーバーサイドでランダムなサンプリングを行うことができ、一部のリクエストに JavaScript の提供だけします。また、私たちはサーバーを簡素化し、クライアントサイドでサンプリングできます。 115 |
116 |117 | クライアントサイドのサンプリングはクライアント間で状況を共有しないためサーバーサイドのように正確にはなりませんが、私たちはランダムなサンプルは得ることができます。 118 |
119 |120 | TODO #1 ご覧ください。 121 |
122 | 123 | 124 |126 | もしあなたの URL がある場合、それは故意または誤った使い方によって悪用される可能性があります。 127 |
128 |129 | 例えば、あなたが満足するサイトのデザインを行い、パフォーマンスを測定するために boomerang の JavaScript を埋め込みます。JavaScript はあなたのサーバーにビーコンを送ります。あなたのデザインが本当に好きな誰かがサイトに訪問して、あなたの HTML をコピーして彼らは自分のサーバーにコピーします。彼らはテキストや画像を変えたりしますが、JavaScript はあなたのサーバーにビーコンをまだ送り続けます。あなたは彼らのビーコンを受け取ることになってしまううえに、これだけでもあなたのサーバーの負荷を増やし測定を台無しにしてしまいます。 130 |
131 |132 | 次に可能性があるのはあなたのビーコンの URL を幼稚なスクリプトが見つけ、不当にあなたのサーバーを大量に叩き始め、何もなければ DoS 攻撃を試してくる場合もあります。 133 |
134 |135 | boomerang はこれらの問題から守る必要があります。 136 |
137 |138 | 使用方法 #7 をご覧ください。 139 |
140 | 141 |143 | モダンブラウザーはページの読み込みに関する多くのパフォーマンス情報を取得できる Navigation Timing API をサポートしています。NavigationTiming プラグインはこの情報を回収し、ビーコンに追加します。 144 |
145 |146 | 使用方法 #9 をご覧ください。 147 |
148 | 149 |150 | 最新のソースコードとドキュメントは github.com/lognormal/boomerang に公開されています。 151 |
152 | 153 | 154 | 155 | 159 | -------------------------------------------------------------------------------- /doc/methodology.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 |14 | We define round trip time as the time taken from the user initiating a resource request 15 | to when that resource is completely available for the user to interact with. We limit 16 | our measurements only to HTML page type resources. 17 |
18 |19 | The round trip time is therefore the time from the user clicking on a link to the page 20 | referenced by that link becoming usable by the user. For most cases, this is as good 21 | as measuring the time from the previous page's onbeforeunload event firing to the current 22 | page's onload event firing. In some cases this may be different, but we let the 23 | developer determine those events. 24 |
25 |26 | This is how we measure. 27 |
28 |
31 | attach a function to the window.onbeforeunload event.
32 |
34 | Inside this function, we take a time reading (in milliseconds) and store it into a 35 | session cookie along with the URL of the current page. 36 |
37 |
40 | attach a function to the window.onload event.
41 |
43 | Inside this function, we take a time reading (in milliseconds). If the browser has implemented the
44 | WebTiming API, we
45 | pull out navigationStart (or fetchStart if navigationStart
46 | is unset). To get around a bug in Firefox 7 and 8, we use unloadEventStart instead.
47 |
49 | If the WebTiming API is not supported, we look for the cookie where we set the start time, and if found, 50 | use that. If we find neither, we abort [1]. 51 |
52 |
53 | If we find a cookie, we check the URL stored in the cookie with the document.referrer
54 | of the current document. If these two differ, it means that the user possibly
55 | visited a third party page in between the two pages from our site and the measurement
56 | is invalid, so we abort [2].
57 |
59 | If we're still going, we pull the time out of the cookie and remove the cookie. We 60 | measure the difference in the two times and this is the round trip time for the page. 61 |
62 |69 | Bandwidth and latency are measured by downloading fixed size images from a server 70 | and measuring the time it took to download them. We run it in the following order: 71 |
72 |75 | First download a 32 byte gif 10 times serially. This is used to measure latency 76 |
77 |78 | We discard the first measurement because that pays the price for the TCP handshake 79 | (3 packets) and TCP slow-start (4 more packets). All other image requests take 80 | two TCP packets (one for the request and one for the response). This gives us a 81 | good idea of how much time it takes to make an HTTP request from the browser to 82 | our server. 83 |
84 |85 | Once done, we calculate the arithmetic mean, standard deviation and standard error 86 | at 95% confidence for the 9 download times that we have. This is the latency number 87 | that we beacon back to our server. 88 |
89 |93 | Next download images of increasing size until one of the times out 94 |
95 |96 | We choose image sizes so that we can narrow down on a bandwidth range as soon as 97 | possible. See the code comments in boomerang.js for 98 | full details. 99 |
100 |101 | Image timeouts are set at between 1.2 and 1.5 seconds. If an image times out, we 102 | stop downloading larger images, and retry the largest image 4 more times[3]. 103 | We then calculate the bandwidth for the largest 3 images that we downloaded. This 104 | should result in 7 readings unless the test timed out before that [4]. 105 | We calculate the median, standard deviation and standard error from these values 106 | and this is the bandwidth that we beacon back to our server. 107 |
108 |112 | The latest code and docs is available on github.com/lognormal/boomerang 113 |
114 | 115 |BW.nruns parameter. See
133 | Howto #6 for details on configuring boomerang.
134 | 12 | This is a list of articles (that we are aware of) that speak about boomerang. If you write one, 13 | or know of one that isn't here, let us know, and we'll add it. 14 |
15 |