Merge pull request #538 from atom/tracing-module

Add content-tracing module

atom.gyp

@@ -18,6 +18,7 @@
       'atom/browser/api/lib/atom-delegate.coffee',
       'atom/browser/api/lib/auto-updater.coffee',
       'atom/browser/api/lib/browser-window.coffee',
+      'atom/browser/api/lib/content-tracing.coffee',
       'atom/browser/api/lib/dialog.coffee',
       'atom/browser/api/lib/ipc.coffee',
       'atom/browser/api/lib/menu.coffee',
@@ -51,6 +52,7 @@
       'atom/browser/api/atom_api_app.h',
       'atom/browser/api/atom_api_auto_updater.cc',
       'atom/browser/api/atom_api_auto_updater.h',
+      'atom/browser/api/atom_api_content_tracing.cc',
       'atom/browser/api/atom_api_dialog.cc',
       'atom/browser/api/atom_api_menu.cc',
       'atom/browser/api/atom_api_menu.h',

atom/browser/api/atom_api_content_tracing.cc

@@ -0,0 +1,77 @@
+// Copyright (c) 2014 GitHub, Inc. All rights reserved.
+// Use of this source code is governed by the MIT license that can be
+// found in the LICENSE file.
+
+#include <set>
+
+#include "atom/common/native_mate_converters/file_path_converter.h"
+#include "atom/common/native_mate_converters/function_converter.h"
+#include "base/bind.h"
+#include "content/public/browser/tracing_controller.h"
+#include "native_mate/dictionary.h"
+
+#include "atom/common/node_includes.h"
+
+using content::TracingController;
+
+namespace mate {
+
+template<typename T>
+struct Converter<std::set<T> > {
+  static v8::Handle<v8::Value> ToV8(v8::Isolate* isolate,
+                                    const std::set<T>& val) {
+    v8::Handle<v8::Array> result = v8::Array::New(
+        isolate, static_cast<int>(val.size()));
+    typename std::set<T>::const_iterator it;
+    int i;
+    for (i = 0, it = val.begin(); it != val.end(); ++it, ++i)
+      result->Set(i, Converter<T>::ToV8(isolate, *it));
+    return result;
+  }
+};
+
+template<>
+struct Converter<TracingController::Options> {
+  static bool FromV8(v8::Isolate* isolate,
+                     v8::Handle<v8::Value> val,
+                     TracingController::Options* out) {
+    if (!val->IsNumber())
+      return false;
+    *out = static_cast<TracingController::Options>(val->IntegerValue());
+    return true;
+  }
+};
+
+}  // namespace mate
+
+namespace {
+
+void Initialize(v8::Handle<v8::Object> exports, v8::Handle<v8::Value> unused,
+                v8::Handle<v8::Context> context, void* priv) {
+  TracingController* controller = TracingController::GetInstance();
+  mate::Dictionary dict(context->GetIsolate(), exports);
+  dict.SetMethod("getCategories", base::Bind(
+      &TracingController::GetCategories, base::Unretained(controller)));
+  dict.SetMethod("startRecording", base::Bind(
+      &TracingController::EnableRecording, base::Unretained(controller)));
+  dict.SetMethod("stopRecording", base::Bind(
+      &TracingController::DisableRecording, base::Unretained(controller)));
+  dict.SetMethod("startMonitoring", base::Bind(
+      &TracingController::EnableMonitoring, base::Unretained(controller)));
+  dict.SetMethod("stopMonitoring", base::Bind(
+      &TracingController::DisableMonitoring, base::Unretained(controller)));
+  dict.SetMethod("captureMonitoringSnapshot", base::Bind(
+      &TracingController::CaptureMonitoringSnapshot,
+      base::Unretained(controller)));
+  dict.SetMethod("getTraceBufferPercentFull", base::Bind(
+      &TracingController::GetTraceBufferPercentFull,
+      base::Unretained(controller)));
+  dict.SetMethod("setWatchEvent", base::Bind(
+      &TracingController::SetWatchEvent, base::Unretained(controller)));
+  dict.SetMethod("cancelWatchEvent", base::Bind(
+      &TracingController::CancelWatchEvent, base::Unretained(controller)));
+}
+
+}  // namespace
+
+NODE_MODULE_CONTEXT_AWARE_BUILTIN(atom_browser_content_tracing, Initialize)

atom/browser/api/atom_api_dialog.cc

@@ -5,13 +5,13 @@
 #include <string>
 #include <vector>
 
-#include "base/bind.h"
 #include "atom/browser/api/atom_api_window.h"
 #include "atom/browser/native_window.h"
 #include "atom/browser/ui/file_dialog.h"
 #include "atom/browser/ui/message_box.h"
 #include "atom/common/native_mate_converters/file_path_converter.h"
 #include "atom/common/native_mate_converters/function_converter.h"
+#include "base/bind.h"
 #include "native_mate/dictionary.h"
 
 #include "atom/common/node_includes.h"

atom/browser/api/lib/content-tracing.coffee

@@ -0,0 +1,7 @@
+module.exports = process.atomBinding 'content_tracing'
+
+# Mirrored from content::TracingController::Options
+module.exports.DEFAULT_OPTIONS = 0
+module.exports.ENABLE_SYSTRACE = 1 << 0
+module.exports.ENABLE_SAMPLING = 1 << 1
+module.exports.RECORD_CONTINUOUSLY = 1 << 2

atom/common/node_bindings.cc

@@ -61,6 +61,7 @@ REFERENCE_MODULE(uv);
 // Atom Shell's builtin modules.
 REFERENCE_MODULE(atom_browser_app);
 REFERENCE_MODULE(atom_browser_auto_updater);
+REFERENCE_MODULE(atom_browser_content_tracing);
 REFERENCE_MODULE(atom_browser_dialog);
 REFERENCE_MODULE(atom_browser_menu);
 REFERENCE_MODULE(atom_browser_power_monitor);

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.