Permalink
Browse files

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: #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>
  • Loading branch information...
jasnell committed Apr 4, 2018
1 parent 54a2e93 commit da5d818a54ab28df632e29204896a74c855b3430
@@ -46,7 +46,7 @@
* [String Decoder](string_decoder.html)
* [Timers](timers.html)
* [TLS/SSL](tls.html)
* [Tracing](tracing.html)
* [Trace Events](tracing.html)
* [TTY](tty.html)
* [UDP/Datagram](dgram.html)
* [URL](url.html)
@@ -1550,6 +1550,18 @@ socket, which is only valid from a client.
An attempt was made to renegotiate TLS on a socket instance with TLS disabled.
<a id="ERR_TRACE_EVENTS_CATEGORY_REQUIRED"></a>
### ERR_TRACE_EVENTS_CATEGORY_REQUIRED
The `trace_events.createTracing()` method requires at least one trace event
category.
<a id="ERR_TRACE_EVENTS_UNAVAILABLE"></a>
### ERR_TRACE_EVENTS_UNAVAILABLE
The `trace_events` module could not be loaded because Node.js was compiled with
the `--without-v8-platform` flag.
<a id="ERR_TRANSFORM_ALREADY_TRANSFORMING"></a>
### ERR_TRANSFORM_ALREADY_TRANSFORMING
@@ -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,12 +64,132 @@ 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
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
@@ -984,6 +984,9 @@ E('ERR_TLS_REQUIRED_SERVER_NAME',
E('ERR_TLS_SESSION_ATTACK', 'TLS session renegotiation attack detected', Error);
E('ERR_TLS_SNI_FROM_SERVER',
'Cannot issue SNI from a TLS server-side socket', Error);
E('ERR_TRACE_EVENTS_CATEGORY_REQUIRED',
'At least one category is required', TypeError);
E('ERR_TRACE_EVENTS_UNAVAILABLE', 'Trace events are unavailable', Error);
E('ERR_TRANSFORM_ALREADY_TRANSFORMING',
'Calling transform done when still transforming', Error);
@@ -101,7 +101,8 @@ const builtinLibs = [
'assert', 'async_hooks', 'buffer', 'child_process', 'cluster', 'crypto',
'dgram', 'dns', 'domain', 'events', 'fs', 'http', 'http2', 'https', 'net',
'os', 'path', 'perf_hooks', 'punycode', 'querystring', 'readline', 'repl',
'stream', 'string_decoder', 'tls', 'tty', 'url', 'util', 'v8', 'vm', 'zlib'
'stream', 'string_decoder', 'tls', 'trace_events', 'tty', 'url', 'util',
'v8', 'vm', 'zlib'
];
if (typeof process.binding('inspector').open === 'function') {
@@ -0,0 +1,89 @@
'use strict';
const { hasTracing } = process.binding('config');
const kHandle = Symbol('handle');
const kEnabled = Symbol('enabled');
const kCategories = Symbol('categories');
const kMaxTracingCount = 10;
const {
ERR_TRACE_EVENTS_CATEGORY_REQUIRED,
ERR_TRACE_EVENTS_UNAVAILABLE,
ERR_INVALID_ARG_TYPE
} = require('internal/errors').codes;
if (!hasTracing)
throw new ERR_TRACE_EVENTS_UNAVAILABLE();
const { CategorySet, getEnabledCategories } = process.binding('trace_events');
const { customInspectSymbol } = require('internal/util');
const { format } = require('util');
const enabledTracingObjects = new Set();
class Tracing {
constructor(categories) {
this[kHandle] = new CategorySet(categories);
this[kCategories] = categories;
this[kEnabled] = false;
}
enable() {
if (!this[kEnabled]) {
this[kEnabled] = true;
this[kHandle].enable();
enabledTracingObjects.add(this);
if (enabledTracingObjects.size > kMaxTracingCount) {
process.emitWarning(
'Possible trace_events memory leak detected. There are more than ' +
`${kMaxTracingCount} enabled Tracing objects.`
);
}
}
}
disable() {
if (this[kEnabled]) {
this[kEnabled] = false;
this[kHandle].disable();
enabledTracingObjects.delete(this);
}
}
get enabled() {
return this[kEnabled];
}
get categories() {
return this[kCategories].join(',');
}
[customInspectSymbol](depth, opts) {
const obj = {
enabled: this.enabled,
categories: this.categories
};
return `Tracing ${format(obj)}`;
}
}
function createTracing(options) {
if (typeof options !== 'object' || options == null)
throw new ERR_INVALID_ARG_TYPE('options', 'object', options);
if (!Array.isArray(options.categories)) {
throw new ERR_INVALID_ARG_TYPE('options.categories', 'string[]',
options.categories);
}
if (options.categories.length <= 0)
throw new ERR_TRACE_EVENTS_CATEGORY_REQUIRED();
return new Tracing(options.categories);
}
module.exports = {
createTracing,
getEnabledCategories
};
@@ -73,6 +73,7 @@
'lib/tls.js',
'lib/_tls_common.js',
'lib/_tls_wrap.js',
'lib/trace_events.js',
'lib/tty.js',
'lib/url.js',
'lib/util.js',
@@ -32,6 +32,7 @@
#include "v8.h"
#include "node_perf_common.h"
#include "node_context_data.h"
#include "tracing/agent.h"
#include <stddef.h>
#include <stdint.h>
@@ -325,6 +326,10 @@ inline v8::Isolate* Environment::isolate() const {
return isolate_;
}
inline tracing::Agent* Environment::tracing_agent() const {
return tracing_agent_;
}
inline Environment* Environment::from_immediate_check_handle(
uv_check_t* handle) {
return ContainerOf(&Environment::immediate_check_handle_, handle);
@@ -3,6 +3,7 @@
#include "node_buffer.h"
#include "node_platform.h"
#include "node_file.h"
#include "tracing/agent.h"
#include <stdio.h>
#include <algorithm>
@@ -87,9 +88,11 @@ void InitThreadLocalOnce() {
}
Environment::Environment(IsolateData* isolate_data,
Local<Context> context)
Local<Context> context,
tracing::Agent* tracing_agent)
: isolate_(context->GetIsolate()),
isolate_data_(isolate_data),
tracing_agent_(tracing_agent),
immediate_info_(context->GetIsolate()),
tick_info_(context->GetIsolate()),
timer_base_(uv_now(isolate_data->event_loop())),
Oops, something went wrong.

0 comments on commit da5d818

Please sign in to comment.