All of the built-in events in WTF are handled by event providers included with the library. They can be enabled or disabled depending on what kind of data one wants to trace and how much overhead they want.

Don't see a provider you want? Contribute one!

Configuring with the Extension

Screenshot of the provider options screen.

The easiest way to configure providers is to use the settings screen accessible from the gear button on the on-page HUD. When using the WTF browser extension the settings will be saved and reused on future page reloads. Each provider has a section containing the available options, the descriptions of which are listed below.

Configuring via Code

When embedding the tracing framework on a page manually it's required that options are set ahead of time via code. This can allow for complex custom URL-driven options sets (such as ?wtf-fast, ?wtf-all, etc) or setting options on browsers that may not be able to display the UI (like mobile devices or node.js).

wtf.trace.start({
  // Disable DOM provider.
  'wtf.trace.provider.dom': false,
  // Enable the WebGL provider with recording at startup.
  'wtf.trace.provider.webgl': true,
  'wtf.trace.provider.webgl.recordAtStartup': true
});

Shared Options

var options = {
  'wtf.trace.disableProviders': true
};

All providers can be quickly disabled with this option. This makes it easy to compare the overhead of traces with providers to those without or see if any provider is breaking the page.

wtf.trace.provider.chromeDebug

The Chrome debugging provider works in conjunction with the WTF Chrome extension to add many useful event types into traces, as well as adding features for capturing native traces. The provider adds a small amount of additional overhead as the Chrome debugger must be attached to get the events.

Use of this feature conflicts with the Chrome Dev Tools. If you have the dev tools open when the page loads or open them later on this feature will be disabled automatically. Closing the dev tools and reloading should make it work again

Screenshot of the debug bar. Do not close this!

Browser Events

var options = {
  'wtf.trace.provider.chromeDebug': true,
  'wtf.trace.provider.chromeDebug.timeline': true
};

This provider inserts events from the Chrome debugger timeline into traces. The events included in this set include garbage collections, script evaluation, browser paint and layout, and style operations. They're very useful for figuring out where the time in-between user callbacks is spent or where GCs are causing skipped frames.

Chrome Tracing

var options = {
  'wtf.trace.provider.chromeDebug': true,
  'wtf.trace.provider.chromeDebug.tracing': true
};

NOTE: you must launch Chrome with --remote-debugging-port=9222 for this to work.

NOTE: this may only work on very recent Chromes (dev channel/canary/Chromium).

This adds a toggle button to the on-page HUD that allows for the capture of chrome:tracing data. The Chrome data will then be stored in the resulting WTF file in addition to any normal WTF events. Currently only the page renderer thread and GPU process are stored in the trace.

This feature uses undocumented functionality inside of Chrome, and it seems to change rather frequently. If it stops working on a recent Chrome, file an issue. Older Chrome releases are unsupported.

For more information on this feature see Advanced Features.

wtf.trace.provider.dom

✝ Chrome requires calling wtf.trace.initializeDomEventProperties on DOM trees added after document load to handle on events.

This provider attempts to automatically add DOM related events to traces. Today it primarily wraps event callbacks from DOM elements but in the future may also log expensive DOM operations.

DOM Events

var options = {
  'wtf.trace.provider.dom': true
};

WARNING: startup timing will be incorrect when this is enabled.

Enabling event injection allows you to easily track time spent in the many events that come back from the DOM such as mouse move or resize. When enabled, all DOM elements and a few other special elements such as Window are automatically instrumented to record their events when the occur.

There is overhead involved in setting up the event injection as well as in recording the events. In most applications this will be minimal, however it's important to note that this overhead exists when trying to get exact timing around startup or events. For example, if trying to optimize application startup latency it's best to disable this provider to remove the startup impact.

wtf.trace.initializeDomEventProperties(el, opt_recursive)

var el = document.createElement('div');
buildElementTree(el);
// Instrument the event handlers recursively.
wtf.trace.initializeDomEventProperties(el, true);

Certain browsers (such as Chrome) require an additional call after new DOM has been constructed after document load. If you don't make this call on the new DOM elements their events will not be recorded. You should try to call it on entire DOM trees/fragments before they are added to the DOM, and although it's safe to call it on the same elements repeatedly you should avoid doing so for performance reasons.

wtf.trace.ignoreDomTree(el)

var el = document.createElement('a');
el.onclick = function(e) { console.log('hi!'); };
// Ignore the onclick events.
wtf.trace.ignoreDomTree(el);

It's often useful to ignore events on certain DOM trees, such as debug UI. You can quickly ignore an entire tree by using this API. There's no way to opt back in a subtree that has been ignored, so only call this on pieces of the UI you really don't want events from.

wtf.trace.provider.image

var options = {
  'wtf.trace.provider.image': true
};

This provider adds special handling to the Image object. The DOM event provider handles HTMLImageElement, but since support for the handling there is flaky this logic is split. If you want consistent, low-overhead tracing of image-related events, prefer using new Image(); and this provider.

wtf.trace.provider.xhr

var options = {
  'wtf.trace.provider.xhr': true
};

WARNING: calls to XHR open and send will have up to .1ms of overhead with this provider enabled.

XMLHttpRequest can often be difficult to debug due to its asynchronous nature. This provider records all method calls and events on the XHRs to make it easier to see who is making the requests and what kind of work is occurring as they progress. Since browsers are rather naive about how they call back XHR events it is useful to try minimizing the amount of work performed in the callbacks.

wtf.trace.provider.webgl

var options = {
  'wtf.trace.provider.webgl': true,
  'wtf.trace.provider.webgl.recordAtStartup': true,
  'wtf.trace.provider.webgl.replayable': true,
  'wtf.trace.provider.webgl.embedRemoteImages': false
};

This provider allows for WebGL call streams to be recorded at various levels of fidelity. It's useful for quickly seeing what kind of uploads and draws are occurring per frame with low overhead, finding every single WebGL call executed (with arguments), or even recording replayable frames.

By default the provider begins recording WebGL data immediately on startup. Since in certain recording modes the amount of data can be very large it can be useful to only record data when desired. When the wtf.trace.provider.webgl.recordAtStartup option is set to false a 'WebGL' button will show up on the on-page HUD that lets you toggle recording on and off. It will also force a WebGL context loss/restore when clicked, allowing for context creation to be observed in the trace.

Replayable traces will record a tremendous amount of data and cannot be used to get reliable timing information. When a trace is recorded with replay enabled a 'WebGL' tab will appear in the UI and all recorded WebGL frames can be replayed and inspected, similar to WebGL Inspector.

When recording in replayable mode references to remote images and videos will be recorded with their URL. Since some URLs are transient (blob URLs, etc) or may not be accessible from the machine performing the replay (URLs that are unique per session/cookie), an option, wtf.trace.provider.webgl.embedRemoteImages, exists to synchronously fetch and embed the data within the trace. This will result in very large trace files and cause a severe performance penalty each time an image is requested. Do not use this option when trying to get performance numbers.

wtf.trace.provider.webworker

var options = {
  'wtf.trace.provider.webworker': true
};

This provider adds instrumentation of Web Worker-related events, such as the methods and events on the Worker object. It also provides the ability to automatically instrument worker code with the tracing framework and proxy the results back to the main thread.

This is an experimental feature and may not work correctly in all browsers or in all situations. It may also have unmeasured performance impacts when trying to transmit a lot of data between workers. Support for workers spawning other workers is untested, as that feature of the spec is unimplemented in most browsers.

Automatic Injection

var options = {
  'wtf.trace.provider.webworker': true,
  'wtf.trace.provider.webworker.inject': true
};

It's possible to enable the automatic instrumentation of created workers with the tracing framework library. This makes it possible to instrument workers without any code changes using the extension at the cost of additional worker startup time.

Currently this feature is disabled by default until browsers gain support for high-resolution times in Web Workers. Track with Chrome issue 169318.