WTF?
A powerful toolset for investigating the performance of rich Javascript applications.
+------------------+ +-----------------+ +--------------------+
| Your Application | | WTF Analysis UI | | Command Line Tools |
+------------------+ +-----------------+ +--------------------+
| wtf-shim.js | ^ ^
+--------+---------+ | |
| +---------+-----------+
v |
+------------------+ +---------------+ +---------+--------+
| Tracing Library +--->| foo.wtf-trace +--->| Analysis Library |
+------------------+ +---------------+ +------------------+
The Web Tracing Framework is a collection of libraries, tools, and scripts aimed at web developers trying to write large, performance-sensitive Javascript applications. It's designed to be used in conjunction with the built-in development tools of browsers but goes far beyond what they usually support at the cost of some user setup time.
The development tools in modern browsers like Chrome and Firefox are pretty amazing. They've got great sampling profilers, live editing, debugging, and are constantly adding more features. Most developers can make (and have been making) the web an engaging place with them. But just as skilled native platform developers often run past the features in Visual Studio or Xcode and augment their work-flow with VTune, Telemetry, and other tools web developers are starting to need the same. Enter the Web Tracing Framework.
This is not a tool for everyone. It requires time to instrument code and understand how to analyze traces and for most simple web pages it's not worth it. But if you're building a Javascript-heavy page that tries to reach 60 frames per second, smoothly react to user input, or load as quickly as possible then you should continue reading.
Learning about the Web Tracing Framework and the data it provides is a journey that will change the way you write (and judge) Javascript. It is not trivial, but it is often worth it.
The tracing framework and its tools are still very young. The feature list will continue to grow in an organic fashion.
Have something you want to see? File an issue or contribute!
The tracing framework operations on a capture-and-analyze cycle. You instrument your code, capture data, and analyze it. You can then either refine your instrumentation or change what you're testing and repeat the process.
+-------------------+
| Instrument Code +---------------+
+-------------------+ v
^ +------------------+
| | Capture Traces |
| +---------+--------+
+---------+--------+ |
| Analyze Traces |<--------------+
+------------------+
Instrumentation is optional, with some built-in browser events automatically being traced, however to get the most benefit from the tool you should at least add events for the major functions of your application. More advanced instrumentation such as asynchronous event flows and time ranges can be added to make navigating traces even easier.
After instrumenting you need to either inject the framework onto your page via the Chrome or Firefox extension or by manually embedding it, as found in the Getting Started guide. This adds a small heads-up-display (HUD) that can be used to control the state of the library or change settings.
Snapshots can be captured and either downloaded for later analysis or opened in a pop-out UI. It's also possible to programmatically capture traces if running inside of a test system. The snapshot contains all data since the page loaded or the snapshot was cleared with a button on the HUD. If the buffer fills up then old data is overwritten in a circular fashion, meaning that you can usually keep the library active while using an application and snapshot at any time.
A captured trace can be opened using the UI popped up from the page, opened via the extension, or hosted on Github. This is the fun part!
Repeat until fast!
"There ain't no such thing as a free lunch."
As with any performance measurement tool there are gotchas. The act of measuring activity with the tracing framework will change the performance characteristics of what's being measured. As a user of the tool you must be aware of this, lest you run down issues that real users would never hit.
You can find more information about a lot of the side-effects of certain features documented with the feature itself on the other pages. This is merely a summary and some of the big concepts.
More details about the overhead of the framework can be found in the overhead document.
Do use the tracing framework to help guide you towards problem areas in your code, check for regressions, and learn about your application.
Do not use the tracing framework to blindly apply microoptimizations or mangle your code.
The Web Tracing Framework uses instrumentation to record its data which naturally has some overhead. Modern Javascript engines and the browsers they run within are insanely complex and can change their behavior in interesting ways when instrumented. When inspecting long traces from large applications from 50,000ft you can often trust the insights you find in the tool. But become more wary of the data the closer in you zoom - if you're trying to make an optimization based on timings in the microseconds with the tracing framework you will not have good results.
The Web Tracing Framework is only really useful in environments that support high-resolution timing. In the browser space this means required support for performance.now. If the target environment doesn't have this method (Mobile Safari, Web Workers, etc) or a broken implementation then the traces will be useful for structural information only. You can easily tell if your target browser is not supported when all times appear rounded to the nearest millisecond.
Even if your environment does have a high-resolution timer beware of the overhead of calling it. Not only is there usually hundreds of nanoseconds involved in getting the time, but the resolution of performance.now is only to the nearest microsecond. This means that a pair of trace events surrounding a single assembly instruction can appear to consume as much as 2 microseconds! It's up to the developer instrumenting the code to know when to avoid adding events that are mostly overhead or ignore the data when viewing a trace that has them.
Every method instrumented or piece of data traced adds additional overhead to the application that can skew trace data. On larger projects careful attention must be paid by developers and code reviewers to ensure that only the most necessary events get committed. It's strongly recommended that instrumented methods are frequently 'gardened' to find and remove events that are no longer providing useful information or being called frequently enough to degrade the trace quality.
enterScope, appendScopeData, or timeStampThere are two major components in the tracing framework that are dependent on the browser: the tracing library and the analysis application.
The instrumentation library that gets embedded onto pages runs in many different browser environments (and node.js). However, unless the environment supports high-resolution timing the traces won't be very interesting.
| Feature | Chrome Release channel (26+) | Firefox Release channel (20+) | Internet Explorer 10+ |
|---|---|---|---|
| High-resolution timing | ✔ ✝ | ✔ | ✔ |
| Custom events | ✔ | ✔ | ✔ |
| Garbage collection events | ✔ | ✔ | ✘ |
| Native browser tracing | ✔ | ✘ | ✘ |
| Memory tracking | ✔ | ✘ | ✘ |
| Web Workers | ✘ | ✘ | ✘ |
✝ Chrome Windows currently does not support the high-resolution timer API. Issue 158234.
Though traces can be captured on many platforms, the UI is designed to work on Chrome (desktop) and Firefox (though support is largely untested). Future versions may support more browsers. Feel free to help out if you care!
| Chrome Release channel (26+) | Firefox Release channel (20+) | Internet Explorer 10+ |
|---|---|---|
| ✔ | ✔ ✝ | ✘ |
✝ The UI in Firefox is mostly untested. There are some issues with resizing panels and animations.
How to RTFM.
This website will be kept up to date with high level guides and examples. For the details, however, it's recommended that you look at the GitHub project.
The documentation directory in the Github project is kept up to date with detailed feature documentation and other information.
Though it's not recommended that the file format is relied upon, the various types of files supported by the framework are documented here: