OpenProfiling NodeJS - Inspector-based Trace Events Inspector

This one isn't really a profier, more like a collector. As defined in the official documentation:

Trace Event provides a mechanism to centralize tracing information generated by V8, Node.js core, and userspace code.

It allows you to collect specific events emited by the Node or V8, such as detailed GC events or function deoptimization. V8 has some documentation about it that we advise to read.

Advantages

• Low performance impact since it's just collecting simple events.
• The fact that is use the core inspector module means that it's available out of the box without installing any dependency.

Drawbacks

• Events doesn't have a lot of details, specially ones about deoptimization. You will just know that they are happening.

How to use

In the following example, you will need to send the SIGUSR2 signal to the process to start the profiling and again when do you want to end it:

import { ProfilingAgent } from '@openprofiling/nodejs'
import { FileExporter } from '@openprofiling/exporter-file'
import { TraceEventsProfiler } from '@openprofiling/inspector-trace-events'
import { SignalTrigger } from '@openprofiling/trigger-signal'

const profilingAgent = new ProfilingAgent()
profilingAgent.register(new SignalTrigger({ signal: 'SIGUSR2' }), new TraceEventsProfiler({
  categories: [ 'v8.gc', 'node.bootstrap', 'v8.jit' ] // those are by default
}))
profilingAgent.start({ exporter: new FileExporter() })

You can choose which categories of events you want to profile, here the list:

• node.fs.sync: event emited when doing sync calls to filesystem
• v8.gc: events about the v8's gc
• v8.runtime: executing function
• node.bootstrap: event that are sent by node itself when starting
• v8.jit: deoptimization events
• v8.compile: parsing scripts

Those are high levels categories and do not represent low levels one (ex: disabled-by-default-v8.runtime_stats) that are used inside V8, you can also add low levels one

If you are using Node 8 and multiple profilers (ex: using both heap and cpu profiler), you will need to share a inspector session like this:

import { ProfilingAgent } from '@openprofiling/nodejs'
import { FileExporter } from '@openprofiling/exporter-file'
import { TraceEventsProfiler } from '@openprofiling/inspector-trace-events'
import { InspectorHeapProfiler } from '@openprofiling/inspector-heap-profiler'
import { SignalTrigger } from '@openprofiling/trigger-signal'
import * as inspector from 'inspector'

const profilingAgent = new ProfilingAgent()
// creation a session
const session = new inspector.Session()
// give it as parameters to the constructor
profilingAgent.register(new SignalTrigger({ signal: 'SIGUSR1' }), new TraceEventsProfiler({ session }))
profilingAgent.register(new SignalTrigger({ signal: 'SIGUSR2' }), new InspectorCPUProfiler({ session }))
profilingAgent.start({ exporter: new FileExporter() })

Vizualisation

After retrieving the trace-events file where it has been exported, it should have a .json extension. Which is the standard extension for this type of data. You have multiple ways to read the output, here the list of (known) tools that you can use :

• chrome://tracing