Tracium

Common errors

• TypeError: Tracium is not a constructor

  cause Attempting to instantiate `Tracium` using the `new` keyword, as if it were a class.
  fix Tracium exports a plain object directly, not a class. Its functions, like `computeMainThreadTasks`, should be called directly on the imported object: `Tracium.computeMainThreadTasks(...)`.

• TypeError: Cannot read properties of undefined (reading 'computeMainThreadTasks') OR Tracium.computeMainThreadTasks is not a function

  cause The `Tracium` module was not imported or required correctly, resulting in `Tracium` being `undefined` or an empty object. This commonly happens when attempting named ESM imports for a CommonJS-only package.
  fix Ensure you are using the correct CommonJS `require` syntax: `const Tracium = require('tracium');`. If using ESM, you may need to rely on Node.js's CJS-ESM interop and access the default export: `import Tracium from 'tracium';` (then `Tracium.computeMainThreadTasks`).

• Error: Invalid traceEvents array in trace JSON

  cause The input `traceJson` object provided to `computeMainThreadTasks` is missing the crucial `traceEvents` array, or this array is malformed or empty, which is required for a valid Chromium trace.
  fix Verify that your input `traceJson` strictly conforms to the Chromium trace format, specifically that it contains a top-level `traceEvents` array populated with valid trace event objects.

Warnings

• gotcha Tracium is specifically designed to parse traces generated by Chrome 66 and newer. Traces from older Chrome versions or other Chromium-based browsers might not be parsed correctly, leading to incomplete or erroneous results.
  Fix: Ensure that your Chromium performance traces are generated using Chrome browser version 66 or higher for accurate and reliable parsing.
• gotcha The `flatten` option in `tracium.computeMainThreadTasks()` defaults to `false`. This means that by default, only top-level tasks are returned, and any child tasks are nested within their parent's `children` array. If you need a flat list of all tasks, including sub-tasks, you must explicitly set `flatten: true`.
  Fix: To obtain a flattened array containing all tasks (top-level and nested), pass `{ flatten: true }` as the second argument to `computeMainThreadTasks`.
• breaking As a pre-1.0.0 package (current version 0.2.1), Tracium does not strictly adhere to Semantic Versioning. Minor versions might introduce breaking changes without a major version increment. It is crucial to review the changelog or release notes (if available) when upgrading minor versions.
  Fix: It is recommended to pin the exact version of `tracium` in your `package.json` (e.g., `"tracium": "0.2.1"`) and perform thorough testing when considering an upgrade to a new minor release.

Install

• npm install tracium npm
• yarn add tracium yarn
• pnpm add tracium pnpm

Imports

• Tracium
  wrong:

  import Tracium from 'tracium';
  // OR
  import { Tracium } from 'tracium';

  correct:

  const Tracium = require('tracium');

  Tracium primarily exposes its API via CommonJS exports. Attempting to use ESM import syntax directly without proper Node.js CJS-ESM interop configuration or transpilation can lead to undefined module exports.
• computeMainThreadTasks
  wrong:

  import { computeMainThreadTasks } from 'tracium';

  correct:

  const Tracium = require('tracium');
  const tasks = Tracium.computeMainThreadTasks(traceJSON);

  The `computeMainThreadTasks` function is a method on the `Tracium` object, which is the default CommonJS export. It is not a named export and must be accessed via the imported `Tracium` object.

Quickstart

Demonstrates how to load a Chromium trace (using a mock JSON for direct runnability) and parse its main thread tasks, showing task type, duration, and self-time for performance analysis.

const fs = require('fs');
const Tracium = require('tracium');

// In a real application, you'd load a trace file like this:
// const traceJSON = JSON.parse(fs.readFileSync('./mytrace.json', 'utf8'));

// For demonstration, we'll create a minimal mock trace structure.
// A real Chromium trace file would be significantly larger and more complex.
const mockTraceJSON = {
  'traceEvents': [
    { 'ph': 'M', 'pid': 1, 'tid': 1, 'name': 'process_name', 'args': { 'name': 'Browser' } },
    { 'ph': 'M', 'pid': 1, 'tid': 2, 'name': 'thread_name', 'args': { 'name': 'CrRendererMain' } },
    { 'ph': 'X', 'cat': 'devtools.timeline', 'name': 'ParseHTML', 'pid': 1, 'tid': 2, 'ts': 1000, 'dur': 500, 'args': {} },
    { 'ph': 'X', 'cat': 'devtools.timeline', 'name': 'EvaluateScript', 'pid': 1, 'tid': 2, 'ts': 1600, 'dur': 300, 'args': {} },
    { 'ph': 'X', 'cat': 'devtools.timeline', 'name': 'InvalidEvent', 'pid': 1, 'tid': 2, 'ts': 1900, 'dur': 100, 'args': {} }
  ],
  'metadata': { 'clockDomain': 'timeSinceEpoch', 'numProcs': 1 }
};

const tasks = Tracium.computeMainThreadTasks(mockTraceJSON, {
  // Set flatten to true to get all tasks, including child tasks, in a single array.
  flatten: true,
});

console.log('Computed Main Thread Tasks:');
tasks.forEach(task => {
  console.log(`- Kind: ${task.kind}, Duration: ${task.duration.toFixed(3)}ms, SelfTime: ${task.selfTime.toFixed(3)}ms`);
});
/*
Example output for the mock trace:
- Kind: parseHTML, Duration: 0.500ms, SelfTime: 0.500ms
- Kind: scriptEvaluation, Duration: 0.300ms, SelfTime: 0.300ms
- Kind: other, Duration: 0.100ms, SelfTime: 0.100ms
*/