or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdindex.mdprogrammatic-api.md
tile.json

tessl/npm-0x

Single-command flamegraph profiling tool for Node.js applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/0x@6.0.x

To install, run

npx @tessl/cli install tessl/npm-0x@6.0.0

index.mddocs/

0x - Flamegraph Profiler

0x is a single-command flamegraph profiling tool for Node.js applications that enables developers to discover bottlenecks and hot paths in their code through interactive visualizations. It offers cross-platform compatibility with automatic stack trace collection and browser-based flamegraph visualization, supports both development and production server profiling scenarios, and includes advanced features like kernel tracing for native stack frames.

Package Information

  • Package Name: 0x
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install -g 0x

Core Imports

const zeroEks = require('0x');

For CLI usage as a global binary:

0x [flags] -- node [nodeFlags] script.js [scriptFlags]

Basic Usage

CLI Usage

Profile a Node.js application and generate interactive flamegraph:

# Basic profiling
0x my-app.js

# Open flamegraph in browser automatically
0x -o my-app.js

# Profile with load testing on first opened port
0x -P 'autocannon localhost:$PORT' my-app.js

# Use custom node executable
0x -- /path/to/node my-app.js

Programmatic Usage

const zeroEks = require('0x');

async function profileApp() {
  // Basic profiling - generates flamegraph HTML file
  const flamegraphPath = await zeroEks({
    argv: ['my-app.js'],
    open: true
  });
  
  // Data collection only - returns folder path
  const dataFolder = await zeroEks({
    argv: ['my-app.js'],
    collectOnly: true,
    outputDir: './profiling-{timestamp}'
  });
}

Architecture

0x is built around several key components:

  • Cross-platform Profiling: V8 profiling for all platforms, Linux kernel tracing for enhanced native stack visibility
  • CLI Interface: Comprehensive command-line tool with extensive flag support and argument validation
  • Programmatic API: Single main function zeroEks for scripted profiling workflows
  • Visualization Engine: Browser-based interactive flamegraph rendering with D3.js
  • Platform Abstraction: Separate modules for V8 and Linux kernel profiling backends

Capabilities

Programmatic API

Main API function for integrating flamegraph profiling into Node.js applications and tooling workflows.

/**
 * Profile a Node.js process and generate flamegraph visualization
 * @param args - Profiling configuration options
 * @returns Promise resolving to flamegraph file path or data folder path
 */
function zeroEks(args: ProfilingOptions): Promise<string>;

interface ProfilingOptions {
  /** Command line arguments for target process (required) */
  argv: string[];
  /** Output name prefix for generated files */
  name?: string;
  /** Flamegraph title */
  title?: string;
  /** Only collect profiling data, don't generate flamegraph */
  collectOnly?: boolean;
  /** Visualize existing profiling data from folder path */
  visualizeOnly?: string;
  /** Visualize existing V8 CPU profile from file path */
  visualizeCpuProfile?: string;
  /** Use Linux kernel tracing instead of V8 profiling */
  kernelTracing?: boolean;
  /** Delay before starting data collection (milliseconds) */
  collectDelay?: number;
  /** Working directory for profiling operations */
  workingDir?: string;
  /** Output directory pattern with template variables */
  outputDir?: string;
  /** Output HTML file pattern with template variables */
  outputHtml?: string;
  /** Automatically open flamegraph in browser */
  open?: boolean;
  /** Path to Node.js binary to profile */
  pathToNodeBinary?: string;
  /** Command or function to execute when port is detected */
  onPort?: string | ((port: number, callback: Function) => void);
  /** Enable frame mapping for better stack trace resolution */
  mapFrames?: boolean;
  /** Generate debug tree data file */
  treeDebug?: boolean;
  /** Write raw tick data to file */
  writeTicks?: boolean;
  /** Callback function for process exit events */
  onProcessExit?: Function;
  /** Status reporting callback function */
  status?: Function;
}

Programmatic API

Command Line Interface

Comprehensive CLI tool providing single-command profiling with extensive configuration options for development and production use cases.

# Basic command structure
0x [flags] -- node [nodeFlags] script.js [scriptFlags]

# Key flags
-o, --open              # Open flamegraph in browser
-D, --output-dir DIR    # Output directory pattern
-F, --output-html FILE  # Output HTML file pattern  
-P, --on-port CMD       # Command to run when port detected
--collect-only          # Only collect data, don't generate flamegraph
--visualize-only DIR    # Visualize existing profiling data
--kernel-tracing        # Use Linux kernel tracing
--collect-delay MS      # Delay before collection starts

Command Line Interface