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>

1 files changed, 153 insertions, 9 deletions

diff --git a/doc/api/tracing.md b/doc/api/tracing.md
index b53197b810..e07320a016 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