LogoفارسیFA

Comprehensive Guide to Trace Events and TTY in Node.js

Node.js provides two powerful low‑level modules for diagnostics and terminal interaction: node:trace_events — a high‑resolution tracing system that captures internal activity from V8, Node.js core, and userland code. It is essential for profiling, performance analysis, and deep debugging. node:tty — a module that exposes TTY (terminal) interfaces, enabling advanced CLI tools, raw input handling, cursor control, color detection, and terminal resizing. This guide explains both modules in a clean, structured, and practical way.

TTYTrace Events

~3 min read • Updated Dec 30, 2025

1. Introduction


The node:trace_events module provides a centralized mechanism for collecting trace data from V8, Node.js internals, and user code. The output is compatible with Chrome’s chrome://tracing tool.


2. Enabling Trace Events


2.1 Via Command Line


node --trace-event-categories v8,node,node.async_hooks app.js

2.2 Via the Module


const { createTracing } = require('node:trace_events');
const tracing = createTracing({ categories: ['node.perf'] });
tracing.enable();
// ...
tracing.disable();

3. Available Trace Categories


Node.js exposes many categories, including:

  • node.async_hooks
  • node.fs.sync / node.fs.async
  • node.net.native
  • node.perf
  • node.http
  • node.vm.script
  • v8 (GC, compilation, execution)
  • node.module_timer

4. Trace Output Files


Default filename:

node_trace.${rotation}.log

Custom pattern:

--trace-event-file-pattern '${pid}-${rotation}.log'

5. Viewing Trace Data


Open the generated log file in:

chrome://tracing

6. Core API


6.1 createTracing()


Creates a Tracing object for specific categories.

6.2 tracing.enable()


Activates tracing for the selected categories.

6.3 tracing.disable()


Deactivates tracing unless another Tracing object or CLI flag keeps it active.

6.4 getEnabledCategories()


Returns a comma‑separated list of all active categories.

7. Limitations


  • Not available inside Worker Threads.
  • Timestamps use microseconds (unlike process.hrtime() which uses nanoseconds).

8. Example: Collecting Trace Data via Inspector


Trace data can also be collected using the node:inspector module.

1. Introduction


The node:tty module provides classes for interacting with text terminals. When Node.js detects a TTY environment:

  • process.stdin → tty.ReadStream
  • process.stdout → tty.WriteStream
  • process.stderr → tty.WriteStream

2. Detecting TTY Mode


process.stdout.isTTY  // true or false

3. tty.ReadStream


  • isRaw: Indicates whether raw mode is active.
  • setRawMode(true/false): Enables or disables raw mode.

What is Raw Mode?


In raw mode:

  • Input is delivered character‑by‑character.
  • No line buffering or echoing.
  • Ctrl+C does not emit SIGINT.

4. tty.WriteStream


  • columns / rows: Terminal size.
  • cursorTo(x, y): Move cursor to absolute position.
  • moveCursor(dx, dy): Move cursor relative to current position.
  • clearLine(): Clear current line.
  • clearScreenDown(): Clear screen from cursor downward.
  • getColorDepth(): Detect color support (2, 16, 256, 16M).
  • hasColors(): Check if terminal supports a given number of colors.

5. resize Event


process.stdout.on('resize', () => {
  console.log(process.stdout.columns, process.stdout.rows);
});

6. tty.isatty()


Returns true if a file descriptor refers to a TTY.


7. Common Use Cases


  • Building advanced CLI tools
  • Interactive terminal applications
  • Custom prompts and dashboards
  • Colorful output and cursor manipulation

Conclusion


The node:trace_events and node:tty modules provide deep visibility and powerful terminal control in Node.js. Trace Events enable high‑resolution performance analysis, while TTY offers the tools needed to build sophisticated command‑line interfaces. Together, they form an essential toolkit for advanced Node.js development.


Written & researched by Dr. Shahin Siami

Next Article