From 70aad83b07a870e9a6a6d3fb55ea261c6c1424b8 Mon Sep 17 00:00:00 2001
From: Cheng Zhao <zcbenz@gmail.com>
Date: Thu, 31 Jul 2014 15:40:40 +0800
Subject: [PATCH] Add docs on content-tracing module.

---
 docs/README.md              |   1 +
 docs/api/content-tracing.md | 136 ++++++++++++++++++++++++++++++++++++
 2 files changed, 137 insertions(+)
 create mode 100644 docs/api/content-tracing.md

diff --git a/docs/README.md b/docs/README.md
index 527a7a5bde9..117cd88c3b9 100644
--- a/docs/README.md
+++ b/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)
diff --git a/docs/api/content-tracing.md b/docs/api/content-tracing.md
new file mode 100644
index 00000000000..e020b3a55a3
--- /dev/null
+++ b/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.