README.md

perftrace

Record PerformanceEntry objects from Node.js and the Web in the Trace Event Format, so that it can be visualized on https://ui.perfetto.dev like this!

The code for this example is available here.

The code for this example is available here.

Check out the blog !

Install

To install via NPM, run:

npm i perftrace

Alternatively, you can use it in vanilla JS, without any bundler, by using a CDN or static hosting. For example, using ES Modules, you can import the library with:

<script type="module">
  import { TraceEvents } from "https://cdn.jsdelivr.net/npm/perftrace/index.mjs";
</script>

Usage

const { TraceEvents, trackRequires } = require('perftrace');
const { writeFileSync } = require('fs');

const traceEvents = new TraceEvents();

// Writes the performance traces in the "events.json" file during process exit.
process.on("beforeExit", () => {
  const events = traceEvents.getEvents();
  traceEvents.destroy();
  writeFileSync("events.json", JSON.stringify(events));
});

// Enables tracking require() calls.
trackRequires(true, { trackSource: true });

// The assert module takes milliseconds to load, so it would be distinctly
// visible in the performance trace.
const assert = require('assert');

const { performance } = require("node:perf_hooks");

// This is tracing an async setTimeout event which is interlaced with
// repeating setInterval events.

performance.mark("Timeout mark"); // marks the beginning of the timeout trace
setTimeout(() => {
  performance.measure("Timeout", "Timeout mark"); // marks the ending of the timeout trace
}, 20);

let id = 0;
performance.mark(`Interval mark ${id}`); // marks the beginning of the first interval trace
setInterval(function () {
  performance.measure(`Interval ${id}`, `Interval mark ${id}`); // marks the ending of the current interval trace
  ++id;
  // The intervals should go up to 3 counts only.
  if (id === 3) {
    this.close();
  }
  performance.mark(`Interval mark ${id}`); // marks the beginning of the next interval trace
}, 5);

After running this script with node filename.js, open the generated events.json file on https://ui.perfetto.dev.

Check out the API documentation and the code examples for details.

License

This project is available under the MIT license. See LICENSE for the full license text.