Comprehensive Guide to Trace Events and TTY in Node.js

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.