async-flow-trace

Trace and visualize asynchronous execution flow in Node.js applications using async_hooks.

Understand how async operations are connected, identify performance bottlenecks, and debug complex promise chains, without modifying your code.

📥 Installation

npm install -D async-flow-trace

Or use directly with npx:

npx async-flow-trace -- node app.js

🧪 Usage

Run any Node.js app with tracing

npx async-flow-trace -- node app.js

With npm scripts

npx async-flow-trace -- npm run start:dev

Configure slow threshold (ms)

npx async-flow-trace --min=100 -- node app.js

🌳 Example Output

🌳 Async Tree:

Timeout (114ms) ⚠
  PROMISE (3ms)
    PROMISE (2ms)

✨ Features

• 🔍 Tracks async operations using async_hooks
• 🌳 Visualizes async execution as a tree
• ⏱ Measures execution time of async tasks
• ⚠ Highlights slow operations
• ⚡ Works without modifying application code

⚙️ How It Works

The tool hooks into Node.js async lifecycle events and builds a parent-child graph of async operations. This graph is then rendered as a readable tree with timing information.

⚠️ Notes

• Intended for development/debugging, not production use
• May add slight overhead due to tracing

📌 Status

Early version (v0.1.0). Feedback and contributions are welcome.

📄 License

MIT