Performance Instrumentation Extension

This VS Code extension automatically instruments your TypeScript/TSX functions and React hook callbacks to measure their execution time. It helps you identify performance bottlenecks in your frontend or Node.js applications.

Features

• Targeted Instrumentation: Instrument specific files or entire folders (*.ts and *.tsx).
• Comprehensive Coverage: Instruments:
  • Top-level functions (declarations, expressions, arrow functions)
  • Class methods
  • Callbacks for React hooks (useEffect, useMemo, useCallback)
• Timing Collection & In-Page UI:
  • Generates an instrumentation.ts file in your project's src directory (your_workspace/src/instrumentation.ts) if it doesn't exist.
  • This file includes a record(id: string, duration: number) function to capture timings.
  • Modified files will have import { record } from "@/instrumentation"; added. This relies on a path alias; ensure your tsconfig.json is configured (e.g., "paths": { "@/*": ["src/*"] }).
  • For browser environments, instrumentation.ts automatically injects a small control panel onto the page with buttons to "Show Perf Stats" and "Clear Perf Stats".
  • The "Show Perf Stats" button opens a modal displaying a sortable table of the collected performance data.
    • The "Distribution Summary" column includes an evolution chart. When data points are aggregated into a single bar, the bar's height represents the average value in that group, and its tooltip will show both the average and maximum execution times for the original values in that group. This helps visualize typical performance and spikes simultaneously.
• De-instrumentation: Easily remove previously added instrumentation from files or folders.
• Standardized Formatting: Applies 2-space indentation to modified code using ts-morph's built-in formatter.
• Excludes Test Files: Automatically skips files containing .test. in their name during folder operations.
• Newline Preservation: Aims to preserve the formatting, including significant newlines, of your original code during instrumentation and de-instrumentation.

How to Use

1. Open your TypeScript/TSX project in VS Code.
2. Ensure your tsconfig.json is present at the workspace root and configured for the @/instrumentation path alias if you intend to use the default import behavior. Example:

   {
     "compilerOptions": {
       "baseUrl": ".", // This must be specified if "paths" is used
       "paths": {
         "@/*": ["src/*"]
       }
     }
   }
   

3. Use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) or context menus to access the extension's commands.
4. Run your instrumented application.

Analyzing Performance Data

After running your instrumented application in a browser environment:

1. Look for the control panel at the top-center of your web page.
   • Click "Show Perf Stats" to open a modal displaying the timing data.
     • The table shows: ID, Total (ms), Count, and Distribution Summary.
     • Click on the table headers (ID, Total (ms), Count) to sort the data. Click again to toggle sort direction.
     • The "Distribution Summary" column features an evolution chart. If data points are numerous and grouped, the bar height indicates the average value of that group, while the tooltip provides both average and maximum times for the underlying data points.
   • Click "Clear Perf Stats" to clear all collected data and update the table if it's open.
2. Alternatively, use your browser's Developer Console:
   • window.showPerfUI(limit?: number, sortBy?: 'totalMs' | 'count'): Programmatically shows the performance statistics modal.
   • window.getTimingStats(): Returns an object containing detailed statistics for each instrumented function/callback:

     interface TimingStats {
       totalMs: number;          // Total milliseconds spent in this function/callback
       count: number;            // How many times this function/callback was called
       distributionSummary: string; // A string summarizing the distribution of timings (e.g., "X% @ <1ms, Y% @ 1-10ms")
     }
     

   • window.clearPerf(): Clears all collected timing data.
   • window.timings: Direct access to the raw timings Record<string, number[]> (identifier -> array of durations).

For Node.js applications (or for programmatic access in any environment), you can import and use functions directly from the generated src/instrumentation.ts file:

• getTimingStats(): Returns the detailed statistics object.
• clearTimings(): Clears all collected timing data (note: named clearTimings when imported, clearPerf on window).
• timings: Direct access to the raw Record<string, number[]> (this is an exported variable).
• serializeTimingStats(): Returns a JSON string representation of the timing statistics, useful for logging or sending data elsewhere.

Extension Commands

• Performance: Instrument File: Instruments the currently active TypeScript/TSX file or the file selected from the explorer context menu.
• Performance: Instrument Folder Functions: Prompts to select a folder (or uses the context-menu folder) to instrument all eligible *.ts and *.tsx files within it.
• Performance: Deinstrument File: Removes instrumentation from the currently active TypeScript/TSX file or the file selected from the explorer context menu.
• Performance: Deinstrument Folder: Prompts to select a folder (or uses the context-menu folder) to remove instrumentation from all eligible *.ts and *.tsx files within it.

Requirements

• VS Code (latest version recommended).
• A TypeScript project with a tsconfig.json file at the workspace root.

Notes

• The extension modifies your source files. It is highly recommended to commit your changes to version control before running instrumentation or de-instrumentation commands. This allows you to easily review or revert the modifications.
• The instrumentation.ts file is created with timing collection and UI logic. You can customize this file to change how data is stored or reported (e.g., send to a backend service, alter UI).
• The extension relies on ts-morph for AST manipulation and formatting. The formatting applied is 2-space indentation.