{ "source": "doc/api/tracing.markdown", "modules": [ { "textRaw": "Tracing", "name": "tracing", "stability": 1, "stabilityText": "Experimental", "desc": "

The tracing module is designed for instrumenting your Node application. It is\nnot meant for general purpose use.\n\n

\n

Be very careful with callbacks used in conjunction with this module\n\n

\n

Many of these callbacks interact directly with asynchronous subsystems in a\nsynchronous fashion. That is to say, you may be in a callback where a call to\nconsole.log() could result in an infinite recursive loop. Also of note, many\nof these callbacks are in hot execution code paths. That is to say your\ncallbacks are executed quite often in the normal operation of Node, so be wary\nof doing CPU bound or synchronous workloads in these functions. Consider a ring\nbuffer and a timer to defer processing.\n\n

\n

require('tracing') to use this module.\n\n

\n", "modules": [ { "textRaw": "v8", "name": "v8", "desc": "

The v8 property is an [EventEmitter][], it exposes events and interfaces\nspecific to the version of v8 built with node. These interfaces are subject\nto change by upstream and are therefore not covered under the stability index.\n\n

\n", "events": [ { "textRaw": "Event: 'gc'", "type": "event", "name": "gc", "desc": "

function (before, after) { }\n\n

\n

Emitted each time a GC run is completed.\n\n

\n

before and after are objects with the following properties:\n\n

\n
{\n  type: 'mark-sweep-compact',\n  flags: 0,\n  timestamp: 905535650119053,\n  total_heap_size: 6295040,\n  total_heap_size_executable: 4194304,\n  total_physical_size: 6295040,\n  used_heap_size: 2855416,\n  heap_size_limit: 1535115264\n}
\n", "params": [] } ], "methods": [ { "textRaw": "getHeapStatistics()", "type": "method", "name": "getHeapStatistics", "desc": "

Returns an object with the following properties\n\n

\n
{\n  total_heap_size: 7326976,\n  total_heap_size_executable: 4194304,\n  total_physical_size: 7326976,\n  used_heap_size: 3476208,\n  heap_size_limit: 1535115264\n}
\n", "signatures": [ { "params": [] } ] } ], "type": "module", "displayName": "v8" } ], "type": "module", "displayName": "Tracing" }, { "textRaw": "Async Listeners", "name": "async_listeners", "desc": "

The AsyncListener API is the JavaScript interface for the AsyncWrap\nclass which allows developers to be notified about key events in the\nlifetime of an asynchronous event. Node performs a lot of asynchronous\nevents internally, and significant use of this API may have a\nsignificant performance impact on your application.\n\n\n

\n", "methods": [ { "textRaw": "tracing.createAsyncListener(callbacksObj[, userData])", "type": "method", "name": "createAsyncListener", "signatures": [ { "params": [ { "textRaw": "`callbacksObj` {Object} Contains optional callbacks that will fire at specific times in the life cycle of the asynchronous event. ", "name": "callbacksObj", "type": "Object", "desc": "Contains optional callbacks that will fire at specific times in the life cycle of the asynchronous event." }, { "textRaw": "`userData` {Value} a value that will be passed to all callbacks. ", "name": "userData", "type": "Value", "desc": "a value that will be passed to all callbacks." } ] }, { "params": [ { "name": "callbacksObj[" }, { "name": "userData" } ] } ], "desc": "

Returns a constructed AsyncListener object.\n\n

\n

To begin capturing asynchronous events pass either the callbacksObj or\npass an existing AsyncListener instance to [tracing.addAsyncListener()][].\nThe same AsyncListener instance can only be added once to the active\nqueue, and subsequent attempts to add the instance will be ignored.\n\n

\n

To stop capturing pass the AsyncListener instance to\n[tracing.removeAsyncListener()][]. This does not mean the\nAsyncListener previously added will stop triggering callbacks. Once\nattached to an asynchronous event it will persist with the lifetime of the\nasynchronous call stack.\n\n

\n

Explanation of function parameters:\n\n\n

\n

callbacksObj: An Object which may contain several optional fields:\n\n

\n\n

userData: A Value (i.e. anything) that will be, by default,\nattached to all new event instances. This will be overwritten if a Value\nis returned by create().\n\n

\n

Here is an example of overwriting the userData:\n\n

\n
tracing.createAsyncListener({\n  create: function listener(value) {\n    // value === true\n    return false;\n}, {\n  before: function before(context, value) {\n    // value === false\n  }\n}, true);
\n

Note: The [EventEmitter][], while used to emit status of an asynchronous\nevent, is not itself asynchronous. So create() will not fire when\nan event is added, and before()/after() will not fire when emitted\ncallbacks are called.\n\n\n

\n" }, { "textRaw": "tracing.addAsyncListener(callbacksObj[, userData])", "type": "method", "name": "addAsyncListener", "desc": "

Returns a constructed AsyncListener object and immediately adds it to\nthe listening queue to begin capturing asynchronous events.\n\n

\n

Function parameters can either be the same as\n[tracing.createAsyncListener()][], or a constructed AsyncListener\nobject.\n\n

\n

Example usage for capturing errors:\n\n

\n
var fs = require('fs');\n\nvar cntr = 0;\nvar key = tracing.addAsyncListener({\n  create: function onCreate() {\n    return { uid: cntr++ };\n  },\n  before: function onBefore(context, storage) {\n    // Write directly to stdout or we'll enter a recursive loop\n    fs.writeSync(1, 'uid: ' + storage.uid + ' is about to run\\n');\n  },\n  after: function onAfter(context, storage) {\n    fs.writeSync(1, 'uid: ' + storage.uid + ' ran\\n');\n  },\n  error: function onError(storage, err) {\n    // Handle known errors\n    if (err.message === 'everything is fine') {\n      // Writing to stderr this time.\n      fs.writeSync(2, 'handled error just threw:\\n');\n      fs.writeSync(2, err.stack + '\\n');\n      return true;\n    }\n  }\n});\n\nprocess.nextTick(function() {\n  throw new Error('everything is fine');\n});\n\n// Output:\n// uid: 0 is about to run\n// handled error just threw:\n// Error: really, it's ok\n//     at /tmp/test2.js:27:9\n//     at process._tickCallback (node.js:583:11)\n//     at Function.Module.runMain (module.js:492:11)\n//     at startup (node.js:123:16)\n//     at node.js:1012:3
\n", "signatures": [ { "params": [ { "name": "asyncListener" } ] }, { "params": [ { "name": "callbacksObj[" }, { "name": "userData" } ] } ] }, { "textRaw": "tracing.addAsyncListener(asyncListener)", "type": "method", "name": "addAsyncListener", "desc": "

Returns a constructed AsyncListener object and immediately adds it to\nthe listening queue to begin capturing asynchronous events.\n\n

\n

Function parameters can either be the same as\n[tracing.createAsyncListener()][], or a constructed AsyncListener\nobject.\n\n

\n

Example usage for capturing errors:\n\n

\n
var fs = require('fs');\n\nvar cntr = 0;\nvar key = tracing.addAsyncListener({\n  create: function onCreate() {\n    return { uid: cntr++ };\n  },\n  before: function onBefore(context, storage) {\n    // Write directly to stdout or we'll enter a recursive loop\n    fs.writeSync(1, 'uid: ' + storage.uid + ' is about to run\\n');\n  },\n  after: function onAfter(context, storage) {\n    fs.writeSync(1, 'uid: ' + storage.uid + ' ran\\n');\n  },\n  error: function onError(storage, err) {\n    // Handle known errors\n    if (err.message === 'everything is fine') {\n      // Writing to stderr this time.\n      fs.writeSync(2, 'handled error just threw:\\n');\n      fs.writeSync(2, err.stack + '\\n');\n      return true;\n    }\n  }\n});\n\nprocess.nextTick(function() {\n  throw new Error('everything is fine');\n});\n\n// Output:\n// uid: 0 is about to run\n// handled error just threw:\n// Error: really, it's ok\n//     at /tmp/test2.js:27:9\n//     at process._tickCallback (node.js:583:11)\n//     at Function.Module.runMain (module.js:492:11)\n//     at startup (node.js:123:16)\n//     at node.js:1012:3
\n", "signatures": [ { "params": [ { "name": "asyncListener" } ] } ] }, { "textRaw": "tracing.removeAsyncListener(asyncListener)", "type": "method", "name": "removeAsyncListener", "desc": "

Removes the AsyncListener from the listening queue.\n\n

\n

Removing the AsyncListener from the active queue does not mean the\nasyncListener callbacks will cease to fire on the events they've been\nregistered. Subsequently, any asynchronous events fired during the\nexecution of a callback will also have the same asyncListener callbacks\nattached for future execution. For example:\n\n

\n
var fs = require('fs');\n\nvar key = tracing.createAsyncListener({\n  create: function asyncListener() {\n    // Write directly to stdout or we'll enter a recursive loop\n    fs.writeSync(1, 'You summoned me?\\n');\n  }\n});\n\n// We want to begin capturing async events some time in the future.\nsetTimeout(function() {\n  tracing.addAsyncListener(key);\n\n  // Perform a few additional async events.\n  setTimeout(function() {\n    setImmediate(function() {\n      process.nextTick(function() { });\n    });\n  });\n\n  // Removing the listener doesn't mean to stop capturing events that\n  // have already been added.\n  tracing.removeAsyncListener(key);\n}, 100);\n\n// Output:\n// You summoned me?\n// You summoned me?\n// You summoned me?\n// You summoned me?
\n

The fact that we logged 4 asynchronous events is an implementation detail\nof Node's [Timers][].\n\n

\n

To stop capturing from a specific asynchronous event stack\ntracing.removeAsyncListener() must be called from within the call\nstack itself. For example:\n\n

\n
var fs = require('fs');\n\nvar key = tracing.createAsyncListener({\n  create: function asyncListener() {\n    // Write directly to stdout or we'll enter a recursive loop\n    fs.writeSync(1, 'You summoned me?\\n');\n  }\n});\n\n// We want to begin capturing async events some time in the future.\nsetTimeout(function() {\n  tracing.addAsyncListener(key);\n\n  // Perform a few additional async events.\n  setImmediate(function() {\n    // Stop capturing from this call stack.\n    tracing.removeAsyncListener(key);\n\n    process.nextTick(function() { });\n  });\n}, 100);\n\n// Output:\n// You summoned me?
\n

The user must be explicit and always pass the AsyncListener they wish\nto remove. It is not possible to simply remove all listeners at once.\n\n\n

\n", "signatures": [ { "params": [ { "name": "asyncListener" } ] } ] } ], "type": "module", "displayName": "Async Listeners" } ] }