@taiga-ai/monitor-web 0.1.0-dev.1 → 0.1.0-rc.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +73 -0
- package/package.json +2 -1
package/README.md
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# @taiga-ai/monitor-web
|
|
2
|
+
|
|
3
|
+
A tiny, self-contained **Real User Monitoring (RUM) beacon** for web apps built with [Taiga](https://tai.ga). 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
|
+
|
|
5
|
+
- **~3.7 KiB gzipped**, zero runtime dependencies (Google's [`web-vitals`](https://github.com/GoogleChrome/web-vitals) is inlined at build time).
|
|
6
|
+
- **No cloud credentials, no server code.** Runs entirely in the browser using standard web APIs.
|
|
7
|
+
- **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.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install @taiga-ai/monitor-web
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Then call `init()` once, as early as possible in your app's entry point:
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { init } from '@taiga-ai/monitor-web';
|
|
19
|
+
|
|
20
|
+
init({
|
|
21
|
+
key: import.meta.env.VITE_TAIGA_MONITOR_KEY, // per-environment write-only ingest key
|
|
22
|
+
url: import.meta.env.VITE_TAIGA_MONITOR_URL, // your Taiga /beacon endpoint
|
|
23
|
+
});
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### No build step? Use the global script
|
|
27
|
+
|
|
28
|
+
For static sites or apps without a bundler, load the IIFE global and call `TaigaMonitor.init`:
|
|
29
|
+
|
|
30
|
+
```html
|
|
31
|
+
<script src="https://unpkg.com/@taiga-ai/monitor-web/dist/monitor-web.global.js"></script>
|
|
32
|
+
<script>
|
|
33
|
+
TaigaMonitor.init({ key: 'taiga_ing_…', url: 'https://…/beacon' });
|
|
34
|
+
</script>
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Configuration
|
|
38
|
+
|
|
39
|
+
`init(config)` takes one object. Only `key` and `url` are required.
|
|
40
|
+
|
|
41
|
+
| Option | Type | Default | Description |
|
|
42
|
+
| ----------------- | -------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
|
|
43
|
+
| `key` | `string` | — | Per-environment **write-only** ingest key (`taiga_ing_…`). Safe to ship in the client bundle. |
|
|
44
|
+
| `url` | `string` | — | The Taiga `/beacon` ingest endpoint for this environment. |
|
|
45
|
+
| `sampleRate` | `number` (0–1) | `1` | Fraction of sessions to instrument. Decided once per page load. |
|
|
46
|
+
| `captureVitals` | `boolean` | `true` | Collect Core Web Vitals (LCP, INP, CLS, FCP, TTFB). |
|
|
47
|
+
| `captureErrors` | `boolean` | `true` | Collect uncaught errors and unhandled promise rejections. |
|
|
48
|
+
| `captureRequests` | `boolean` | `true` | Collect client-observed API calls (`fetch` + `XHR`): status and latency. |
|
|
49
|
+
| `beforeSend` | `(event) => event \| null` | — | Transform each event before it is queued, or return `null` to drop it. Use for extra PII scrubbing. |
|
|
50
|
+
|
|
51
|
+
The `key`, `url`, and any of the flags are the _only_ configuration — there is nothing to set up inside the package itself.
|
|
52
|
+
|
|
53
|
+
## What it collects
|
|
54
|
+
|
|
55
|
+
Every measurement is sent as a small, self-describing event `{ kind, name?, value?, unit?, attributes?, occurredAt }`:
|
|
56
|
+
|
|
57
|
+
- **`web_vital`** — Core Web Vitals via `web-vitals`, with each metric's `rating` (good / needs-improvement / poor).
|
|
58
|
+
- **`error`** — uncaught errors and unhandled rejections (message and stack are length-capped; passive listeners, so your own handlers are preserved).
|
|
59
|
+
- **`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.
|
|
60
|
+
|
|
61
|
+
## Privacy
|
|
62
|
+
|
|
63
|
+
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.
|
|
64
|
+
|
|
65
|
+
The `key` 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.
|
|
66
|
+
|
|
67
|
+
## Batching & delivery
|
|
68
|
+
|
|
69
|
+
Events are batched and sent with [`navigator.sendBeacon`](https://developer.mozilla.org/docs/Web/API/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`).
|
|
70
|
+
|
|
71
|
+
## License
|
|
72
|
+
|
|
73
|
+
MIT. Bundles [`web-vitals`](https://github.com/GoogleChrome/web-vitals) (Apache-2.0); see `THIRD_PARTY_NOTICES.txt`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@taiga-ai/monitor-web",
|
|
3
|
-
"version": "0.1.0-
|
|
3
|
+
"version": "0.1.0-rc.3",
|
|
4
4
|
"description": "Taiga app monitoring — a tiny, self-contained RUM beacon (Core Web Vitals, JS errors, client-observed API health) for apps built with Taiga.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"sideEffects": false,
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
},
|
|
18
18
|
"files": [
|
|
19
19
|
"dist",
|
|
20
|
+
"README.md",
|
|
20
21
|
"THIRD_PARTY_NOTICES.txt"
|
|
21
22
|
],
|
|
22
23
|
"keywords": [
|