diff options
author | James M Snell <jasnell@gmail.com> | 2018-04-04 04:05:33 +0300 |
---|---|---|
committer | James M Snell <jasnell@gmail.com> | 2018-04-17 18:30:20 +0300 |
commit | 5c27e44488aa1c00248297204ff3484c24ff3ae7 (patch) | |
tree | 4c061d36122bcb91028eb9d0457dfa15bc84604a /doc/api/tracing.md | |
parent | 95fafc0254f6636b7c7546ac63599c79a7182fd9 (diff) |
trace_events: adds a new trace_events api
Removes the requirement to use `--trace-events-enabled` to enable
trace events. Tracing is enabled automatically if there are any
enabled categories.
Adds a new `trace_events` module with an API for enabling/disabling
trace events at runtime without a command line flag.
```js
const trace_events = require('trace_events');
const categories = [ 'node.perf', 'node.async_hooks' ];
const tracing = trace_events.createTracing({ categories });
tracing.enable();
// do stuff
tracing.disable();
```
Multiple `Tracing` objects may exist and be enabled at any point
in time. The enabled trace event categories is the union of all
enabled `Tracing` objects and the `--trace-event-categories`
flag.
PR-URL: https://github.com/nodejs/node/pull/19803
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Ali Ijaz Sheikh <ofrobots@google.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Diffstat (limited to 'doc/api/tracing.md')
-rw-r--r-- | doc/api/tracing.md | 162 |
1 files changed, 153 insertions, 9 deletions
diff --git a/doc/api/tracing.md b/doc/api/tracing.md index b53197b8109..e07320a0163 100644 --- a/doc/api/tracing.md +++ b/doc/api/tracing.md @@ -1,16 +1,15 @@ -# Tracing +# Trace Events <!--introduced_in=v7.7.0--> +> Stability: 1 - Experimental + Trace Event provides a mechanism to centralize tracing information generated by V8, Node.js core, and userspace code. -Tracing can be enabled by passing the `--trace-events-enabled` flag when -starting a Node.js application. - -The set of categories for which traces are recorded can be specified using the -`--trace-event-categories` flag followed by a list of comma separated category -names. +Tracing can be enabled with the `--trace-event-categories` command-line flag +or by using the trace_events module. The `--trace-event-categories` flag accepts +a list of comma-separated category names. The available categories are: @@ -27,7 +26,32 @@ The available categories are: By default the `node`, `node.async_hooks`, and `v8` categories are enabled. ```txt -node --trace-events-enabled --trace-event-categories v8,node,node.async_hooks server.js +node --trace-event-categories v8,node,node.async_hooks server.js +``` + +Prior versions of Node.js required the use of the `--trace-events-enabled` +flag to enable trace events. This requirement has been removed. However, the +`--trace-events-enabled` flag *may* still be used and will enable the +`node`, `node.async_hooks`, and `v8` trace event categories by default. + +```txt +node --trace-events-enabled + +// is equivalent to + +node --trace-event-categories v8,node,node.async_hooks +``` + +Alternatively, trace events may be enabled using the `trace_events` module: + +```js +const trace_events = require('trace_events'); +const tracing = trace_events.createTracing({ categories: ['node.perf'] }); +tracing.enable(); // Enable trace event capture for the 'node.perf' category + +// do work + +tracing.disable(); // Disable trace event capture for the 'node.perf' category ``` Running Node.js with tracing enabled will produce log files that can be opened @@ -40,7 +64,7 @@ be specified with `--trace-event-file-pattern` that accepts a template string that supports `${rotation}` and `${pid}`. For example: ```txt -node --trace-events-enabled --trace-event-file-pattern '${pid}-${rotation}.log' server.js +node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js ``` Starting with Node.js 10.0.0, the tracing system uses the same time source @@ -48,4 +72,124 @@ as the one used by `process.hrtime()` however the trace-event timestamps are expressed in microseconds, unlike `process.hrtime()` which returns nanoseconds. +## The `trace_events` module +<!-- YAML +added: REPLACEME +--> + +### `Tracing` object +<!-- YAML +added: REPLACEME +--> + +The `Tracing` object is used to enable or disable tracing for sets of +categories. Instances are created using the `trace_events.createTracing()` +method. + +When created, the `Tracing` object is disabled. Calling the +`tracing.enable()` method adds the categories to the set of enabled trace event +categories. Calling `tracing.disable()` will remove the categories from the +set of enabled trace event categories. + +#### `tracing.categories` +<!-- YAML +added: REPLACEME +--> + +* {string} + +A comma-separated list of the trace event categories covered by this +`Tracing` object. + +#### `tracing.disable()` +<!-- YAML +added: REPLACEME +--> + +Disables this `Tracing` object. + +Only trace event categories *not* covered by other enabled `Tracing` objects +and *not* specified by the `--trace-event-categories` flag will be disabled. + +```js +const trace_events = require('trace_events'); +const t1 = trace_events.createTracing({ categories: ['node', 'v8'] }); +const t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] }); +t1.enable(); +t2.enable(); + +// Prints 'node,node.perf,v8' +console.log(trace_events.getEnabledCategories()); + +t2.disable(); // will only disable emission of the 'node.perf' category + +// Prints 'node,v8' +console.log(trace_events.getEnabledCategories()); +``` + +#### `tracing.enable()` +<!-- YAML +added: REPLACEME +--> + +Enables this `Tracing` object for the set of categories covered by the +`Tracing` object. + +#### `tracing.enabled` +<!-- YAML +added: REPLACEME +--> + +* {boolean} `true` only if the `Tracing` object has been enabled. + +### `trace_events.createTracing(options)` +<!-- YAML +added: REPLACEME +--> + +* `options` {Object} + * `categories` {string[]} An array of trace category names. Values included + in the array are coerced to a string when possible. An error will be + thrown if the value cannot be coerced. +* Returns: {Tracing}. + +Creates and returns a `Tracing` object for the given set of `categories`. + +```js +const trace_events = require('trace_events'); +const categories = ['node.perf', 'node.async_hooks']; +const tracing = trace_events.createTracing({ categories }); +tracing.enable(); +// do stuff +tracing.disable(); +``` + +### `trace_events.getEnabledCategories()` +<!-- YAML +added: REPLACEME +--> + +* Returns: {string} + +Returns a comma-separated list of all currently-enabled trace event +categories. The current set of enabled trace event categories is determined +by the *union* of all currently-enabled `Tracing` objects and any categories +enabled using the `--trace-event-categories` flag. + +Given the file `test.js` below, the command +`node --trace-event-categories node.perf test.js` will print +`'node.async_hooks,node.perf'` to the console. + +```js +const trace_events = require('trace_events'); +const t1 = trace_events.createTracing({ categories: ['node.async_hooks'] }); +const t2 = trace_events.createTracing({ categories: ['node.perf'] }); +const t3 = trace_events.createTracing({ categories: ['v8'] }); + +t1.enable(); +t2.enable(); + +console.log(trace_events.getEnabledCategories()); +``` + [Performance API]: perf_hooks.html |