Getting started

Use Node.js 22 or newer for the CLI and build integration. Packages are ESM with TypeScript declarations.

npm install @leracherry/tracelens-browser
npx @leracherry/tracelens-cli@1.0.0 studio

Open http://127.0.0.1:4173. Add this to your application's browser entry point:

import { init } from '@leracherry/tracelens-browser';

const stop = init({
  app: 'dashboard',
  release: '1.0.0',
  environment: 'development',
  endpoint: 'http://127.0.0.1:4173/__tracelens',
});
// Call await stop() when instrumentation should stop.

Initialize once per page. The SDK batches events every second by default. Use explicit, non-sensitive data-tracelens-name attributes on controls to make interactions recognizable.

Vite

npm install --save-dev @leracherry/tracelens-vite

import { defineConfig } from 'vite';
import { tracelens } from '@leracherry/tracelens-vite';

export default defineConfig({ plugins: [tracelens()] });

The plugin injects the nearest package version, Git commit, current build time, and Vite mode. You can override these in the plugin options or SDK init(); explicit SDK values take priority.

Browser, React, and custom work

Use the browser instrumentation guide for transports, naming, custom spans, trace propagation, and browser support. Install @leracherry/tracelens-react alongside @leracherry/tracelens-browser and follow the React guide. Wrap expensive operations with trace('operation-name', fn) to capture custom spans.

Local collection and data handling

The packaged Studio requires neither Vite nor a repository checkout. It retains the most recent 50,000 events in memory, accepts batches up to 1 MiB, and loses data when stopped. To save events:

curl http://127.0.0.1:4173/__tracelens -o trace.json
npx @leracherry/tracelens-cli inspect trace.json

Use Studio on loopback for local debugging. It has no authentication and permits browser applications to post telemetry across origins. An HTTPS application may block an HTTP collector as mixed content; use a suitable local proxy in that case.

The SDK does not capture input values, request bodies, or headers. URL credentials, queries, fragments (including hash routes), and email-shaped path segments are removed by default. Element IDs and aria-labels require explicit opt-in. Other routes, explicit names, and build metadata can still contain sensitive information. Review those values and your consent requirements before production use. See privacy controls and auditing, and check registry availability before using the npm commands above.