webperf-monitor

A comprehensive web performance monitoring package for tracking DOM elements, JavaScript functions, and simulating load in web applications.

Features

• 🚀 Function Performance Monitoring: Track execution time and memory usage of JavaScript functions
• 🎯 DOM Element Monitoring: Attach listeners to buttons or DOM elements and monitor user interactions (via Puppeteer)
• 🔄 Load Simulation: Simulate user traffic to evaluate performance under load (via Puppeteer)
• 📊 Data Export: Export structured performance logs in JSON/CSV formats
• 📈 Visual Reports: Generate charts and visual reports for performance analysis
• 🛠️ Multiple Interfaces: Both programmatic API and CLI interface
• 📝 Advanced Logging: Use PerformanceLogger for custom/advanced logging

Installation

From npm

npm install webperf-monitor

From GitHub (latest)

npm install git+https://github.com/krishnasharma0101/webperf-monitor.git

Quick Start

Programmatic Usage

Monitor a Function

import { monitorFunction } from 'webperf-monitor';

const result = await monitorFunction(
  () => expensiveCalculation(),
  'expensive-calculation',
  {
    logToFile: true,
    logToConsole: true,
    includeMemory: true,
    outputDir: './logs',
    format: 'json',
    filename: 'expensive-calc',
    append: true
  }
);
console.log(result);

Monitor DOM Elements (via Puppeteer)

import { monitorElement } from 'webperf-monitor';

await monitorElement(
  'https://example.com',
  '#submit-button',
  {
    events: ['click', 'focus'],
    logToFile: true,
    logToConsole: true,
    timeout: 10000,
    outputDir: './logs',
    format: 'json',
    filename: 'element-events',
    append: true
  }
);

Simulate Load (via Puppeteer)

import { simulateLoad } from 'webperf-monitor';

await simulateLoad({
  target: 'https://example.com',
  concurrency: 10,
  duration: 60000, // ms
  interval: 1000, // ms between requests
  actions: [
    { type: 'click', selector: '#login' },
    { type: 'type', selector: '#username', value: 'user' },
    { type: 'type', selector: '#password', value: 'pass' },
    { type: 'click', selector: '#submit' }
  ],
  logToFile: true,
  logSummaryToFile: true,
  outputDir: './logs',
  filename: 'load-test',
  format: 'json',
  append: true
});

CLI Usage

# Monitor a function in a file (see sample-func.js)
node bin/cli.js function --file ./sample-func.js --function add

# Monitor a slow async function
node bin/cli.js function --file ./sample-func.js --function slow

# Monitor a function that throws
node bin/cli.js function --file ./sample-func.js --function fail

# Monitor DOM element (headless, via Puppeteer)
node bin/cli.js element --url https://example.com --selector 'h1' --events click --timeout 5000

# Simulate load
done bin/cli.js load --url https://example.com --concurrency 2 --duration 10000 --interval 2000

API Reference

monitorFunction(fn, label, options?)

Monitors the execution of a function and returns performance metrics.

Parameters:

• fn: Function to monitor
• label: Label for the function in logs
• options: Optional configuration (see below)

Returns: Promise with { result, metrics }

Options for monitorFunction

• logToFile (boolean): Log metrics to file
• logToConsole (boolean): Log metrics to console
• includeMemory (boolean): Include memory usage
• outputDir (string): Directory for logs
• format (string): 'json' or 'csv'
• filename (string): Log file name
• append (boolean): Append to log file

monitorElement(url, selector, config)

Attaches performance monitoring listeners to DOM elements (via Puppeteer).

Parameters:

• url: URL to open
• selector: CSS selector for the element
• config: Configuration object (see below)

Config for monitorElement

• events (array): Events to monitor (e.g., ['click', 'focus'])
• logToFile, logToConsole, timeout, outputDir, format, filename, append (see above)

simulateLoad(options)

Simulates user traffic to evaluate performance under load (via Puppeteer).

Parameters:

• options.target: Target URL
• options.concurrency: Number of concurrent users
• options.duration: Test duration in ms
• options.interval: Interval between requests (ms)
• options.actions: Array of user actions (click, type, wait, navigate)
• logToFile, logSummaryToFile, outputDir, filename, format, append (see above)

Advanced Usage: PerformanceLogger

You can use the PerformanceLogger class directly for custom logging:

import { PerformanceLogger } from 'webperf-monitor';
const logger = new PerformanceLogger({ outputDir: './logs', format: 'json' });
await logger.log({ executionTime: 123, label: 'custom', timestamp: Date.now(), success: true });

Configuration

The package supports various configuration options for logging, reporting, and monitoring behavior. See the API reference above for details.

Cleaning the Directory for GitHub

Before pushing to GitHub, make sure to:

• Remove or gitignore logs/: Performance logs and test outputs should not be committed.
• Remove or gitignore dist/: Build outputs should not be committed (add to .gitignore).
• Remove or gitignore node_modules/: Never commit dependencies.
• Remove test and sample files: Remove test.js, test-file-logging.js, and sample-func.js if not needed for the published package.

License

MIT