Skip to content

Trace event support for Node.js

Checklist
  • make -j8 test (UNIX), or vcbuild test nosign (Windows) passes
  • documentation is changed or added
  • commit message follows commit guidelines
Affected core subsystem(s)

src

Description of change

Background: https://github.com/nodejs/diagnostics/issues/30, https://github.com/nodejs/diagnostics/issues/53

This PR adds support for trace-event tracing to Node.js. It provides a mechanism to centralize tracing information generated by V8, Node core, and userspace code. The PR contains a few components:

  • A trace writer responsible for serializing traces and cycling the output files so that no individual file becomes to large.
  • A buffer for aggregating traces to allow for batched flushes.
  • An agent which initializes the tracing controller and ensures that trace serialization is done on a separate thread.
  • A set of macros for generating trace events.

Generating Trace Events

This PR introduces macros for recording trace events. Synchronous operations can be traced by wrapping them with the appropriate macros:

TRACE_EVENT_BEGIN0("MY_CATEGORY", "SomethingCostly")
doSomethingCostly()
TRACE_EVENT_END0("MY_CATEGORY", "SomethingCostly")

Asynchronous operations can be traced using:

void StartAsyncOperation(int operation_id, ...) {
  TRACE_EVENT_NESTABLE_ASYNC_BEGIN0("category", "operation", operation_id);
  ...
}
void EndAsyncOperation(int operation_id, ...) {
  TRACE_EVENT_NESTABLE_ASYNC_END0("category", "operation", operation_id);
  ...
}

An example of async traces can be seen below. The example was generated by integrating the above macros into Async-Wrap.

Additional examples as well as a complete list of trace macros can be found in src/tracing/trace_event.h. This PR does not introduce any JS interface for generating events or tracing of Node core with the hope that the community can determine how the instrumentation of core should be approached and how this functionality can be exposed to end users.

Viewing Trace Events

The current trace serialization outputs traces in a format that can be visualized by navigating to chrome://tracing in Chrome and loading a trace output file.

w85xe3osv1u

We can zoom in on this visualization to view VM events alongside the opening and closing of TCP connections:

dsksrjkirjkirjkk69xc63ny39g3a3zhbdtmw4aaaaaelftksuqmcc

Usage

Tracing can be enabled by running:

node --trace-events-enabled server.js

By default, this will record all events in the "v8" and "node" categories. To trace other categories or ignore either of these categories, use the --trace-event-categories flag:

node --trace-events-enabled --trace-event-categories v8,custom-category server.js

This PR is the result of a lot of hard work by @misterpoe, @kjin, @lpy, @fmeawad, and @ofrobots.

Thanks for the review!

/cc @nodejs/diagnostics

Merge request reports

Loading