@taiga-ai/monitor-web

A tiny, self-contained Real User Monitoring (RUM) beacon for web apps built with Taiga. It reports how your app behaves in real browsers — Core Web Vitals, JavaScript errors, and client-observed API health — back to your Taiga project's Monitoring surface.

• ~4.8 KiB gzipped, zero runtime dependencies (Google's web-vitals is inlined at build time).
• No cloud credentials, no server code. Runs entirely in the browser using standard web APIs.
• Observe-only. It never alters your responses, swallows your errors, or blocks the page — telemetry is strictly fire-and-forget and never throws into your app.

Install

npm install @taiga-ai/monitor-web

Then call init() once, as early as possible in your app's entry point, with the DSN Taiga gives you for the environment:

import { init } from '@taiga-ai/monitor-web';

init({ dsn: import.meta.env.VITE_TAIGA_MONITOR_DSN });

The DSN is a single token — https://<key>@<host>/beacon — that carries both the ingest endpoint and a per-environment write-only key. Because Taiga mints it per environment, it always points at the right place; you only ever configure one value.

Prefer not to use a DSN? You can pass the endpoint and key separately instead:

init({ key: import.meta.env.VITE_TAIGA_MONITOR_KEY, url: import.meta.env.VITE_TAIGA_MONITOR_URL });

No build step? Use the global script

For static sites or apps without a bundler, load the IIFE global and call TaigaMonitor.init:

<script src="https://unpkg.com/@taiga-ai/monitor-web/dist/monitor-web.global.js"></script>
<script>
  TaigaMonitor.init({ dsn: 'https://taiga_ing_…@…/beacon' });
</script>

Configuration

init(config) takes one object. Provide either a dsn (preferred) or a key + url pair.

| Option | Type | Default | Description | | ----------------- | -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | dsn | string | — | Per-environment ingest DSN, https://<key>@<host>/beacon. Encodes the endpoint + write-only key in one env-correct token. Preferred. | | key | string | — | Per-environment write-only ingest key (taiga_ing_…). Safe to ship in the client bundle. Use with url, or prefer dsn. | | url | string | — | The Taiga /beacon ingest endpoint for this environment. Use with key, or prefer dsn. | | sampleRate | number (0–1) | 1 | Fraction of sessions to instrument. Decided once per page load. | | captureVitals | boolean | true | Collect Core Web Vitals (LCP, INP, CLS, FCP, TTFB). | | captureErrors | boolean | true | Collect uncaught errors and unhandled promise rejections. | | captureRequests | boolean | true | Collect client-observed API calls (fetch + XHR): status and latency. | | beforeSend | (event) => event \| null | — | Transform each event before it is queued, or return null to drop it. Use for extra PII scrubbing. |

The dsn (or key + url) and any of the flags are the only configuration — there is nothing to set up inside the package itself.

What it collects

Every measurement is sent as a small, self-describing event { kind, name?, value?, unit?, attributes?, occurredAt }:

• web_vital — Core Web Vitals via web-vitals, with each metric's rating (good / needs-improvement / poor).
• error — uncaught errors and unhandled rejections (message and stack are length-capped; passive listeners, so your own handlers are preserved).
• api_call — the HTTP status and latency of fetch/XHR requests as the browser observes them. Requests are observed, never modified: the original response is returned untouched and errors are re-thrown.

Privacy

URLs are scrubbed client-side before anything leaves the page — the query string and fragment (which routinely carry tokens, ids, and PII) are dropped, keeping only origin + path. Request and response bodies are never read. Use beforeSend to redact or drop anything else specific to your app.

The ingest key (whether passed directly or embedded in the dsn) is write-only: it can submit telemetry to your environment's ingest but cannot read anything back, which is why it is safe to embed in a public client bundle.

Batching & delivery

Events are batched and sent with navigator.sendBeacon (a text/plain POST that survives page unload and skips the CORS preflight), falling back to fetch(keepalive). Batches flush when full, on an interval, and when the page is backgrounded (visibilitychange → hidden / pagehide).

License

MIT. Bundles web-vitals (Apache-2.0); see THIRD_PARTY_NOTICES.txt.