TraceLens v1.0.0

TraceLens v1.0.0

TraceLens 1.0 is the production-readiness release: stable public APIs, a polished local debugging workflow, strict telemetry validation, hardened Studio boundaries, complete reference documentation, runnable examples, and verified distribution artifacts.

What is stable

• Browser initialization, shutdown, marks, custom spans, privacy controls, batching, and retry behavior.
• Interaction, INP, long-frame, layout-shift, fetch/XHR, and Web Vital capture where browser APIs permit it.
• React Profiler boundaries with commit duration and render-count attribution.
• Release metadata, ReleaseScope comparisons, CLI inspection, source maps, and GitHub source links.
• OTLP/HTTP JSON export and opt-in, origin-allowlisted trace-context propagation.
• Release and route performance budgets plus GitHub Checks, summaries, artifacts, and pull-request comments.
• The version 1 telemetry protocol and storage adapter contracts.

Final-phase hardening

• Validate every supported event type and payload at collector and file-ingestion boundaries; reject unknown event types, invalid timings, malformed trace contexts, and negative durations.
• Restrict browser access to the local Studio collector to loopback origins instead of exposing permissive cross-origin reads and writes.
• Fix sampleRate: 0 so even a zero-valued random sample can never initialize telemetry.
• Read the CLI version from its package manifest, removing a manual version-drift point.
• Point package runtime and type exports at shipped build artifacts, with tarball smoke tests that verify imports, declarations, the CLI, and bundled Studio.
• Fail release publication before creating downstream packages or releases when npm publication fails.
• Add local documentation-link validation to CI and release workflows.

Product polish

• Adopt one restrained, accessible interface system across Studio, ReleaseScope, Playground, and the documentation site.
• Refresh all static screenshots, the animated Studio tour, and the visual-regression baseline.
• Rebuild the repository README around real workflows, architecture, packages, privacy boundaries, and quality guarantees.
• Add task-oriented workflow and troubleshooting guides, browser/CLI/configuration reference pages, and Vite integration documentation.
• Add complete Vanilla TypeScript and React + Vite examples alongside existing budget, Action, OTLP, and trace fixtures.

Upgrade

Keep all TraceLens packages on the same version:

npm install \
  @leracherry/tracelens-browser@1.0.0 \
  @leracherry/tracelens-react@1.0.0

npx @leracherry/tracelens-cli@1.0.0 studio

The telemetry protocol remains version 1, so valid v0.x trace files remain compatible. The stricter runtime guard can reject malformed or unofficial event payloads that earlier versions accepted shallowly.

Operational boundaries

Studio remains a loopback-only, unauthenticated development tool with bounded in-memory storage. Browser Performance API coverage varies, production React profiling requires a profiling-enabled build, and release comparisons describe captured samples rather than statistical significance.

Read the getting-started guide, common workflows, configuration reference, and troubleshooting guide.

TraceLens v0.4.0

TraceLens v0.4.0

Release-aware performance budgets, native GitHub reporting, and a searchable documentation site.

Highlights

• Define global INP, LCP, CLS, and long-frames-per-session budgets in tracelens.yml.
• Add route-level interaction p75 thresholds and minimum sample requirements that fail closed when telemetry is missing.
• Run budgets from the CLI with human-readable or stable JSON output, selecting an explicit release or the newest captured release.
• Use leracherry/tracelens@v0.4.0 as a self-contained Node 24 GitHub Action.
• Publish results to the job summary, a downloadable JSON artifact, a dedicated GitHub Check, and one deduplicated pull-request comment.
• Run the Action in reporting-only mode while establishing baselines, with fork permission failures reduced to warnings.
• Browse a VitePress documentation site with local search, structured navigation, detailed browser and React setup, an interaction-debugging tutorial, and a system architecture guide.

Performance budget quick start

Create tracelens.yml:

minimumSamples: 20

performance:
  inp:
    p75: 200
  lcp:
    p75: 2500
  cls:
    p75: 0.1
  longFramesPerSession:
    max: 1

routes:
  /checkout:
    inp:
      p75: 150

Run it locally:

npx @leracherry/tracelens-cli@0.4.0 budget check \
  --config tracelens.yml \
  --file trace.json \
  --release 2.14.0 \
  --app billing-dashboard \
  --environment production

Or in GitHub Actions:

permissions:
  contents: read
  checks: write
  pull-requests: write

steps:
  - uses: actions/checkout@v5
  - uses: leracherry/tracelens@v0.4.0
    with:
      trace-file: artifacts/tracelens-events.json
      github-token: ${{ secrets.GITHUB_TOKEN }}

Documentation

The new documentation portal is published at https://leracherry.github.io/tracelens/. Start with browser instrumentation, React integration, or the slow-interaction walkthrough.

Compatibility and limits

Upgrade all TraceLens npm packages together to 0.4.0. The event protocol remains version 1. The GitHub Action is distributed with the repository release rather than as a separate npm package.

Budget results describe the supplied telemetry sample and do not establish statistical significance. Route budgets currently support interaction p75. The Action requires a JSON event artifact from an earlier workflow step; it does not collect browser telemetry itself.

Studio remains a local development tool with no authentication. Production React timing still requires a profiling-enabled React build, and browser API support varies.

TraceLens v0.3.0

TraceLens v0.3.0

Source-level long-frame attribution and a more visual repository presentation.

Highlights

• Import external .js.map and .mjs.map files into a bounded local source-map store with tracelens sourcemaps upload.
• Record Long Animation Frame sourceCharPosition offsets and resolve them against the exact generated script for the matching app and release.
• Show original file, line, column, mapped function name, and safe commit-pinned GitHub links in Studio.
• Preserve unresolved contributions instead of guessing locations when maps or positions are unavailable.
• Add authentic Studio interaction and ReleaseScope screenshots plus a reproducible Playwright capture script.
• Refresh README navigation, product story, architecture overview, badges, package documentation, and repository metadata.

Source-map quick start

npx @leracherry/tracelens-cli@0.3.0 sourcemaps upload ./dist \
  --app dashboard \
  --release 2.14.0 \
  --url-prefix https://app.example.com/ \
  --repository https://github.com/owner/repo \
  --commit 7ac841f

npx @leracherry/tracelens-cli@0.3.0 studio

The app and release must match browser telemetry, and the generated URL match is exact. Imports are local, immutable per app/release, and limited to 20 MiB. Source contents are removed from imported maps. TraceLens never fetches maps from telemetry URLs.

See the source-map guide for supported map formats, privacy behavior, and GitHub-link rules.

Compatibility and limits

All packages should be upgraded together to 0.3.0. The public package namespace remains @leracherry/tracelens-*.

Source resolution supports flat v3 maps and Chromium's Long Animation Frames character offsets. It does not yet support indexed maps, inline maps, error-stack mapping, or remote uploads. Studio remains a local, unauthenticated, in-memory tool.

TraceLens v0.2.1

TraceLens v0.2.1

Fixes package publication by using the account-owned @leracherry/tracelens-* namespace on both npm and GitHub Packages.

• All nine packages, workspace imports, examples, and documentation now use the same namespace.
• CI tests installation of the actual release tarballs, runtime imports, CLI version, and bundled Studio.
• Both registries receive matching package names and dependency versions; no registry-specific import rewriting is needed.
• Privacy controls and OpenTelemetry support from v0.2.0 are unchanged.

Install from npm

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

import { init } from '@leracherry/tracelens-browser';
init({ app: 'dashboard', endpoint: 'http://127.0.0.1:4173/__tracelens' });

Replace old @tracelens/browser imports with @leracherry/tracelens-browser (and likewise for every package). Keep all packages on 0.2.1. GitHub Packages users already using the account scope only need to update versions.

See registry setup. GitHub Release assets contain all nine npm tarballs.

TraceLens v0.2.0

TraceLens v0.2.0

Privacy controls and OpenTelemetry integration (Phases 16–17).

Added

• Configurable element-attribute allowlists, URL query allowlists, path-segment redaction, and custom URL sanitizers before telemetry is queued.
• CLI tracelens privacy audit for local Studio events or trace files. Findings omit detected values; exit code 1 means findings or an error, not a compliance assessment.
• New @tracelens/otel transport for OTLP/HTTP JSON trace export, including resource/build metadata and interaction-linked span contexts.
• Opt-in W3C traceparent propagation for fetch requests to exact allowed origins. Existing trace headers are preserved.
• Nine package-specific READMEs, updated setup guides, and version-aware release notes and smoke checks.

Upgrading from v0.1.0

Update all TraceLens packages together to 0.2.0. Default element attributes are now data-tracelens-name, role, and type; explicitly allow aria-label or id only after reviewing their contents. Prefer stable, non-sensitive data-tracelens-name labels.

URL credentials, queries, fragments (including hash routes), and email-shaped path segments are removed before queueing. This can change route grouping and labels compared with old traces. Configure path redaction for user/order identifiers; custom names and metadata are not automatically anonymized.

Create the OTLP exporter before calling browser init(). Selecting this transport replaces Studio delivery. Propagation is disabled by default and may require server CORS changes when enabled.

Installation and artifacts

See registry availability and setup. npm uses @tracelens/*; the GitHub Packages mirror uses @leracherry/tracelens-*. npm scope access previously blocked publication and is checked separately by the workflow. GitHub Release assets contain nine npm-format tarballs; those do not imply npm registry availability.

Limits

The OTLP transport is not an OpenTelemetry SDK SpanExporter. It exports traces only; Web Vitals are represented as spans, not metrics. XHR timing is exported but propagation is fetch-only. Existing external trace contexts are preserved but not adopted as local parents. This is not a general-purpose asynchronous context manager.

Studio remains a local, unauthenticated, in-memory tool. Privacy auditing is heuristic. Source maps, CI budgets, and hosted collection remain future work. Automated tests exercise OTLP payloads and transport behavior; a live Collector integration was not validated locally.

Guides: Privacy · OpenTelemetry.

TraceLens v0.1.0

TraceLens v0.1.0

The first public release brings browser interaction debugging and release comparisons to a local Studio.

Included

• Browser Event Timing, INP subparts, LCP, CLS, long animation frames, fetch/XHR timing, and custom spans.
• React Profiler boundaries with interaction correlation and component timing tables.
• A Vite plugin that injects release, commit, environment, and build timestamp.
• ReleaseScope comparisons for interaction and route timings, LCP, long frames per session, and React components.
• A standalone CLI with bundled Studio, inspect, compare, and doctor commands.
• Protocol, core, and memory/file storage packages with compiled ESM and TypeScript declarations.

Quick start

npm install @tracelens/browser
npx @tracelens/cli@0.1.0 studio

See the getting started guide for SDK configuration.

Limits in this release

Studio stores up to 50,000 events in memory and clears them when stopped. It is a local development tool and has no authentication. Keep its default loopback host.

Browser support varies by Performance API. React production profiling requires a profiling-enabled React build. Release comparisons are descriptive: the current INP p75 is computed across captured interaction durations, LCP p75 across captured LCP samples, and render counts are raw sample counts. Populations and capture lengths can differ; percentage changes do not establish statistical significance. The Studio highlights changes above 5%. Long-frame count increases do not identify individual new frame sources.

Privacy configuration, source-map resolution, OpenTelemetry export, CI budgets, and hosted collection are not included in v0.1.0. Review application-supplied names, labels, routes, and metadata before collecting production telemetry.

Registries

The npm distribution uses @tracelens/*. GitHub Packages uses the repository owner's namespace, @leracherry/tracelens-*. Tarballs attached to this release are the npm distribution.