Getting started

How it works

A technical overview of what the Rytena agent captures, how leaks are detected, and how root cause analysis is generated.

Architecture

Rytena has three components: the agent that runs inside your Node.js process, the backend that receives metrics and coordinates analysis, and the dashboard where you view results.

text

  Your Node.js App
       │
       │  every 10s
       ▼
  ┌──────────────┐
  │ Rytena Agent │
  │              │
  │ • heap stats │
  │ • deep scan  │
  └──────┬───────┘
         │  HTTPS + API key
         ▼
  ┌──────────────┐
  │   Backend    │
  │              │
  │ • persistence│
  │ • leak logic │
  │ • AI analysis│
  └──────┬───────┘
         │
         ▼
    Dashboard

What the agent captures

Every interval (default 10 seconds), the agent captures a quick snapshot using Node's built-in process.memoryUsage(). This is cheap — under 1ms of overhead.

heapUsed — memory currently used by V8's JavaScript heap
heapTotal — total heap V8 has allocated
rss — resident set size, total process memory
external — memory used by C++ objects bound to JS

How leaks are detected

The agent maintains a rolling window of the last 10 snapshots. When it has at least 5 snapshots, it checks for sustained growth.

If heap usage grows more than 15% between the oldest and newest snapshot in the window, the agent flags it as a suspected leak.

text

Snapshot 1:  120 MB
Snapshot 2:  128 MB
Snapshot 3:  135 MB
Snapshot 4:  148 MB
Snapshot 5:  164 MB    → 37% growth = LEAK

Severity levels

Low — 15-25% growth
Medium — 25-50% growth
High — 50-100% growth
Critical — 100%+ growth

Deep scan for source location

When a leak is detected, the agent runs a 30-second deep scan using Node's built-in inspector module. This uses V8's sampling heap profiler to identify which functions are allocating the most memory.

The scan filters out allocations from node_modules and Node internals, returning only your application code. It identifies the exact file, function, and line responsible for the most allocation during the leak window.

Deep scans have a 5-minute cooldown between runs to avoid performance impact. Only one scan runs at a time per process.

Root cause analysis

Once the agent identifies the leak location, it extracts a 10-line code snippet around the leak line and sends everything to the backend.

The backend runs the leak metadata and source code through a large language model. The AI produces:

A plain-English explanation of why the code leaks memory
A specific recommendation for how to fix it
A corrected code snippet

The analysis references the actual variable names and patterns from your code, not generic advice.

Notifications

When a high or critical leak is detected, Rytena creates an alert and sends an email to the configured address. Medium and low leaks appear in the dashboard but do not trigger emails.