feat: add trace event utils

packages/utils/package.json

@@ -24,7 +24,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=17.0.0"
+    "node": ">=18.2.0"
   },
   "dependencies": {
     "@code-pushup/models": "0.102.0",

packages/utils/src/lib/clock-epoch.ts

@@ -41,6 +41,18 @@ export function epochClock(init: EpochClockOptions = {}) {
     msToUs(timeOriginMs + perfMs);
 
   const fromEntryStartTimeMs = fromPerfMs;
+  const fromEntry = (
+    entry: {
+      startTime: Milliseconds;
+      entryType: string;
+      duration: Milliseconds;
+    },
+    useEndTime = false,
+  ) =>
+    fromPerfMs(
+      entry.startTime +
+        (entry.entryType === 'measure' && useEndTime ? entry.duration : 0),
+    );
   const fromDateNowMs = fromEpochMs;
 
   return {
@@ -55,6 +67,7 @@ export function epochClock(init: EpochClockOptions = {}) {
     fromEpochMs,
     fromEpochUs,
     fromPerfMs,
+    fromEntry,
     fromEntryStartTimeMs,
     fromDateNowMs,
   };

packages/utils/src/lib/clock-epoch.unit.test.ts

@@ -10,6 +10,7 @@ describe('epochClock', () => {
     expect(c.fromEpochMs).toBeFunction();
     expect(c.fromEpochUs).toBeFunction();
     expect(c.fromPerfMs).toBeFunction();
+    expect(c.fromEntry).toBeFunction();
     expect(c.fromEntryStartTimeMs).toBeFunction();
     expect(c.fromDateNowMs).toBeFunction();
   });
@@ -33,7 +34,7 @@ describe('epochClock', () => {
   it('should support performance clock by default for epochNowUs', () => {
     const c = epochClock();
     expect(c.timeOriginMs).toBe(500_000);
-    expect(c.epochNowUs()).toBe(500_000_000); // timeOrigin + performance.now() = timeOrigin + 0
+    expect(c.epochNowUs()).toBe(500_000_000);
   });
 
   it.each([
@@ -72,6 +73,41 @@ describe('epochClock', () => {
     ]).toStrictEqual([c.fromPerfMs(0), c.fromPerfMs(1000)]);
   });
 
+  it('should convert performance mark to microseconds', () => {
+    const markEntry = {
+      name: 'test-mark',
+      entryType: 'mark',
+      startTime: 1000,
+      duration: 0,
+    } as PerformanceMark;
+
+    expect(defaultClock.fromEntry(markEntry)).toBe(
+      defaultClock.fromPerfMs(1000),
+    );
+    expect(defaultClock.fromEntry(markEntry, true)).toBe(
+      defaultClock.fromPerfMs(1000),
+    );
+  });
+
+  it('should convert performance measure to microseconds', () => {
+    const measureEntry = {
+      name: 'test-measure',
+      entryType: 'measure',
+      startTime: 1000,
+      duration: 500,
+    } as PerformanceMeasure;
+
+    expect(defaultClock.fromEntry(measureEntry)).toBe(
+      defaultClock.fromPerfMs(1000),
+    );
+    expect(defaultClock.fromEntry(measureEntry, false)).toBe(
+      defaultClock.fromPerfMs(1000),
+    );
+    expect(defaultClock.fromEntry(measureEntry, true)).toBe(
+      defaultClock.fromPerfMs(1500),
+    );
+  });
+
   it('should convert Date.now() milliseconds to microseconds', () => {
     const c = epochClock();
     expect([

packages/utils/src/lib/trace-file-utils.ts

@@ -0,0 +1,268 @@
+import os from 'node:os';
+import type { PerformanceMark, PerformanceMeasure } from 'node:perf_hooks';
+import { threadId } from 'node:worker_threads';
+import { defaultClock } from './clock-epoch.js';
+import type {
+  BeginEvent,
+  CompleteEvent,
+  EndEvent,
+  InstantEvent,
+  InstantEventArgs,
+  InstantEventTracingStartedInBrowser,
+  SpanEvent,
+  SpanEventArgs,
+  TraceEvent,
+  TraceEventContainer,
+} from './trace-file.type.js';
+
+/** Global counter for generating unique span IDs within a trace */
+// eslint-disable-next-line functional/no-let
+let id2Count = 0;
+
+/**
+ * Generates a unique ID for linking begin and end span events in Chrome traces.
+ * @returns Object with local ID string for the id2 field
+ */
+export const nextId2 = () => ({ local: `0x${++id2Count}` });
+
+/**
+ * Provides default values for trace event properties.
+ * @param opt - Optional overrides for pid, tid, and timestamp
+ * @returns Object with pid, tid, and timestamp
+ */
+const defaults = (opt?: { pid?: number; tid?: number; ts?: number }) => ({
+  pid: opt?.pid ?? process.pid,
+  tid: opt?.tid ?? threadId,
+  ts: opt?.ts ?? defaultClock.epochNowUs(),
+});
+
+/**
+ * Generates a unique frame tree node ID from process and thread IDs.
+ * @param pid - Process ID
+ * @param tid - Thread ID
+ * @returns Combined numeric ID
+ */
+export const frameTreeNodeId = (pid: number, tid: number) =>
+  Number.parseInt(`${pid}0${tid}`, 10);
+
+/**
+ * Generates a frame name string from process and thread IDs.
+ * @param pid - Process ID
+ * @param tid - Thread ID
+ * @returns Formatted frame name
+ */
+export const frameName = (pid: number, tid: number) => `FRAME0P${pid}T${tid}`;
+
+/**
+ * Creates an instant trace event for marking a point in time.
+ * @param opt - Event configuration options
+ * @returns InstantEvent object
+ */
+export const getInstantEvent = (opt: {
+  name: string;
+  ts?: number;
+  pid?: number;
+  tid?: number;
+  args?: InstantEventArgs;
+}): InstantEvent => ({
+  cat: 'blink.user_timing',
+  ph: 'i',
+  name: opt.name,
+  ...defaults(opt),
+  args: opt.args ?? {},
+});
+
+/**
+ * Creates a start tracing event with frame information.
+ * This event is needed at the beginning of the traceEvents array to make tell the UI profiling has started, and it should visualize the data.
+ * @param opt - Tracing configuration options
+ * @returns StartTracingEvent object
+ */
+export const getInstantEventTracingStartedInBrowser = (opt: {
+  url: string;
+  ts?: number;
+  pid?: number;
+  tid?: number;
+}): InstantEventTracingStartedInBrowser => {
+  const { pid, tid, ts } = defaults(opt);
+  const id = frameTreeNodeId(pid, tid);
+
+  return {
+    cat: 'devtools.timeline',
+    ph: 'i',
+    name: 'TracingStartedInBrowser',
+    pid,
+    tid,
+    ts,
+    args: {
+      data: {
+        frameTreeNodeId: id,
+        frames: [
+          {
+            frame: frameName(pid, tid),
+            isInPrimaryMainFrame: true,
+            isOutermostMainFrame: true,
+            name: '',
+            processId: pid,
+            url: opt.url,
+          },
+        ],
+        persistentIds: true,
+      },
+    },
+  };
+};
+
+/**
+ * Creates a complete trace event with duration.
+ * @param opt - Event configuration with name and duration
+ * @returns CompleteEvent object
+ */
+export const getCompleteEvent = (opt: {
+  name: string;
+  dur: number;
+  ts?: number;
+  pid?: number;
+  tid?: number;
+}): CompleteEvent => ({
+  cat: 'devtools.timeline',
+  ph: 'X',
+  name: opt.name,
+  dur: opt.dur,
+  ...defaults(opt),
+  args: {},
+});
+
+/** Options for creating span events */
+type SpanOpt = {
+  name: string;
+  id2: { local: string };
+  ts?: number;
+  pid?: number;
+  tid?: number;
+  args?: SpanEventArgs;
+};
+
+/**
+ * Creates a begin span event.
+ * @param ph - Phase ('b' for begin)
+ * @param opt - Span event options
+ * @returns BeginEvent object
+ */
+export function getSpanEvent(ph: 'b', opt: SpanOpt): BeginEvent;
+/**
+ * Creates an end span event.
+ * @param ph - Phase ('e' for end)
+ * @param opt - Span event options
+ * @returns EndEvent object
+ */
+export function getSpanEvent(ph: 'e', opt: SpanOpt): EndEvent;
+/**
+ * Creates a span event (begin or end).
+ * @param ph - Phase ('b' or 'e')
+ * @param opt - Span event options
+ * @returns SpanEvent object
+ */
+export function getSpanEvent(ph: 'b' | 'e', opt: SpanOpt): SpanEvent {
+  return {
+    cat: 'blink.user_timing',
+    ph,
+    name: opt.name,
+    id2: opt.id2,
+    ...defaults(opt),
+    args: opt.args?.data?.detail
+      ? { data: { detail: opt.args.data.detail } }
+      : {},
+  };
+}
+
+/**
+ * Creates a pair of begin and end span events.
+ * @param opt - Span configuration with start/end timestamps
+ * @returns Tuple of BeginEvent and EndEvent
+ */
+export const getSpan = (opt: {
+  name: string;
+  tsB: number;
+  tsE: number;
+  id2?: { local: string };
+  pid?: number;
+  tid?: number;
+  args?: SpanEventArgs;
+  tsMarkerPadding?: number;
+}): [BeginEvent, EndEvent] => {
+  // tsMarkerPadding is here to make the measure slightly smaller so the markers align perfectly.
+  // Otherwise, the marker is visible at the start of the measure below the frame
+  //       No padding   Padding
+  // spans: ========   |======|
+  // marks: |      |
+  const pad = opt.tsMarkerPadding ?? 1;
+  // b|e need to share the same id2
+  const id2 = opt.id2 ?? nextId2();
+
+  return [
+    getSpanEvent('b', {
+      ...opt,
+      id2,
+      ts: opt.tsB + pad,
+    }),
+    getSpanEvent('e', {
+      ...opt,
+      id2,
+      ts: opt.tsE - pad,
+    }),
+  ];
+};
+
+/**
+ * Converts a PerformanceMark to an instant trace event.
+ * @param entry - Performance mark entry
+ * @param opt - Optional overrides for name, pid, and tid
+ * @returns InstantEvent object
+ */
+export const markToInstantEvent = (
+  entry: PerformanceMark,
+  opt?: { name?: string; pid?: number; tid?: number },
+): InstantEvent =>
+  getInstantEvent({
+    ...opt,
+    name: opt?.name ?? entry.name,
+    ts: defaultClock.fromEntry(entry),
+    args: entry.detail ? { detail: entry.detail } : undefined,
+  });
+
+/**
+ * Converts a PerformanceMeasure to a pair of span events.
+ * @param entry - Performance measure entry
+ * @param opt - Optional overrides for name, pid, and tid
+ * @returns Tuple of BeginEvent and EndEvent
+ */
+export const measureToSpanEvents = (
+  entry: PerformanceMeasure,
+  opt?: { name?: string; pid?: number; tid?: number },
+): [BeginEvent, EndEvent] =>
+  getSpan({
+    ...opt,
+    name: opt?.name ?? entry.name,
+    tsB: defaultClock.fromEntry(entry),
+    tsE: defaultClock.fromEntry(entry, true),
+    args: entry.detail ? { data: { detail: entry.detail } } : undefined,
+  });
+
+/**
+ * Creates a complete trace file container with metadata.
+ * @param opt - Trace file configuration
+ * @returns TraceEventContainer with events and metadata
+ */
+export const getTraceFile = (opt: {
+  traceEvents: TraceEvent[];
+  startTime?: string;
+}): TraceEventContainer => ({
+  traceEvents: opt.traceEvents,
+  displayTimeUnit: 'ms',
+  metadata: {
+    source: 'Node.js UserTiming',
+    startTime: opt.startTime ?? new Date().toISOString(),
+    hardwareConcurrency: os.cpus().length,
+  },
+});