Real-user performance debugging for frontend engineers.
Find the interaction. Find the frame. Find the component. Find the release.
Quick start · Documentation · Workflows · Packages · Contributing
TraceLens turns browser telemetry into an explanation. Start with a slow interaction, follow the browser, React, network, layout, and custom work that overlapped it, map expensive scripts back to source, and compare the same signal across releases.
Important
TraceLens is a local-first debugging toolkit—not a hosted RUM backend. Studio binds to loopback, keeps telemetry in bounded memory, and requires no account.
| A metric tells you… | TraceLens helps you answer… |
|---|---|
| INP p75 is 487 ms | Which interaction produced it? |
| Main-thread work was high | Which long frame and script consumed the time? |
| React committed during the delay | Which profiled boundary rendered, how long, and how often? |
| A request overlapped the interaction | Which sanitized fetch or XHR call was involved? |
| Performance changed | Which release, route, interaction, or component regressed? |
Requires Node.js 22 or newer.
1. Start Studio
npx @leracherry/tracelens-cli@1.0.0 studioStudio opens at http://127.0.0.1:4173 and exposes a loopback-only collector at /__tracelens.
2. Instrument the browser
npm install @leracherry/tracelens-browserimport { init } from '@leracherry/tracelens-browser';
const stopTraceLens = init({
app: 'checkout',
release: '1.0.0',
environment: 'development',
endpoint: 'http://127.0.0.1:4173/__tracelens',
});
// Flush queued telemetry and restore patched browser APIs.
await stopTraceLens();3. Name important work
<button data-tracelens-name="Save settings">Save</button>import { trace } from '@leracherry/tracelens-browser';
await trace('validate-settings', async () => {
await validateSettings();
});Click the control, then select the newest interaction in Studio.
Follow the complete five-minute setup, or open the Vanilla and React + Vite examples.
| Signal | What TraceLens records | Where it appears |
|---|---|---|
| Event Timing | Input delay, processing, presentation, route, accessible interaction name | Interaction summary and timing bar |
| Long Animation Frames | Duration, blocking time, script attribution, first/third-party classification | Browser lane and frame explorer |
| React Profiler | Boundary, phase, actual/base duration, render count | React lane and component table |
| Fetch and XHR | Method, sanitized URL, status, duration | Network lane |
| Layout Shift | Score, recency, interaction correlation | Layout lane |
| Custom spans and marks | Named application work | Custom lane and exported traces |
| Build metadata | Release, commit, environment, build timestamp | Release selector and ReleaseScope |
One interaction, from input delay to its source-mapped long-frame contributor.
flowchart LR
A[Reproduce a slow action] --> B[Open its Studio trace]
B --> C[Inspect timing segments]
C --> D[Follow correlated lanes]
D --> E[Open the source-mapped contributor]
ReleaseScope compares p75 values across captured builds and ranks the interaction, route, and React component deltas that changed most.
npx @leracherry/tracelens-cli compare 2.13.4 2.14.0 --file trace.jsonname: Performance budget
on: [pull_request]
permissions:
contents: read
checks: write
pull-requests: write
jobs:
tracelens:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: leracherry/tracelens@v1.0.0
with:
trace-file: artifacts/tracelens-events.json
github-token: ${{ secrets.GITHUB_TOKEN }}The Action publishes a job summary, JSON artifact, GitHub Check, and one continuously updated pull-request comment. See the complete CI workflow and Action guide.
import { init } from '@leracherry/tracelens-browser';
import { createTraceLensExporter } from '@leracherry/tracelens-otel';
init({
app: 'checkout',
transport: createTraceLensExporter({
endpoint: 'http://localhost:4318/v1/traces',
}),
});TraceLens emits OTLP/HTTP JSON spans with resource, release, interaction, HTTP, React, and timing attributes. Use the collector example and OTel guide.
tracelens studio Start the local collector and UI
tracelens inspect trace.json Explain the slowest interaction
tracelens compare BEFORE AFTER Compare two captured releases
tracelens doctor Audit local instrumentation setup
tracelens privacy audit Find risky telemetry values
tracelens sourcemaps upload ./dist Import maps into the local store
tracelens budget check Evaluate release and route budgets
Run npx @leracherry/tracelens-cli --help or open the CLI reference for every option and exit-code contract.
flowchart TB
APP[Browser application] --> SDK[Browser SDK]
REACT[React Profiler boundaries] --> SDK
SDK --> PRIVACY[Privacy filter + correlation]
PRIVACY --> STUDIO[Local Studio collector]
PRIVACY --> OTLP[OTLP/HTTP collector]
STUDIO --> INSPECT[Interaction inspector]
STUDIO --> RELEASE[ReleaseScope]
RELEASE --> CLI[CLI budgets + comparisons]
CLI --> GH[GitHub Action]
The event protocol is versioned and storage-independent. Read the architecture overview and interaction-correlation design.
| Package | Purpose |
|---|---|
@leracherry/tracelens-browser |
Browser instrumentation, correlation, privacy, and transports |
@leracherry/tracelens-react |
React Profiler integration and explicit boundaries |
@leracherry/tracelens-vite |
Release, commit, environment, and build metadata injection |
@leracherry/tracelens-cli |
Bundled Studio, reports, diagnostics, source maps, and budgets |
@leracherry/tracelens-protocol |
Versioned telemetry types and runtime validation |
@leracherry/tracelens-core |
Queries, release aggregation, diffs, and source resolution |
@leracherry/tracelens-storage-memory |
In-memory storage adapter |
@leracherry/tracelens-storage-file |
Local JSON storage adapter |
@leracherry/tracelens-otel |
TraceLens-to-OTLP mapping and HTTP export |
All packages are published to npm and mirrored to GitHub Packages. Keep package versions aligned.
TraceLens excludes input values, DOM text, request bodies, and headers. It removes URL credentials, query strings, fragments, and email-shaped path segments by default. Element IDs and aria-label values require opt-in.
Warning
Default redaction is not anonymization. Application-provided span names, release metadata, and URL path segments can still contain sensitive values. Audit synthetic telemetry before production rollout.
Studio is an unauthenticated development tool. It binds to loopback, accepts browser requests only from loopback origins, keeps at most 50,000 events in memory, and should never be exposed through a public proxy.
Read the privacy model, delivery lifecycle, and browser support and overhead.
- Core instrumentation degrades safely when a Performance API is unavailable.
- Event Timing and Long Animation Frames are most complete in Chromium-based browsers.
- React production attribution requires a profiling-enabled React build.
- Release comparisons describe captured samples; they do not claim statistical significance.
- The OTLP transport is a TraceLens transport, not an OpenTelemetry SDK
SpanExporter. - Studio storage is intentionally local and ephemeral.
git clone https://github.com/leracherry/tracelens.git
cd tracelens
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm devOpen http://127.0.0.1:4174 for controlled search, settings, checkout, layout, and third-party scenarios. Open http://127.0.0.1:4173 to inspect them. The guided workflow explains the expected evidence.
The searchable site is available at leracherry.github.io/tracelens.
Every push to main verifies formatting, strict TypeScript, unit tests, production builds, browser integration, browser bundle size, runtime overhead, Studio keyboard/accessibility/responsive behavior, visual regression, documentation, packed npm artifacts, the bundled Studio, and the repository Action.
pnpm typecheck
pnpm test
pnpm build
pnpm quality:browser
pnpm quality:studio
pnpm docs:check
node scripts/release.mjs npm
node scripts/smoke-release.mjsSee CONTRIBUTING.md for development setup and reproducible product captures.
TraceLens 1.0 stabilizes the browser API, React attribution, release comparison, local Studio, OpenTelemetry export, source-map workflow, performance budgets, and GitHub integration described above. Future work stays focused on frontend interaction debugging rather than expanding into session replay or general-purpose APM.
TraceLens is released under the MIT License.