@autotracer/flow

Automatic function flow tracing with dormant mode and browser console control.

See exactly what your code is doing—function calls, parameters, return values, exceptions, and nested call stacks—all logged automatically without writing a single console.log. Your functions get instrumented at build time, so you can trace complex execution flows just by opening your browser console and calling globalThis.autoTracer.flowTracer.start(). Perfect for debugging TEST/QA environments where you need tracing available on-demand without any performance impact when it's off.

Installation

You need two packages: the core library and a build plugin.

For Vite projects:

pnpm add @autotracer/flow @autotracer/logger
pnpm add -D @autotracer/plugin-vite-flow

For Next.js / Babel projects:

pnpm add @autotracer/flow @autotracer/logger
pnpm add -D @autotracer/plugin-babel-flow

Note: @autotracer/logger is a required dependency of @autotracer/flow. While it's listed as a dependency and should be automatically installed, explicitly including it ensures compatibility across different package managers.

Monorepo / Workspace Setup

When using @autotracer/flow from a local workspace (e.g., in a monorepo), add Vite aliases to resolve the packages:

// vite.config.ts
import path from "path";

export default defineConfig({
  resolve: {
    alias: {
      "@autotracer/flow/runtime": path.resolve(
        __dirname,
        "path/to/packages/auto-tracer-flow/dist/runtime.js",
      ),
      "@autotracer/flow": path.resolve(
        __dirname,
        "path/to/packages/auto-tracer-flow",
      ),
      "@autotracer/logger": path.resolve(
        __dirname,
        "path/to/packages/auto-tracer-logger",
      ),
    },
  },
  // ... rest of config
});

Important: The /runtime alias must come before the base @autotracer/flow alias for proper resolution.

What You Get

• Automatic function tracing - Entry, exit, parameters, and return values logged automatically
• Dormant mode - Zero overhead when not activated (logger completely disabled)
• Runtime browser control - Activate/deactivate tracing via window.autoTracer.flowTracer.start() / window.autoTracer.flowTracer.stop()
• Exception logging - Errors logged before they're caught or thrown
• Call stack visualization - Nested calls shown with console.group nesting
• Framework-agnostic - Works with any JavaScript/TypeScript application

Perfect for Large Teams and Unfamiliar Code

When working on large customer solutions with many developers, you often need to troubleshoot or understand code you didn't write. Flow tracing gives you the most exact and powerful way to see what's happening:

• Faster than stepping - See the complete execution flow instantly instead of stepping through hundreds of function calls
• Search and filter - Console output is searchable, making it easy to find specific function calls or parameters
• Automatic relevance - Chrome's console.group collapsing means you only see the code paths that actually executed
• Zero instrumentation - No manual logging needed, no code changes required
• Complete context - Parameters, return values, and timing all captured automatically

Example scenario: A bug appears in a multi-step checkout flow. Instead of setting 20 breakpoints and stepping through each function, activate flow tracing, reproduce the issue, and get a complete trace of every function call, parameter, and return value. Search the console for the problematic value and see exactly which function produced it.

React Integration

Combine @autotracer/flow with @autotracer/react18 for React projects to get complete insight into both execution flow and React lifecycle:

• State and props tracking - See exactly when state and props change in each component
• Render cycle visibility - Understand what happens on every render cycle
• Full execution context - Function calls interleaved with React render events
• Component hierarchy - See which components render and in what order

This combination gives you unprecedented visibility into React applications, making it easy to understand performance issues, unnecessary re-renders, and complex state interactions.

Quickstart

Note: The examples below show Vite configuration. For Next.js/Babel setup, see the Integration Guides section.

Normal Mode (Local Development)

For immediate tracing output during local development:

// vite.config.ts
import { flowTracer } from "@autotracer/plugin-vite-flow";

export default {
  plugins: [
    flowTracer({
      enabled: true,
      runtimeControlled: false, // Tracing always active
      include: {
        paths: ["**/src/**"],
        functions: ["*"],
      },
    }),
  ],
};

All instrumented functions immediately produce console output. No browser console commands needed.

Dormant Mode (TEST/QA Deployments)

For production-like environments where tracing should be off by default but available on-demand:

// vite.config.ts
import { flowTracer } from "@autotracer/plugin-vite-flow";

export default {
  plugins: [
    flowTracer({
      enabled: true,
      runtimeControlled: true, // Start dormant, activate via console
      include: {
        paths: ["**/src/**"],
        functions: ["*"],
      },
    }),
  ],
};

The runtime control is automatically imported. Open browser console to activate:

// Activate flow tracing
globalThis.autoTracer.flowTracer.start();

// Your instrumented functions now produce console output

// Deactivate flow tracing
globalThis.autoTracer.flowTracer.stop();

What You'll See

When tracing is active and you call instrumented functions:

handleAdd
  add
    params: 5 3
    returned: 8
    add (elapsed: 0.5ms)
  handleAdd (elapsed: 1.2ms)

With exceptions:

divide
  params: 10 0
  💥 Exception in divide: Error: Division by zero
    at divide (App.tsx:64:13)
    at safeDivide (App.tsx:87:12)
    ...
  divide (elapsed: 1.4ms)

API Reference

Global Runtime API

When @autotracer/flow/runtime is imported, these are available globally:

// Canonical runtime control surface
globalThis.autoTracer: {
  getOutputMode(): "devtools" | "copy-paste"
  setOutputMode(mode: "devtools" | "copy-paste"): void
  flowTracer: {
    start(): void
    stop(): void
    isEnabled(): boolean
    addFilter(match: string): void
    showFilters(): string
    clearFilters(): void
    filterMode(enabled?: boolean): boolean
  }
}

// Internal (injected-code) tracer surface.
// This is intentionally not part of the human-facing console API.
globalThis.__flowTracer: {
  enter(functionName: string): unknown
  exit(handle: unknown): void
  traceParameter(name: string, value: unknown): void
  // ... additional internal trace helpers
}

Runtime Filtering

Flow tracing supports runtime name-only filtering that is persisted in localStorage.

// Add a runtime filter (name-only, supports glob-style patterns)
globalThis.autoTracer.flowTracer.addFilter("noise*");

// Print and return a copy/paste snippet for compile-time config
globalThis.autoTracer.flowTracer.showFilters();
// -> exclude: { functions: ["noise*"] }

// Clear only runtime filters
globalThis.autoTracer.flowTracer.clearFilters();

Copy/Paste Assist (filterMode)

Enable “filterMode” to append a copy/paste-ready snippet to each traced function row.

// Enable per-row copy/paste snippets (not persisted)
globalThis.autoTracer.flowTracer.filterMode();

// Disable per-row copy/paste snippets
globalThis.autoTracer.flowTracer.filterMode(false);

Notes:

• Filters persist across reloads; filterMode does not.
• Matching is by function name only (paths are not available at runtime).

Startup Output Mode

To avoid needing runtime console calls, configure output formatting at startup.

Vite: set outputMode on @autotracer/plugin-vite-flow. This is injected into the page before any runtime imports, so grouping is correct from the first trace.

Next.js / Babel: set outputMode on @autotracer/plugin-babel-flow. The plugin injects startup configuration into modules that import @autotracer/flow/runtime.

Grouping Mode Control

Grouping mode is controlled via the canonical outputMode:

• "default" - Uses native console.group() for interactive collapsible groups (default)
• "text" - Uses UTF-8 box-drawing characters for copy-paste friendly output

// Copy/paste-friendly output
globalThis.autoTracer.setOutputMode("copy-paste");

// DevTools-friendly output
globalThis.autoTracer.setOutputMode("devtools");

Use cases:

• Default mode: Best for interactive debugging in browser DevTools
• Text mode: Best when you need to copy console output to share with teammates or file bug reports

In "copy-paste" mode, @autotracer/flow also formats complex values (objects, arrays, errors, maps, sets) as stable JSON text so the console output is reliably copyable.

Convenience API:

Use window.autoTracer.setOutputMode(...) to switch between interactive DevTools grouping and copy/paste-friendly output.

Themed Output

All flow tracing output uses themed styling with semantic categories:

• Function Entry (→) - Synchronous function entry with themed arrow
• Function Exit (←) - Synchronous function exit with duration
• Async Start (🚀) - Async function entry
• Async Complete (✅) - Async function completion
• Parameters - Function parameters in italic style
• Return Values - Return values in plain style
• Exceptions (💥) - Caught exceptions with stack traces
• Runtime Control (🔧) - Runtime control messages (start/stop tracing)

Each category can be customized with light/dark mode colors and icons via theme configuration files (see Theme File Configuration below).

Theme File Configuration

NEW: Flow tracing supports external theme files for personal customization without modifying project code.

📖 Complete Theme Files Guide - Detailed documentation with examples for colorblind-friendly palettes, high-contrast modes, and accessibility customization.

Quick Start

Create theme files in your project root (typically gitignored):

// flow-theme-light.json
{
  "functionEnter": {
    "light": {
      "icon": "▶",
      "text": "#2563eb"
    }
  },
  "exception": {
    "light": {
      "icon": "⚠️",
      "text": "#dc2626",
      "background": "#fff5f5"
    }
  }
}

// flow-theme-dark.json
{
  "functionEnter": {
    "dark": {
      "icon": "▶",
      "text": "#60a5fa"
    }
  },
  "exception": {
    "dark": {
      "icon": "⚠️",
      "text": "#f87171",
      "background": "#3f1f1f"
    }
  }
}

The flow tracer automatically detects these files and applies them based on browser color scheme preference.

Theme Priority Order

Themes are merged in this order (later overrides earlier):

1. Built-in defaults - Shipped with @autotracer/flow
2. Programmatic config - Set by project maintainer in code
3. External theme files - flow-theme-light.json and flow-theme-dark.json (highest priority)

Rationale: External theme files have the highest priority to enable per-developer customization:

• Project maintainer sets sensible defaults via programmatic config
• Individual developers drop in their own theme files (gitignored) to override colors/icons
• Personal preferences without code changes or merge conflicts
• Accessibility - Developers can use colorblind-friendly palettes, high-contrast modes, or preferred icons

Light and Dark Mode Support

Flow tracing automatically detects browser color scheme (prefers-color-scheme) and applies the appropriate theme mode:

• Light mode - Uses light property from theme configuration
• Dark mode - Uses dark property from theme configuration

Each semantic category can have different icons and colors for light vs dark mode:

{
  "functionEnter": {
    "light": {
      "icon": "→",
      "text": "#1e40af"
    },
    "dark": {
      "icon": "→",
      "text": "#93c5fd"
    }
  }
}

The tracer automatically switches themes when you toggle your browser's color scheme preference in DevTools.

Personal Customization Pattern

Add theme files to .gitignore for personal customization (recommended):

# .gitignore
flow-theme-light.json
flow-theme-dark.json

This allows each developer to customize their local console output appearance without affecting teammates:

• Colorblind-friendly palettes - Use distinct colors that work for different types of color vision
• High-contrast modes - Increase readability in different lighting conditions
• Personal icon preferences - Choose emoji vs text symbols
• Accessibility needs - Customize for screen readers or visual impairments

Example: Developer with deuteranopia (red-green colorblindness) can use blue/orange palette instead of default red/green, while teammates keep default colors.

Alternatively, commit theme files for team-wide standards:

If your team wants consistent console output across all developers (e.g., for screenshots in bug reports or documentation), you can commit theme files to version control. However, this removes the ability for individual developers to customize for accessibility needs.

# Commit theme files (optional - reduces personal customization)
git add flow-theme-*.json
git commit -m "Add team flow tracing theme"

Available Theme Categories

Each category supports light and dark mode configuration with icon, text, background, bold, and italic properties:

• functionEnter - Synchronous function entry
• functionExit - Synchronous function exit with duration
• asyncStart - Async function entry
• asyncComplete - Async function completion with duration
• parameter - Function parameter logging
• returnValue - Return value logging
• exception - Exception/error logging
• runtimeControl - Runtime control messages (start/stop)

Complete Theme File Example

{
  "functionEnter": {
    "light": { "icon": "▶", "text": "#2563eb" },
    "dark": { "icon": "▶", "text": "#60a5fa" }
  },
  "functionExit": {
    "light": { "icon": "◀", "text": "#059669" },
    "dark": { "icon": "◀", "text": "#34d399" }
  },
  "asyncStart": {
    "light": { "icon": "🚀", "text": "#7c3aed" },
    "dark": { "icon": "🚀", "text": "#a78bfa" }
  },
  "asyncComplete": {
    "light": { "icon": "✅", "text": "#059669" },
    "dark": { "icon": "✅", "text": "#34d399" }
  },
  "parameter": {
    "light": { "icon": "", "text": "#64748b", "italic": true },
    "dark": { "icon": "", "text": "#94a3b8", "italic": true }
  },
  "returnValue": {
    "light": { "icon": "", "text": "#0891b2" },
    "dark": { "icon": "", "text": "#22d3ee" }
  },
  "exception": {
    "light": {
      "icon": "💥",
      "text": "#dc2626",
      "background": "#fff5f5",
      "bold": true
    },
    "dark": {
      "icon": "💥",
      "text": "#f87171",
      "background": "#3f1f1f",
      "bold": true
    }
  },
  "runtimeControl": {
    "light": { "icon": "🔧", "text": "#ea580c" },
    "dark": { "icon": "🔧", "text": "#fb923c" }
  }
}

Note: Partial theme files are supported - you only need to specify the categories you want to customize.

Integration Guides

Vite

// vite.config.ts
import { flowTracer } from "@autotracer/plugin-vite-flow";

export default {
  plugins: [
    flowTracer({
      enabled: true,
      runtimeControlled: true,
      include: {
        paths: ["**/src/**"],
        functions: ["handle*", "calculate*"],
      },
      exclude: {
        functions: ["handleError"], // Skip specific functions
      },
    }),
  ],
};

The plugin will automatically inject import "@autotracer/flow/runtime" into your HTML when runtimeControlled: true.

Next.js / Babel

// babel.config.js
module.exports = {
  plugins: [
    [
      "@autotracer/plugin-babel-flow",
      {
        include: {
          paths: ["**/src/**"],
        },
      },
    ],
  ],
};

Then import the runtime in your app entry point:

// app/layout.tsx or pages/_app.tsx
import "@autotracer/flow/runtime";

export default function RootLayout({ children }) {
  return children;
}

The Babel plugin transforms your functions at build time. The runtime import provides the dormant mode browser console controls.

Filtering: Include and Exclude Patterns

Control which functions get instrumented using include and exclude patterns:

Function Patterns

Match functions by name using glob patterns, regular expressions, or exact strings:

flowTracer({
  include: {
    functions: ["handle*", "on*", "process*"], // Only event handlers and processors
  },
  exclude: {
    functions: ["handleError", "onInit"], // Skip specific functions
  },
});

Pattern matching:

• Glob patterns: "handle*", "*Click", "on*Event"
• Regular expressions: /^handle[A-Z]/, /^on[A-Z]\w+$/
• Exact strings: "handleSubmit", "onClick"

File Path Patterns

Instrument only files in specific directories:

flowTracer({
  include: {
    paths: ["**/src/**"], // Only instrument source files
  },
  exclude: {
    paths: ["**/src/utils/**", "**/src/config/**"], // Skip utilities and config
  },
});

Path patterns use glob syntax:

• **/src/** - All files under any src directory
• **/components/**/*.tsx - All TSX files in any components directory
• src/features/** - Files under src/features (non-recursive without **)

Combined Filtering

Both function and path patterns can be used together. A function is instrumented only if it matches all include criteria and none of the exclude criteria:

flowTracer({
  include: {
    paths: ["**/src/features/**"],
    functions: ["handle*", "process*"],
  },
  exclude: {
    functions: ["handleError", "processLogs"],
  },
});

This configuration:

• ✅ Instruments handleSubmit in src/features/form/FormHandler.ts
• ❌ Skips handleError (excluded function)
• ❌ Skips fetchData (not in include functions)
• ❌ Skips any function in src/utils/ (not in include paths)

Performance Considerations

Dormant Mode

When logger is "off" (dormant mode):

• Function calls: ~0.1μs overhead (just the enter/exit calls)
• No string formatting
• No console I/O
• No stack tracking
• Production-safe

Active Mode

When tracing is enabled:

• Console.group nesting: ~50-100μs per function
• Parameter stringification: varies by complexity
• Return value logging: varies by size
• Not recommended for production traffic

Recommendation

Use dormant mode (runtimeControlled: true) in TEST and QA environments. Developers can activate tracing in their browser console when debugging specific issues without any performance impact when disabled.

Security Considerations

Do Not Use in Production

Flow tracing should never be enabled in production environments for the following reasons:

1. Information Disclosure - Function parameters, return values, and exception details are logged to the browser console, potentially exposing:

   • Authentication tokens and credentials
   • Personal identifiable information (PII)
   • Business logic and internal implementation details
   • API keys and sensitive configuration

2. Performance Impact - Active tracing generates significant console I/O overhead that degrades user experience

3. Attack Surface - The window.autoTracer.flowTracer.start() API is accessible to anyone with browser console access, including malicious actors

Recommended Setup

• Local Development - Use normal mode (runtimeControlled: false) for immediate feedback
• TEST/QA Environments - Use dormant mode (runtimeControlled: true) for on-demand debugging
• Production - Disable flow tracing completely using environment-based configuration:

// vite.config.ts
import { flowTracer } from "@autotracer/plugin-vite-flow";

const isDev = process.env.NODE_ENV === "development";
const isQA = process.env.DEPLOY_ENV === "qa";

export default {
  plugins: [
    flowTracer({
      enabled: isDev || isQA, // Disabled in production
      runtimeControlled: isQA, // Dormant in QA, active in dev
      include: { paths: ["**/src/**"] },
    }),
  ],
};

Troubleshooting

No logs appearing

1. Check if runtime control is enabled: window.autoTracer.flowTracer.isEnabled()
2. Activate tracing: window.autoTracer.flowTracer.start()
3. Verify functions are instrumented (check build plugin configuration)

"Flow tracing runtime control ready" message not appearing

The runtime import isn't being loaded. Check:

• Vite plugin has runtimeControlled: true
• HTML injection is working (dev mode)
• Or manually import @autotracer/flow/runtime in your entry point

Functions not traced

Check the build plugin's include/exclude configuration. The plugin only instruments functions matching your patterns.

Too verbose

Adjust which functions are instrumented:

flowTracer({
  include: {
    // Only instrument event handlers
    functions: ["handle*", "on*"],
  },
});

Or use different log levels:

Adjust which functions are instrumented instead:

flowTracer({
  include: {
    // Only instrument specific patterns
    functions: ["handle*", "process*"],
  },
});

Performance impact

If you see performance degradation:

• In development: Normal - console I/O is slow
• In production: Should be in dormant mode with minimal overhead
• Consider instrumenting fewer functions via include.functions patterns

Internals Overview

graph TD
    A[Build Plugin] -->|Transforms code| B[Instrumented Functions]
    B -->|Calls| C[FlowTracer.enter/exit]
    C -->|Delegates to| D[Logger]
    D -->|Checks| E{Log Level}
    E -->|"trace" active| F[console.group/log/groupEnd]
    E -->|"off" dormant| G[No-op]

    H[Runtime Control] -->|Sets| I[Logger Level]
    I -->|Updates| E

    J[Browser Console] -->|Calls| K[window.autoTracer.flowTracer.start]
    K -->|Activates| H

License

MIT