tracing: add v8 specific tracing api

doc/api/_toc.markdown

@@ -29,6 +29,7 @@
 * [String Decoder](string_decoder.html)
 * [Timers](timers.html)
 * [TLS/SSL](tls.html)
+* [Tracing](tracing.html)
 * [TTY](tty.html)
 * [UDP/Datagram](dgram.html)
 * [URL](url.html)

doc/api/all.markdown

@@ -35,3 +35,4 @@
 @include debugger
 @include cluster
 @include smalloc
+@include tracing

doc/api/tracing.markdown

@@ -0,0 +1,61 @@
+# Tracing
+
+    Stability: 1 - Experimental
+
+The tracing module is designed for instrumenting your Node application. It is
+not meant for general purpose use.
+
+***Be very careful with callbacks used in conjunction with this module***
+
+Many of these callbacks interact directly with asynchronous subsystems in a
+synchronous fashion. That is to say, you may be in a callback where a call to
+`console.log()` could result in an infinite recursive loop.  Also of note, many
+of these callbacks are in hot execution code paths. That is to say your
+callbacks are executed quite often in the normal operation of Node, so be wary
+of doing CPU bound or synchronous workloads in these functions. Consider a ring
+buffer and a timer to defer processing.
+
+`require('tracing')` to use this module.
+
+## v8
+
+The `v8` property is an [EventEmitter][], it exposes events and interfaces
+specific to the version of `v8` built with node. These interfaces are subject
+to change by upstream and are therefore not covered under the stability index.
+
+### Event: 'gc'
+
+`function (before, after) { }`
+
+Emitted each time a GC run is completed.
+
+`before` and `after` are objects with the following properties:
+
+```
+{
+  type: 'mark-sweep-compact',
+  flags: 0,
+  timestamp: 905535650119053,
+  total_heap_size: 6295040,
+  total_heap_size_executable: 4194304,
+  total_physical_size: 6295040,
+  used_heap_size: 2855416,
+  heap_size_limit: 1535115264
+}
+```
+
+### getHeapStatistics()
+
+Returns an object with the following properties
+
+```
+{
+  total_heap_size: 7326976,
+  total_heap_size_executable: 4194304,
+  total_physical_size: 7326976,
+  used_heap_size: 3476208,
+  heap_size_limit: 1535115264
+}
+```
+
+[EventEmitter]: events.html#events_class_events_eventemitter

lib/repl.js

@@ -73,7 +73,8 @@ exports.writer = util.inspect;
 exports._builtinLibs = ['assert', 'buffer', 'child_process', 'cluster',
   'crypto', 'dgram', 'dns', 'domain', 'events', 'fs', 'http', 'https', 'net',
   'os', 'path', 'punycode', 'querystring', 'readline', 'stream',
-  'string_decoder', 'tls', 'tty', 'url', 'util', 'vm', 'zlib', 'smalloc'];
+  'string_decoder', 'tls', 'tty', 'url', 'util', 'vm', 'zlib', 'smalloc',
+  'tracing'];
 
 
 function REPLServer(prompt, stream, eval_, useGlobal, ignoreUndefined) {

lib/tracing.js

@@ -0,0 +1,41 @@
+// Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+var EventEmitter = require('events');
+var binding = process.binding('v8');
+
+var v8 = exports.v8 = new EventEmitter();
+
+v8.on('newListener', function(name) {
+  if (name === 'gc' && EventEmitter.listenerCount(this, name) === 0) {
+    binding.startGarbageCollectionTracking(function emitGC(before, after) {
+      v8.emit('gc', before, after);
+    });
+  }
+});
+
+v8.on('removeListener', function(name) {
+  if (name === 'gc' && EventEmitter.listenerCount(this, name) === 0) {
+    binding.stopGarbageCollectionTracking();
+  }
+});
+
+v8.getHeapStatistics = binding.getHeapStatistics;

node.gyp

@@ -56,6 +56,7 @@
       'lib/string_decoder.js',
       'lib/sys.js',
       'lib/timers.js',
+      'lib/tracing.js',
       'lib/tls.js',
       'lib/_tls_legacy.js',
       'lib/_tls_wrap.js',
@@ -96,6 +97,7 @@
         'src/node_javascript.cc',
         'src/node_main.cc',
         'src/node_os.cc',
+        'src/node_v8.cc',
         'src/node_stat_watcher.cc',
         'src/node_watchdog.cc',
         'src/node_zlib.cc',

src/env-inl.h

@@ -33,9 +33,48 @@
 
 namespace node {
 
+inline Environment::GCInfo::GCInfo()
+    : type_(static_cast<v8::GCType>(0)),
+      flags_(static_cast<v8::GCCallbackFlags>(0)),
+      timestamp_(0) {
+}
+
+inline Environment::GCInfo::GCInfo(v8::Isolate* isolate,
+                                   v8::GCType type,
+                                   v8::GCCallbackFlags flags,
+                                   uint64_t timestamp)
+    : type_(type),
+      flags_(flags),
+      timestamp_(timestamp) {
+  isolate->GetHeapStatistics(&stats_);
+}
+
+inline v8::GCType Environment::GCInfo::type() const {
+  return type_;
+}
+
+inline v8::GCCallbackFlags Environment::GCInfo::flags() const {
+  return flags_;
+}
+
+inline v8::HeapStatistics* Environment::GCInfo::stats() const {
+  // TODO(bnoordhuis) Const-ify once https://codereview.chromium.org/63693005
+  // lands and makes it way into a stable release.
+  return const_cast<v8::HeapStatistics*>(&stats_);
+}
+
+inline uint64_t Environment::GCInfo::timestamp() const {
+  return timestamp_;
+}
+
+inline Environment::IsolateData* Environment::IsolateData::Get(
+    v8::Isolate* isolate) {
+  return static_cast<IsolateData*>(isolate->GetData());
+}
+
 inline Environment::IsolateData* Environment::IsolateData::GetOrCreate(
     v8::Isolate* isolate) {
-  IsolateData* isolate_data = static_cast<IsolateData*>(isolate->GetData());
+  IsolateData* isolate_data = Get(isolate);
   if (isolate_data == NULL) {
     isolate_data = new IsolateData(isolate);
     isolate->SetData(isolate_data);
@@ -59,6 +98,7 @@ inline Environment::IsolateData::IsolateData(v8::Isolate* isolate)
     PER_ISOLATE_STRING_PROPERTIES(V)
 #undef V
     ref_count_(0) {
+  QUEUE_INIT(&gc_tracker_queue_);
 }
 
 inline uv_loop_t* Environment::IsolateData::event_loop() const {
@@ -187,6 +227,7 @@ inline Environment::Environment(v8::Local<v8::Context> context)
   set_binding_cache_object(v8::Object::New());
   set_module_load_list_array(v8::Array::New());
   RB_INIT(&cares_task_list_);
+  QUEUE_INIT(&gc_tracker_queue_);
 }
 
 inline Environment::~Environment() {

src/env.h

@@ -27,6 +27,7 @@
 #include "util.h"
 #include "uv.h"
 #include "v8.h"
+#include "queue.h"
 
 #include <stdint.h>
 
@@ -52,9 +53,9 @@ namespace node {
 // for the sake of convenience.
 #define PER_ISOLATE_STRING_PROPERTIES(V)                                      \
   V(address_string, "address")                                                \
-  V(atime_string, "atime")                                                    \
-  V(async, "async")                                                           \
   V(async_queue_string, "_asyncQueue")                                        \
+  V(async, "async")                                                           \
+  V(atime_string, "atime")                                                    \
   V(birthtime_string, "birthtime")                                            \
   V(blksize_string, "blksize")                                                \
   V(blocks_string, "blocks")                                                  \
@@ -78,16 +79,19 @@ namespace node {
   V(family_string, "family")                                                  \
   V(fatal_exception_string, "_fatalException")                                \
   V(fingerprint_string, "fingerprint")                                        \
+  V(flags_string, "flags")                                                    \
   V(gid_string, "gid")                                                        \
   V(handle_string, "handle")                                                  \
   V(headers_string, "headers")                                                \
+  V(heap_size_limit_string, "heap_size_limit")                                \
   V(heap_total_string, "heapTotal")                                           \
   V(heap_used_string, "heapUsed")                                             \
   V(immediate_callback_string, "_immediateCallback")                          \
   V(ino_string, "ino")                                                        \
   V(ipv4_string, "IPv4")                                                      \
   V(ipv6_string, "IPv6")                                                      \
   V(issuer_string, "issuer")                                                  \
+  V(mark_sweep_compact_string, "mark-sweep-compact")                          \
   V(method_string, "method")                                                  \
   V(mode_string, "mode")                                                      \
   V(modulus_string, "modulus")                                                \
@@ -114,6 +118,7 @@ namespace node {
   V(rdev_string, "rdev")                                                      \
   V(rename_string, "rename")                                                  \
   V(rss_string, "rss")                                                        \
+  V(scavenge_string, "scavenge")                                              \
   V(serial_number_string, "serialNumber")                                     \
   V(servername_string, "servername")                                          \
   V(session_id_string, "sessionId")                                           \
@@ -126,10 +131,16 @@ namespace node {
   V(subject_string, "subject")                                                \
   V(subjectaltname_string, "subjectaltname")                                  \
   V(syscall_string, "syscall")                                                \
+  V(timestamp_string, "timestamp")                                            \
   V(tls_ticket_string, "tlsTicket")                                           \
+  V(total_heap_size_executable_string, "total_heap_size_executable")          \
+  V(total_heap_size_string, "total_heap_size")                                \
+  V(total_physical_size_string, "total_physical_size")                        \
+  V(type_string, "type")                                                      \
   V(uid_string, "uid")                                                        \
   V(upgrade_string, "upgrade")                                                \
   V(url_string, "url")                                                        \
+  V(used_heap_size_string, "used_heap_size")                                  \
   V(valid_from_string, "valid_from")                                          \
   V(valid_to_string, "valid_to")                                              \
   V(version_major_string, "versionMajor")                                     \
@@ -145,6 +156,7 @@ namespace node {
   V(buffer_constructor_function, v8::Function)                                \
   V(context, v8::Context)                                                     \
   V(domain_array, v8::Array)                                                  \
+  V(gc_info_callback_function, v8::Function)                                  \
   V(module_load_list_array, v8::Array)                                        \
   V(pipe_constructor_template, v8::FunctionTemplate)                          \
   V(process_object, v8::Object)                                               \
@@ -251,6 +263,10 @@ class Environment {
   static inline Environment* New(v8::Local<v8::Context> context);
   inline void Dispose();
 
+  // Defined in src/node_profiler.cc.
+  void StartGarbageCollectionTracking(v8::Local<v8::Function> callback);
+  void StopGarbageCollectionTracking();
+
   inline v8::Isolate* isolate() const;
   inline uv_loop_t* event_loop() const;
   inline bool has_async_listener() const;
@@ -296,10 +312,13 @@ class Environment {
 #undef V
 
  private:
+  class GCInfo;
   class IsolateData;
   inline explicit Environment(v8::Local<v8::Context> context);
   inline ~Environment();
   inline IsolateData* isolate_data() const;
+  void AfterGarbageCollectionCallback(const GCInfo* before,
+                                      const GCInfo* after);
 
   enum ContextEmbedderDataIndex {
     kContextEmbedderDataIndex = NODE_CONTEXT_EMBEDDER_DATA_INDEX
@@ -319,28 +338,64 @@ class Environment {
   ares_task_list cares_task_list_;
   bool using_smalloc_alloc_cb_;
   bool using_domains_;
+  QUEUE gc_tracker_queue_;
 
 #define V(PropertyName, TypeName)                                             \
   v8::Persistent<TypeName> PropertyName ## _;
   ENVIRONMENT_STRONG_PERSISTENT_PROPERTIES(V)
 #undef V
 
+  class GCInfo {
+   public:
+    inline GCInfo();
+    inline GCInfo(v8::Isolate* isolate,
+                  v8::GCType type,
+                  v8::GCCallbackFlags flags,
+                  uint64_t timestamp);
+    inline v8::GCType type() const;
+    inline v8::GCCallbackFlags flags() const;
+    // TODO(bnoordhuis) Const-ify once https://codereview.chromium.org/63693005
+    // lands and makes it way into a stable release.
+    inline v8::HeapStatistics* stats() const;
+    inline uint64_t timestamp() const;
+   private:
+    v8::GCType type_;
+    v8::GCCallbackFlags flags_;
+    v8::HeapStatistics stats_;
+    uint64_t timestamp_;
+  };
+
   // Per-thread, reference-counted singleton.
   class IsolateData {
    public:
     static inline IsolateData* GetOrCreate(v8::Isolate* isolate);
     inline void Put();
     inline uv_loop_t* event_loop() const;
 
+    // Defined in src/node_profiler.cc.
+    void StartGarbageCollectionTracking(Environment* env);
+    void StopGarbageCollectionTracking(Environment* env);
+
 #define V(PropertyName, StringValue)                                          \
     inline v8::Local<v8::String> PropertyName() const;
     PER_ISOLATE_STRING_PROPERTIES(V)
 #undef V
 
    private:
+    inline static IsolateData* Get(v8::Isolate* isolate);
     inline explicit IsolateData(v8::Isolate* isolate);
     inline v8::Isolate* isolate() const;
 
+    // Defined in src/node_profiler.cc.
+    static void BeforeGarbageCollection(v8::Isolate* isolate,
+                                        v8::GCType type,
+                                        v8::GCCallbackFlags flags);
+    static void AfterGarbageCollection(v8::Isolate* isolate,
+                                       v8::GCType type,
+                                       v8::GCCallbackFlags flags);
+    void BeforeGarbageCollection(v8::GCType type, v8::GCCallbackFlags flags);
+    void AfterGarbageCollection(v8::GCType type, v8::GCCallbackFlags flags);
+
     uv_loop_t* const event_loop_;
     v8::Isolate* const isolate_;
 
@@ -350,6 +405,9 @@ class Environment {
 #undef V
 
     unsigned int ref_count_;
+    QUEUE gc_tracker_queue_;
+    GCInfo gc_info_before_;
+    GCInfo gc_info_after_;
 
     DISALLOW_COPY_AND_ASSIGN(IsolateData);
   };