Add docs on content-tracing module.

docs/README.md

@@ -14,6 +14,7 @@ Modules for browser side:
 * [app](api/app.md)
 * [auto-updater](api/auto-updater.md)
 * [browser-window](api/browser-window.md)
+* [content-tracing](api/content-tracing.md)
 * [dialog](api/dialog.md)
 * [ipc (browser)](api/ipc-browser.md)
 * [menu](api/menu.md)

docs/api/content-tracing.md

@@ -0,0 +1,136 @@
+# content-tracing
+
+The `content-trace` module is used to collect tracing data generated by the
+underlying Chromium content module. This module does not include a web interface
+so you need to open `chrome://tracing/` in Chrome browser and load the generated
+file to view the result.
+
+```javascript
+var tracing = require('content-tracing');
+tracing.startRecording('*', tracing.DEFAULT_OPTIONS, function() {
+  console.log('Tracing started');
+
+  setTimeout(function() {
+    tracing.stopRecording('', function(path) {
+      console.log('Tracing data recorded to ' + path);
+    });
+  }, 5000);
+});
+```
+
+## tracing.getCategories(callback)
+
+* `callback` Function
+
+Get a set of category groups. The category groups can change as new code paths
+are reached.
+
+Once all child processes have acked to the `getCategories` request, `callback`
+is called back with an array of category groups.
+
+## tracing.startRecording(categoryFilter, options, callback)
+
+* `categoryFilter` String
+* `options` Integer
+* `callback` Function
+
+Start recording on all processes.
+
+Recording begins immediately locally, and asynchronously on child processes
+as soon as they receive the EnableRecording request. Once all child processes
+have acked to the `startRecording` request, `callback` will be called back.
+
+`categoryFilter` is a filter to control what category groups should be
+traced. A filter can have an optional `-` prefix to exclude category groups
+that contain a matching category. Having both included and excluded
+category patterns in the same list would not be supported.
+
+Examples:
+
+* `test_MyTest*`,
+* `test_MyTest*,test_OtherStuff`,
+* `"-excluded_category1,-excluded_category2`
+
+`options` controls what kind of tracing is enabled, it could be a OR-ed
+combination of `tracing.DEFAULT_OPTIONS`, `tracing.ENABLE_SYSTRACE`,
+`tracing.ENABLE_SAMPLING` and `tracing.RECORD_CONTINUOUSLY`.
+
+## tracing.stopRecording(resultFilePath, callback)
+
+* `resultFilePath` String
+* `callback` Function
+
+Stop recording on all processes.
+
+Child processes typically are caching trace data and only rarely flush and send
+trace data back to the browser process. That is because it may be an expensive
+operation to send the trace data over IPC, and we would like to avoid much
+runtime overhead of tracing. So, to end tracing, we must asynchronously ask all
+child processes to flush any pending trace data.
+
+Once all child processes have acked to the `stopRecording` request, `callback`
+will be called back with a file that contains the traced data.
+
+Trace data will be written into `resultFilePath` if it is not empty, or into a
+temporary file. The actual file path will be passed to `callback` if it's not
+null.
+
+## tracing.startMonitoring(categoryFilter, options, callback)
+
+* `categoryFilter` String
+* `options` Integer
+* `callback` Function
+
+Start monitoring on all processes.
+
+Monitoring begins immediately locally, and asynchronously on child processes as
+soon as they receive the `startMonitoring` request.
+
+Once all child processes have acked to the `startMonitoring` request, `callback`
+will be called back.
+
+## tracing.stopMonitoring(callback);
+
+* `callback` Function
+
+Stop monitoring on all processes.
+
+Once all child processes have acked to the `stopMonitoring` request, `callback`
+is called back.
+
+## tracing.captureMonitoringSnapshot(resultFilePath, callback)
+
+* `resultFilePath` String
+* `callback` Function
+
+Get the current monitoring traced data.
+
+Child processes typically are caching trace data and only rarely flush and send
+trace data back to the browser process. That is because it may be an expensive
+operation to send the trace data over IPC, and we would like to avoid much
+runtime overhead of tracing. So, to end tracing, we must asynchronously ask all
+child processes to flush any pending trace data.
+
+Once all child processes have acked to the `captureMonitoringSnapshot` request,
+`callback` will be called back with a file that contains the traced data.
+
+
+## tracing.getTraceBufferPercentFull(callback)
+
+* `callback` Function
+
+Get the maximum across processes of trace buffer percent full state.  When the
+TraceBufferPercentFull value is determined, the `callback` is called.
+
+## tracing.setWatchEvent(categoryName, eventName, callback)
+
+* `categoryName` String
+* `eventName` String
+* `callback` Function
+
+`callback` will will be called every time the given event occurs on any process.
+
+## tracing.cancelWatchEvent()
+
+Cancel the watch event. If tracing is enabled, this may race with the watch
+event callback.