Skip to main content

​
Architecture Overview

Ladybugs consists of three main components that work together to provide comprehensive runtime debugging:
1

Code Instrumentation

Babel plugin adds tracing to your source code during build
2

Data Collection

Instrumented code captures runtime data and sends it to your server
3

AI Integration

MCP server provides AI assistants with query access to runtime data

​
Code Instrumentation with Babel

Ladybugs uses a Babel plugin to automatically instrument your JavaScript and TypeScript code during the build process. This happens transparently without requiring you to manually add logging statements.

​
What Gets Instrumented

The Babel plugin adds tracing for:
  • Function calls - Entry and exit points, parameters, return values
  • Variable assignments - Track how data changes throughout execution
  • Conditional statements - Which branches were taken and why
  • Loops - Iterations, break conditions, loop variables
  • Data access - Object property reads/writes, array operations
  • Errors - Full stack traces with runtime variable values
  • And much more!

​
Data Captured

Each trace event includes:
  • Timestamp - Precise execution time
  • Context - Request ID, user ID, session info
  • Location - File, function, line number
  • Data - Variable values, parameters, return values
  • Metadata - Environment, version, deployment info
  • And much more!

​
AI Integration via MCP

The Model Context Protocol (MCP) server bridges your AI assistant with Ladybugs data.

​
Query Capabilities

When you ask your AI assistant about a production issue, the MCP server can:

Search by Context

Find traces based on user actions, error messages, or specific data values

Trace Execution

Follow the complete execution path of a request through your codebase

Analyze Data Flow

Track how data transforms as it moves through your application

Identify Patterns

Discover common patterns in errors or unexpected behavior

​
Example Query Flow

1

Natural Language Query

You: “I tried to create a post with the title ‘Banana’ and it failed”
2

AI Understanding

The AI assistant understands you want to find traces related to:
  • Function: createPost
  • Parameter: title = 'Banana'
  • Outcome: Error/failure
3

MCP Query

The MCP server translates this to a structured query:
{
  "function": "createPost",
  "params.title": "Banana",
  "hasError": true,
  "timeRange": "last 24 hours"
}
4

Data Retrieval

The server finds matching traces and returns:
  • Full execution flow
  • All variable values at each step
  • The exact error and why it occurred
5

AI Analysis

The AI analyzes the runtime data and provides:
  • Root cause explanation
  • Code location of the issue
  • Suggested fix

​
Security & Privacy

​
Data Isolation

  • Self-hosted - All data stays in your infrastructure

​
Supported Languages & Frameworks

​
JavaScript & TypeScript

Full support for modern JavaScript/TypeScript features:
  • ES6+ syntax (async/await, destructuring, etc.)
  • JSX/TSX for React components
  • TypeScript types (preserved in traces)
  • Decorators and class syntax

​
Frameworks

  • Express.js
  • Fastify
  • NestJS
  • Next.js (API routes)
  • Any Node.js application

​
Next Steps

MCP Setup

Connect Ladybugs to your AI assistant

Setup Guide

Set up Ladybugs in your repository