How to capture and view traces.
The tracing framework is a suite of tools and libraries, and there are many different ways to obtain each. The easiest way to get started is to install the Chrome Extension (on Mac/Linux) and see what it records on your page. From there, you can start to add custom instrumentation and analyzing the data.
The most awesome, advanced features require the Chrome extension and some optional command line flags. It's recommended you run with the dev channel or a Canary build. Mac or Linux are preferred!
Easily inject the Tracing Framework onto any page and get garbage collection information.
None yet! Contribute some! Maybe a Safari one?
Requires: node >= 0.8.14
You can use NPM to install the tracing-framework module. You can either install it within your project as a dev dependency or globally to get access to the command line tools.
$ node -v # ensure at least v0.8.14 $ npm install -g tracing-framework $ wtf-trace myapp.js $ wtf-dump myapp-[date].wtf-trace # or open in the UI
The hosted library and extension are updated every few weeks, but if you prefer living on the bleeding edge you can checkout and build the entire toolset from source. Detailed instructions are available in the building documentation.
The tracing framework operates by being loaded inside your page or app before any of your application code executes. Attempting to load it afterwards will produce incorrect results.
The easiest way to put the framework on the page is via the Chrome extension. It gives you a toggle button for injection and makes it easy to enable and disable the framework when developing and testing. The extension also provides additional support for advanced features such as browser internal events like garbage collections.
You can toggle the injection via the page action popup, as well as show the UI at any time. Note that your page will reload when you enable or disable the injection, so it's handy to have any state you need to preserve stored in the URL to save time.
Screenshot showing enabling and disabling the library.
Similar to the Chrome extension, the injection of the tracing fraemwork library is toggled on a per-uRL basis. Find the extension icon in the Firefox addons bar (ctrl+/ to show it if hidden) and click it to enable or disable the library.
When running where a browser extension is not available, such as Internet Explorer or on mobile devices, it's possible to manually embed the library on a page using some <script> tags. This is also useful when running automated tests that cannot depend on user interaction.
Add a <script> tag pointing at the compiled tracing library. This can be your own build result (if building from source), a copy of the library stored on your own server, or the publicly hosted one on Github. Note that the Github hosted version will not load on HTTPS pages, so you will have to copy it to your own server first.
After loading the library it must be initialized and started. You should do this with another <script> tag immediately following the previous one and again before any other scripts. This tag initializes options used by the library, optionally shows the on-screen HUD, and starts tracing right away (usually the desired behavior).
<html>
<head>
<!-- These MUST be before any other scripts! -->
<script src="http://google.github.io/tracing-framework/bin/wtf_trace_web_js_compiled.js"></script>
<script>
var options = {
/* options, if any */
};
// Setup tracing with the given options.
wtf.trace.prepare(options);
// Optionally, create the on-screen HUD for better control.
wtf.hud.prepare(options);
// Start recording a trace immediately (if desired).
wtf.trace.start(options);
</script>
<!-- Add your stuff here... -->
</head>
</html>
For more details about the options that can be passed see the options documentation and the event providers page.
The easiest way to get the tracing framework to record your application is to use the wtf-trace tool included with the NPM package. This allows you to run any other node app with the library already present and recording at startup and will dump the trace file when the application ends (or CTRL-C is used).
$ wtf-trace myapp.js Running... <ctrl-c> $ ls *.wtf-trace myapp-123456.wtf-trace
When more control is desired you can instead directly require and setup the library. First you must obtain the wtf_node_js_compiled.js file, which can be found in the node_modules/tracing-framework/build-out/ directory from your NPM install.
// Require from wherever the library happens to be.
global.wtf = require('tracing-framework');
// Provide any options here.
var options = {
/* options, if any */
};
// Start tracing with a handler for ctrl-c saving.
wtf.trace.node.start(options);
If you prefer to more tightly control the trace recording you can call the normal API instead:
global.wtf = require('tracing-framework');
wtf.trace.prepare({ /* options, if any */ });
// Later on, when desired:
wtf.trace.start();
// Do stuff...
wtf.trace.snapshot();
Once the library is included and initialized as above one must record and save off traces. When using the on-screen HUD such as when added via the Chrome Extension this is as easy as clicking a button, but otherwise you must control the recording and saving yourself. Note that even with the HUD enabled it's still possible to use the programmatic control as described below.
The on-screen HUD provides several options for saving, resetting, and showing trace snapshots. You can easily reset the current data, save a snapshot to disk, or open a new UI with the data loaded with either buttons or hotkeys.
TIP: hold shift while clicking 'Show in UI' to open the trace in a new window.
TIP: see the tooltips on the buttons for keyboard keys that perform the action.
Screenshot showing the on-screen HUD buttons.
Screenshot showing saving a trace file for later use.
Screenshot showing how to snapshot and open the UI.
Programmatically capturing traces can be useful when trying to gather data from specific timeranges, reducing the interference of the framework by not showing the HUD, or trying to automate trace capture.
// Start capturing immediately.
wtf.trace.start({
/* option overrides, if any */
});
// Reset the current buffer, clearing all recorded events.
wtf.trace.reset();
// Stop capturing and cleanup.
wtf.trace.stop();
Captures are started with the wtf.trace.start() API. This takes an optional object dictionary that can override any options that were previously passed to a wtf.trace.prepare() call or were setup by the extension.
The trace begins recording immediately after the call returns and when in snapshotting mode any new events are appended to the buffer. If you want to clear the buffer (for example, to ignore previous uninteresting events) you can use wtf.trace.reset().
When the capture session is no longer required a call to wtf.trace.stop() is used to clean up any resources used by the snapshot. After this the data is disposed and there is no way to save it. Any future calls to wtf.trace.start() will begin with a clean buffer.
// Save a snapshot with the default save options (file named on page/time):
wtf.trace.snapshot();
// Save a file with the given prefix:
wtf.trace.snapshot('file://myprefix');
// Grab the binary data from the snapshot:
var buffers = [];
wtf.trace.snapshot(buffers);
console.log(buffers[0]); // a Uint8Array of the data
Snapshots are saved on demand and can be either saved to a file, posted to a remote HTTP server, or grabbed in memory for custom saving.
If desired, an default save target can be passed when the library is initialized so that it needs not be passed to each snapshot call:
// Specify a default save name (used for snapshots unless overridden).
wtf.trace.prepare({
'wtf.trace.target': 'file://myname'
});
// No need to pass a name here, the given target will be used:
wtf.trace.snapshot();
The easiest way to view a trace is to open it directly from the on-screen HUD. The 'Show in UI' button will capture a new trace and pop up a new UI window with the trace loaded, ready for inspection. If you wish to save this trace for later comparison or sharing you can use the 'Save' button.
You can always use the hosted version available on Github:
http://google.github.io/tracing-framework/bin/app/maindisplay.html
If using the Chrome extension you can open the UI quickly:
Screenshot showing how to open the UI at any time.
If you've saved a trace and have a .wtf-trace file there are several ways to load it.
wtf omnibar keyword in Chrome to open URLs directly.TIP: Drag/drop new files into the UI to update with the latest data.
Screenshot showing drag/drop loading of a file.
Screenshot showing opening a URL from the omnibox.
It's possible to use the Github-hosted UI page to easily share traces with people who may not have the tracing framework extension installed. The simplest is to give them the URL to the UI, http://google.github.io/tracing-framework/bin/app/maindisplay.html, and tell them to open the file you've shared.
Alternatively, the UI page accepts a ?url=http://... query parameter that allows for loading a trace from a given source. Beware that the target must allow cross-origin XHRs via cross-origin resource sharing or it will fail to load.
You're not done yet!
To get the most from the tracing framework you'll need to adjust settings, instrument your code, and learn what all the data means.
Enable or disable built-in event providers to get more information or reduce tracing overhead.
Get the most out of traces by efficiently tracing your application and its data.
Find out what the different data means and how to get useful information out of traces.
Learn more about the advanced features of the framework such as native browser tracing, remote control, and memory allocation tracking.
Add your own custom data providers and visualizers.