AsyncScope

AsyncScope is a Node.js library and CLI tool that tracks and visualizes promises, async/await, timers, and event emitters. It generates flow graphs showing parent-child relationships and logs the lifecycle of async resources.

Use it as a CLI wrapper or integrate directly into your code for detailed async operation insights.

Installation

npm install

Usage

Option 1: CLI Commands

After linking:

npm link

Start the real-time viewer:

asyncscope viewer

Then open http://localhost:8080 to see live graph updates.

Track a specific file:

asyncscope track --target <path-to-js-file> [options]

Run a Node.js app with tracking:

asyncscope node <path-to-js-file> [options]

Options:

• -t, --target <file>: Path to the Node.js file to instrument (required for track)
• -o, --output <file>: Output file for the graph in Mermaid format (default: graph.mmd)
• -l, --log <file>: Output file for logs (default: async.log)
• -i, --image <file>: Output image file for graph (PNG) (default: graph.png)
• -n, --instance <name>: Instance name for multi-app monitoring (default: default)
• -p, --port <number>: Port for viewer server (default: 8080)
• -V, --version: Show version
• -h, --help: Show help

Option 2: Library Integration

Add to your Node.js app:

const AsyncScope = require('asyncscope');

AsyncScope.start({
  logFile: 'my-app.log',
  graphFile: 'my-app.dot',
  imageFile: 'my-app.png'
});

// Your app code here

// On shutdown
AsyncScope.stop();

For Express apps, handle SIGINT:

process.on('SIGINT', () => {
  AsyncScope.stop();
  process.exit(0);
});

Features

• Comprehensive Tracking: Monitors promises, async/await, timers, event emitters, and more
• Multi-Instance Monitoring: Track multiple applications/servers simultaneously with instance names
• Real-time Updates: Graph updates every 5 seconds during active tracking
• Detailed Logging: Records creation, execution, and destruction with timestamps
• Smart Labeling: Shows originating function names and API endpoints in graph nodes
• Execution Flow Visualization: Displays parent-child relationships and execution sequences
• Interactive Real-time Viewer: Web-based dashboard with live Mermaid graph rendering
• Zoom & Navigation: Full zoom controls, pan, fit-to-screen, and scroll for large graphs
• Export Functionality: Download Mermaid (.mmd) files directly from the viewer
• Responsive Design: Adapts to different screen sizes with proper scrolling
• Accessibility: Screen reader friendly with proper ARIA labels and keyboard navigation
• Modular Architecture: Clean separation of concerns with organized code structure
• Flexible Integration: Library API or CLI wrapper for existing apps

Project Structure

lib/
├── index.js                    # Main AsyncTracker API & exports
├── core/
│   ├── tracker.js             # AsyncTracker class
│   ├── graph-store.js         # Node/edge management
│   └── logger.js              # Event logging
├── hooks/
│   ├── index.js               # Hook setup coordinator
│   ├── async-hooks.js         # Async resource hooks
│   └── event-hooks.js         # EventEmitter hooks
└── visualization/
    ├── index.js               # Visualization coordinator
    └── mermaid-generator.js   # Mermaid graph generation

bin/
├── index.js                   # CLI entry point
└── commands/
    ├── track.js               # Track command
    ├── node.js                # Node wrapper command
    └── viewer.js              # Viewer server command

server/
├── index.js                   # Server entry point
├── routes/
│   └── api.js                 # API endpoints
└── views/
    └── index.html             # Interactive viewer

examples/
├── demo.js                    # Demo script
└── express-app.js             # Express app example

Visualization

To visualize the graph:

dot -Tpng graph.dot -o graph.png
# or
dot -Tsvg graph.dot -o graph.svg

Examples

Real-time Interactive Monitoring

Single Instance

1. Start the interactive viewer:

   asyncscope viewer

   Open http://localhost:8080 for a live, interactive graph

2. Run your app with tracking:

   asyncscope node your-app.js

3. Make requests to your app to see real-time graph updates:

   curl http://localhost:3000/api/endpoint

4. Use zoom controls to navigate large graphs:

   • Zoom In/Out: Buttons or Ctrl + Scroll
   • Fit to Screen: Automatically adjust zoom to fit the graph
   • Reset Zoom: Return to default zoom level
   • Scroll: Use mouse wheel or scroll bars for navigation

5. Use the information panel on the right to understand:

   • Node labels: Each line represents different information (type, function, ID, timestamps)
   • Graph legends: Color coding for different resource types
   • Control explanations: What each button and feature does

6. Watch the graph update automatically every 5 seconds

7. Export the graph using the "Export MMD" button in the viewer

8. Press Ctrl+C to stop tracking and generate final reports

Multi-Instance Monitoring

1. Start viewer:

   asyncscope viewer

2. Run multiple apps with different instances:

   # Terminal 1
   asyncscope node examples/express-app.js --instance api-server
   
   # Terminal 2
   asyncscope node examples/demo.js --instance demo-script

3. Switch between instances in the viewer dropdown to monitor different apps

4. Export graphs for each instance separately

Quick Demo

Track the demo script:

asyncscope track --target examples/demo.js

Library Integration

See examples/express-app.js for embedding AsyncScope directly in your code.