web-tracing: a browser-side frontend monitoring SDK for tracking, errors, performance and session replay

What web-tracing collects, and the team it was written for

The problem web-tracing addresses is the gap between a frontend application and the platform team that has to observe it. A browser app can throw, stall, fire a slow request, fail to render a lazy image, or lose a user in a broken route transition without any of that reaching a server log. web-tracing is a JS plugin that instruments the page and ships those signals somewhere you control. The README lists the collection surface as 埋点 (custom tracking events), behaviour, performance, exception, request, resource, route, exposure and screen recording.

The audience is explicit. The project's stated motivation is to help developers build a frontend monitoring platform on their own company's infrastructure, and the author writes that the goal is to reduce the time and effort frontend teams spend on this. That framing matters when you evaluate the API: this is not a hosted product with a dashboard, it is the client half of a system you assemble. The repository ships a demo, the core SDK and the documentation in one monorepo, which the README says was a deliberate choice so that debugging and deployment stay convenient.

One design decision is stated openly and is unusual. The author says the core code is deliberately not split into sub-packages, even though the monorepo layout would allow it, because splitting would hurt readability and make secondary development harder. If your team plans to fork and modify the SDK, that is a point in its favour. If you wanted to import only the performance collector and leave the rest out of your bundle, it is a constraint you will feel.

How the SDK is structured: one core, several platform builds

The repository is a pnpm workspace. The root package.json names it @web-tracing/monorepo, sets packageManager to [email protected], and defines the build pipeline through esno scripts/build.ts and a rollup.config.js. Top-level entries include packages/, docs/, examples/, meta/ and scripts/, and the example directory carries vanilla, vue2, vue3, react and nuxt variants. The README states that multiple platform versions are produced from the monorepo and published with one command.

Inside the SDK, the README says there is a large amount of rewriting and listening, and that a unified flow was built around it. It also says the project implements Vue-style reactivity internally and applies it to the options object. That is the mechanism behind the configuration API: options are reactive, so changing a value at runtime can change collector behaviour rather than requiring a re-initialisation. Whether that is a benefit or a surprise depends on your mental model, but it is a real architectural choice and not a wrapper around an existing library.

The SDK does not implement everything itself. The README's acknowledgement section says screen recording is handled by rrweb, unique user identification uses an offline copy of fingerprintjs v3.4.1, and public IP detection uses an offline copy of webrtc-ip v3.0.1. Those are vendored rather than pulled as live dependencies, which keeps the bundle self-contained but also means upstream fixes in those libraries do not arrive automatically.

Installing web-tracing and sending a first tracking event

The README points readers to the official documentation at m-cheng-web.github.io/web-tracing for setup, and to the example repositories for runnable projects: web-tracing-examples-js, web-tracing-examples-vue2, web-tracing-examples-vue3, web-tracing-examples-react and web-tracing-examples-nuxt. The monorepo itself can be installed and built locally, and the root package.json exposes the scripts for that.

To work on the SDK from source, install dependencies with pnpm and run the build script. The repository pins [email protected], so use that version if you want the lockfile to behave.

pnpm install
pnpm run build

The build script first runs scripts/update.ts and then executes the esno build task, so the generated output reflects the current package metadata. If you only want type declarations, the separate script is build:types, which runs tsc --emitDeclarationOnly and then scripts/fix-types.ts.

To exercise the SDK in a browser without wiring your own app, the repository provides per-framework dev scripts. The vanilla example is the smallest one.

pnpm run test:js

That resolves to a dev server inside examples/vanilla. The vue2, vue3, react and nuxt equivalents are test:vue2, test:vue3, test:react and test:nuxt. Running one of these is the fastest way to see what the collectors actually emit before you integrate the SDK into a real application.

The README does not reproduce the initialisation snippet or the options schema in the repository root. Those live in the documentation site and in the example projects, so read the example closest to your framework before you write your own init call.

Bandwidth control is the API's centre of gravity

The README's highlights section is almost entirely about reducing what the SDK sends. That tells you where the author expected the pain to be: monitoring data is cheap to collect and expensive to store, and a naive collector will flood your endpoint.

Four mechanisms are named. There is a localisation option API that lets the developer decide manually when monitoring data is sent, so collection and transmission are decoupled. There is a batch error API that merges error information when the page hits an infinite error loop, which is the classic case where a single broken render produces thousands of identical payloads. There is a sampling API for sending. And there are filter APIs for error and request events.

Taken together, these are the controls you would otherwise build yourself after your first traffic spike. The trade-off is that the SDK does not decide for you. Manual localisation means you own the flush logic, including the question of what happens to buffered events when the user closes the tab. Sampling means your error counts are estimates, and the README does not describe how sampled data is weighted or labelled downstream. If you need exact per-error counts for a support investigation, sampling is the wrong setting to leave on.

The README also mentions hook functions that let you intervene in the data flow. Those hooks are the extension point for reshaping events before they leave the browser, which matters if your backend schema does not match the SDK's default payload.

Maintenance status: low-frequency by the author's own statement

This is the part to read before anything else. The README carries an important notice stating that web-tracing is the open source starting point for Tracera, that the project will move to low-frequency, necessary maintenance only, that there will be no further high-frequency feature iteration, and that no fixed version or issue response cycle is promised.

The repository is not archived, and the last push was on 2026-09-21, so the code is not abandoned. But a recent commit and an active roadmap are different things, and the author has said plainly which one this is. Bug reports go to GitHub Issues, with the same caveat about response time attached.

Tracera is described as an independent project rebuilt along the same frontend monitoring line of work, covering server-side reliable processing, data analysis, error scene replay, Source Map resolution, PageSpy direct user connection, private deployment, and an Agent Runtime based on real system evidence. The README states Tracera is in Beta and that the SDK and frontend layers are intended to be open sourced after the Beta period, with project details and trial access at the Tracera site.

The practical reading: if you adopt web-tracing today, you are adopting a stable client SDK with a frozen feature set, not a product with a roadmap. Plan your fork accordingly, because upstream will not absorb your feature requests.

Where web-tracing is the wrong tool, and what to use instead

web-tracing stops at the browser boundary. It collects and transmits. There is no ingestion service, no storage, no alerting and no issue grouping in this repository. If your team wants to open a dashboard on Monday and see grouped exceptions with stack traces mapped to source, this SDK is one component of that, not the whole answer.

Sentry is the obvious alternative, and the difference is architectural rather than a matter of feature lists. Sentry ships a hosted or self-hosted backend alongside its browser SDK, so error grouping, release tracking and Source Map resolution are handled by the platform. web-tracing gives you the collection layer and expects you to build or buy the rest. If you already run an observability stack and only need a browser collector that speaks your schema, web-tracing's hooks and filter APIs are a reasonable fit. If you want the pipeline included, Sentry is the shorter path.

The README names one backend that pairs with this SDK: WebTracingAnalysis, described as Spring Boot + MySQL + React + Ant Design with containerised deployment support. That is the closest thing to an official server side, and it is a separate repository with its own maintenance story, which you should check independently.

There is also a scope limit worth stating. The SDK runs in the browser and depends on browser APIs; the vendored webrtc-ip copy for public IP detection is a good example of a capability that only exists client-side. Nothing here instruments a Node service or a native app.

Licence and the cost of keeping a fork alive

web-tracing is MIT licensed, and the LICENSE file sits at the repository root. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. The vendored components complicate the picture slightly: rrweb, fingerprintjs v3.4.1 and webrtc-ip v3.0.1 are bundled as offline copies, and each carries its own licence, so a redistribution audit needs to cover those too. This is a description of the licence terms, not legal advice; check the bundled licences yourself before shipping.

The upgrade cost is where the maintenance notice bites. Because the core is intentionally not split into sub-packages, a fork that changes collector behaviour touches the same files that upstream would change, and there is no package boundary to absorb the conflict. A team that patches the SDK heavily should expect to carry those patches rather than rebase them cleanly.

On the build side, the toolchain is pinned and conventional: [email protected], rollup, TypeScript, vitest for tests with a coverage variant, and eslint configured through .eslintrc.cjs. The clean script removes dist and per-package dist directories, which is the script to reach for when a build produces stale artifacts. None of this is exotic, which lowers the cost of keeping a fork building even if upstream slows down.

Editorial conclusion

Adopt web-tracing if you need a self-hosted, MIT-licensed browser SDK that covers tracking, errors, performance, requests, resources, routes, exposure and replay in one package, and you accept that new feature work has stopped. Do not adopt it if you need a vendor-backed error triage pipeline, server-side ingestion, or a guaranteed issue response time: the README states maintenance is low-frequency and no fixed version or issue cadence is promised. Before committing, verify that your bundler can consume the monorepo package output, and check whether the WebTracingAnalysis backend or Tracera's Beta matches the workflow you actually need.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. M-cheng-web/web-tracing on GitHub
4. Project website
5. README