{"id":16553,"library":"tracium","title":"Tracium","description":"Tracium is a JavaScript library designed for parsing Chromium performance traces. It was extracted from Google Lighthouse, making it a robust tool for analyzing web performance data generated by Chrome browsers (version 66 and newer). Currently at version 0.2.1, its release cadence is infrequent, suggesting a stable, feature-complete state rather than active, rapid development. A key differentiator is its ability to correctly parse modern Chrome traces, positioning it as an up-to-date alternative to older parsers like Big Rig. It provides structured main thread task data, including task kind, timing, and an event hierarchy, crucial for detailed performance analysis.","status":"maintenance","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/aslushnikov/tracium","tags":["javascript"],"install":[{"cmd":"npm install tracium","lang":"bash","label":"npm"},{"cmd":"yarn add tracium","lang":"bash","label":"yarn"},{"cmd":"pnpm add tracium","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import Tracium from 'tracium';\n// OR\nimport { Tracium } from 'tracium';","symbol":"Tracium","correct":"const Tracium = require('tracium');"},{"note":"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.","wrong":"import { computeMainThreadTasks } from 'tracium';","symbol":"computeMainThreadTasks","correct":"const Tracium = require('tracium');\nconst tasks = Tracium.computeMainThreadTasks(traceJSON);"}],"quickstart":{"code":"const fs = require('fs');\nconst Tracium = require('tracium');\n\n// In a real application, you'd load a trace file like this:\n// const traceJSON = JSON.parse(fs.readFileSync('./mytrace.json', 'utf8'));\n\n// For demonstration, we'll create a minimal mock trace structure.\n// A real Chromium trace file would be significantly larger and more complex.\nconst mockTraceJSON = {\n  'traceEvents': [\n    { 'ph': 'M', 'pid': 1, 'tid': 1, 'name': 'process_name', 'args': { 'name': 'Browser' } },\n    { 'ph': 'M', 'pid': 1, 'tid': 2, 'name': 'thread_name', 'args': { 'name': 'CrRendererMain' } },\n    { 'ph': 'X', 'cat': 'devtools.timeline', 'name': 'ParseHTML', 'pid': 1, 'tid': 2, 'ts': 1000, 'dur': 500, 'args': {} },\n    { 'ph': 'X', 'cat': 'devtools.timeline', 'name': 'EvaluateScript', 'pid': 1, 'tid': 2, 'ts': 1600, 'dur': 300, 'args': {} },\n    { 'ph': 'X', 'cat': 'devtools.timeline', 'name': 'InvalidEvent', 'pid': 1, 'tid': 2, 'ts': 1900, 'dur': 100, 'args': {} }\n  ],\n  'metadata': { 'clockDomain': 'timeSinceEpoch', 'numProcs': 1 }\n};\n\nconst tasks = Tracium.computeMainThreadTasks(mockTraceJSON, {\n  // Set flatten to true to get all tasks, including child tasks, in a single array.\n  flatten: true,\n});\n\nconsole.log('Computed Main Thread Tasks:');\ntasks.forEach(task => {\n  console.log(`- Kind: ${task.kind}, Duration: ${task.duration.toFixed(3)}ms, SelfTime: ${task.selfTime.toFixed(3)}ms`);\n});\n/*\nExample output for the mock trace:\n- Kind: parseHTML, Duration: 0.500ms, SelfTime: 0.500ms\n- Kind: scriptEvaluation, Duration: 0.300ms, SelfTime: 0.300ms\n- Kind: other, Duration: 0.100ms, SelfTime: 0.100ms\n*/","lang":"javascript","description":"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."},"warnings":[{"fix":"Ensure that your Chromium performance traces are generated using Chrome browser version 66 or higher for accurate and reliable parsing.","message":"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.","severity":"gotcha","affected_versions":"<=0.2.1"},{"fix":"To obtain a flattened array containing all tasks (top-level and nested), pass `{ flatten: true }` as the second argument to `computeMainThreadTasks`.","message":"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`.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Tracium exports a plain object directly, not a class. Its functions, like `computeMainThreadTasks`, should be called directly on the imported object: `Tracium.computeMainThreadTasks(...)`.","cause":"Attempting to instantiate `Tracium` using the `new` keyword, as if it were a class.","error":"TypeError: Tracium is not a constructor"},{"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`).","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.","error":"TypeError: Cannot read properties of undefined (reading 'computeMainThreadTasks') OR Tracium.computeMainThreadTasks is not a function"},{"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.","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.","error":"Error: Invalid traceEvents array in trace JSON"}],"ecosystem":"npm"}