FlowLens — See Every Trace

Getting Started

Install dependencies and start the development server:

bash

npm install
npm run dev

This builds the instrumentation bundle first, then starts Electron in dev mode with hot reload.

Once running, paste your app's URL (e.g. http://localhost:3000) into the onboarding screen. FlowLens loads your app in an embedded browser and auto-injects instrumentation — zero frontend code changes required.

Architecture

FlowLens has three Electron processes:

Main process — Owns the TraceCorrelationEngine (500-trace LRU), source file fetcher, backend span collector (HTTP on :9229), WebSocket server (:9230 for event ingestion), and IPC handler registry.

Target view — Sandboxed WebContentsView that loads the user's URL. Auto-injects the instrumentation bundle on page load and supports element inspection.

Renderer — React UI showing timeline, source code panel, console, and inspector. Subscribes to live event stream from main.

Data Flow

text

Embedded page(auto-injected)  ──WS :9230──▶  ws-server.ts  ──┐
                                                              ├──▶ trace-engine ──▶ renderer
@nihal/flowlens-node           ──HTTP :9229─▶  span-collector ─┘

Both frontend events and backend spans are correlated by traceId, which is propagated via the X-FlowLens-Trace-Id header injected into all outgoing fetch/XHR requests.

Event Types

domClick, submit, input, change, focus, blur events

network-requestOutgoing fetch and XHR requests

network-responseCompleted responses with body preview

network-errorFailed network calls

consoleconsole.log, warn, error, info, debug

errorRuntime errors and unhandled rejections

state-changeReact useState/useReducer mutations

backend-spanServer-side request/handler/response phases

Element Inspector

Click the Inspect button in the target toolbar to activate the element inspector. Hover over any element in the embedded page to see:

• Tag name, classes, and dimensions
• React component name (if applicable)
• Source file location of the component

Click an element to navigate directly to its component's source file in the source code panel.

Backend Tracing

Install @nihal/flowlens-node in your backend to correlate server-side spans with frontend traces. The middleware reads the X-FlowLens-Trace-Id header and reports spans back to FlowLens.

bash

npm install @nihal/flowlens-node

CORS must allow the trace header for cross-origin requests:

typescript

import cors from 'cors'
import { flowlens } from '@nihal/flowlens-node'

app.use(cors({
  origin: true,
  allowedHeaders: ['Content-Type', 'X-FlowLens-Trace-Id']
}))
app.use(flowlens({ serviceName: 'my-api' }))

Each backend span appears as three events in the timeline: ingress, route-handler, and egress. Zero overhead when the trace header is absent.

Quick Setup

1. Start FlowLens desktop: npm run dev
2. Paste your frontend URL (e.g. http://localhost:3000) — instrumentation is injected automatically
3. (Optional) Backend: install @nihal/flowlens-node, attach middleware with CORS headers
4. Use your app — traces appear with frontend + backend events correlated

SDK Reference

@nihal/flowlens-node

Backend span collection SDK — Express, Fastify, and raw HTTP adapters

Documentation