@lark.js/sentry 0.0.4 → 0.0.6
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 +782 -0
- package/dist/package.json.cjs +1 -1
- package/dist/package.json.js +1 -1
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,782 @@
|
|
|
1
|
+
# @lark.js/sentry
|
|
2
|
+
|
|
3
|
+
`@lark.js/sentry` is a browser monitoring and analytics SDK for page views, declarative clicks, runtime errors, resource errors, HTTP requests, performance metrics, exposure tracking, white-screen detection, offline reporting, and screen record context.
|
|
4
|
+
|
|
5
|
+
The core entry is framework agnostic. React and Vue integrations are published as dedicated subpath exports so non-framework users do not load framework dependencies.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install @lark.js/sentry
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
React and Vue are optional peer dependencies. Install them only when the matching integration is used.
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install react
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install vue
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Package Exports
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
import { init, destroy, isInitialized, pluginEnable } from "@lark.js/sentry";
|
|
27
|
+
import {
|
|
28
|
+
PerformancePlugin,
|
|
29
|
+
ScreenRecordPlugin,
|
|
30
|
+
ExposurePlugin,
|
|
31
|
+
} from "@lark.js/sentry/plugins";
|
|
32
|
+
import { ReactErrorBoundary } from "@lark.js/sentry/react";
|
|
33
|
+
import { vuePlugin } from "@lark.js/sentry/vue";
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Each public export provides ESM, CJS, and TypeScript declaration files.
|
|
37
|
+
|
|
38
|
+
## Quick Start
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
import { init, pluginEnable } from "@lark.js/sentry";
|
|
42
|
+
import {
|
|
43
|
+
PerformancePlugin,
|
|
44
|
+
ScreenRecordPlugin,
|
|
45
|
+
ExposurePlugin,
|
|
46
|
+
} from "@lark.js/sentry/plugins";
|
|
47
|
+
|
|
48
|
+
init({
|
|
49
|
+
dsn: "/api/log",
|
|
50
|
+
projectId: "frontend-app",
|
|
51
|
+
userId: "anonymous",
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
pluginEnable(PerformancePlugin);
|
|
55
|
+
pluginEnable(ScreenRecordPlugin);
|
|
56
|
+
pluginEnable(ExposurePlugin);
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`dsn` must be a non-empty string. If `dsn` is empty, initialization is rejected.
|
|
60
|
+
|
|
61
|
+
## Lifecycle APIs
|
|
62
|
+
|
|
63
|
+
### init
|
|
64
|
+
|
|
65
|
+
`init(options)` validates the input with zod, merges it with default options, writes runtime configuration, installs capture listeners, starts page-view lifecycle tracking, and initializes visitor identity when enabled.
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
import { init } from "@lark.js/sentry";
|
|
69
|
+
|
|
70
|
+
init({
|
|
71
|
+
dsn: "/api/log",
|
|
72
|
+
projectId: "checkout-web",
|
|
73
|
+
userId: "user-001",
|
|
74
|
+
enableFetch: true,
|
|
75
|
+
enableXhr: true,
|
|
76
|
+
enableClick: true,
|
|
77
|
+
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### destroy
|
|
81
|
+
|
|
82
|
+
`destroy()` cleans plugin instances, event subscriptions, browser listeners, and decorated global methods.
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
import { destroy } from "@lark.js/sentry";
|
|
86
|
+
|
|
87
|
+
destroy();
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Use it when resetting tests, unloading a micro-frontend, or dynamically disabling monitoring.
|
|
91
|
+
|
|
92
|
+
### isInitialized
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
import { init, isInitialized } from "@lark.js/sentry";
|
|
96
|
+
|
|
97
|
+
if (!isInitialized()) {
|
|
98
|
+
init({ dsn: "/api/log" });
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Configuration
|
|
103
|
+
|
|
104
|
+
`init` accepts partial options. Values not provided by the caller use SDK defaults.
|
|
105
|
+
|
|
106
|
+
| Option | Type | Default | Description |
|
|
107
|
+
| ---------------------------- | ---------------------- | --------------------------------------------------- | ------------------------------------------------------ |
|
|
108
|
+
| `dsn` | `string` | `""` | Report endpoint. Required for initialization. |
|
|
109
|
+
| `projectId` | `string` | `"unknown"` | Frontend project identifier. |
|
|
110
|
+
| `userId` | `string` | `"unknown"` | Current user identifier. |
|
|
111
|
+
| `disabled` | `boolean` | `false` | Disable the SDK. |
|
|
112
|
+
| `enableXhr` | `boolean` | `true` | Capture XMLHttpRequest requests. |
|
|
113
|
+
| `enableFetch` | `boolean` | `true` | Capture fetch requests. |
|
|
114
|
+
| `enableClick` | `boolean` | `true` | Capture declarative click events. |
|
|
115
|
+
| `enableError` | `boolean` | `true` | Capture runtime and resource errors. |
|
|
116
|
+
| `enableUnhandledRejection` | `boolean` | `true` | Capture unhandled promise rejections. |
|
|
117
|
+
| `enableHashChange` | `boolean` | `true` | Capture hash navigation. |
|
|
118
|
+
| `enableHistory` | `boolean` | `true` | Capture history navigation. |
|
|
119
|
+
| `enablePerformance` | `boolean` | `true` | Enable performance-related capture. |
|
|
120
|
+
| `enableScreenRecord` | `boolean` | `true` | Enable screen-record-related reporting. |
|
|
121
|
+
| `enableWhiteScreen` | `boolean` | `true` | Enable white-screen detection. |
|
|
122
|
+
| `enableFingerprint` | `boolean` | `false` | Enable FingerprintJS anonymous visitor identity. |
|
|
123
|
+
| `anonymousId` | `string` | `"unknown"` | SDK-generated anonymous visitor id. |
|
|
124
|
+
| `visitorId` | `string` | `"unknown"` | Backend-bound visitor id. |
|
|
125
|
+
| `useImageReport` | `boolean` | `false` | Allow image transport. |
|
|
126
|
+
| `screenRecordDurationMs` | `number` | `3000` | Rolling screen record window length. |
|
|
127
|
+
| `screenRecordEventTypes` | `EventType[]` | `[Error, Xhr, Fetch, Resource, UnhandledRejection]` | Event types that trigger screen record reporting. |
|
|
128
|
+
| `hasSkeleton` | `boolean` | `false` | Whether the page has a skeleton screen. |
|
|
129
|
+
| `rootCssSelectors` | `string[]` | `["html", "body", "#app", "#root"]` | Root selectors used by white-screen detection. |
|
|
130
|
+
| `clickThrottleDelay` | `number` | `0` | Click capture throttle delay in milliseconds. |
|
|
131
|
+
| `requestTimeoutMilliseconds` | `number` | `3000` | Request timeout in milliseconds. |
|
|
132
|
+
| `maxBreadcrumbs` | `number` | `30` | Breadcrumb capacity. |
|
|
133
|
+
| `repeatCodeError` | `boolean` | `false` | Report duplicate code errors. |
|
|
134
|
+
| `enableHttpPerformance` | `boolean` | `false` | Report successful HTTP requests as performance events. |
|
|
135
|
+
| `ignoreErrors` | `(string \| RegExp)[]` | `[]` | Runtime error ignore rules. |
|
|
136
|
+
| `excludeApis` | `(string \| RegExp)[]` | `[]` | HTTP request ignore rules. |
|
|
137
|
+
| `cacheMaxLength` | `number` | `10` | Maximum batch size. |
|
|
138
|
+
| `cacheWaitingTime` | `number` | `2000` | Batch wait time in milliseconds. |
|
|
139
|
+
| `maxQueueLength` | `number` | `200` | Maximum queued events while offline or retrying. |
|
|
140
|
+
| `retryIntervalMilliseconds` | `number` | `60000` | Server recovery probe interval. |
|
|
141
|
+
| `offlineCacheKey` | `string` | `"lark_sentry_offline_cache"` | localStorage key for offline cache. |
|
|
142
|
+
| `tracesSampleRate` | `number` | `1` | Sampling rate from 0 to 1. |
|
|
143
|
+
| `onBeforePushBreadcrumb` | `function` | `undefined` | Hook before storing a breadcrumb. |
|
|
144
|
+
| `onBeforeReportData` | `function` | `undefined` | Hook before one event enters Reporter queue. |
|
|
145
|
+
| `beforePushEventList` | `function` | `undefined` | Hook before a batch enters transport. |
|
|
146
|
+
| `afterSendData` | `function` | `undefined` | Hook after a batch enters transport successfully. |
|
|
147
|
+
| `handleHttpError` | `function` | `undefined` | Custom HTTP error callback. |
|
|
148
|
+
|
|
149
|
+
Example production configuration:
|
|
150
|
+
|
|
151
|
+
```ts
|
|
152
|
+
import { init } from "@lark.js/sentry";
|
|
153
|
+
|
|
154
|
+
init({
|
|
155
|
+
dsn: "https://example.com/api/log",
|
|
156
|
+
projectId: "production-web",
|
|
157
|
+
userId: "unknown",
|
|
158
|
+
enableFingerprint: true,
|
|
159
|
+
enableHttpPerformance: true,
|
|
160
|
+
tracesSampleRate: 1,
|
|
161
|
+
excludeApis: ["https://example.com/api/log"],
|
|
162
|
+
ignoreErrors: [/ResizeObserver loop limit exceeded/],
|
|
163
|
+
});
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Report Data
|
|
167
|
+
|
|
168
|
+
Reporter sends `IReportData` objects to the configured `dsn`.
|
|
169
|
+
|
|
170
|
+
| Field | Description |
|
|
171
|
+
| ------------ | ------------------------------------------ |
|
|
172
|
+
| `id` | Reporter instance id. |
|
|
173
|
+
| `type` | Event type. |
|
|
174
|
+
| `name` | Event name. |
|
|
175
|
+
| `message` | Event message. |
|
|
176
|
+
| `status` | `OK` or `Error`. |
|
|
177
|
+
| `time` | Formatted time. |
|
|
178
|
+
| `timestamp` | Numeric timestamp. |
|
|
179
|
+
| `url` | Current page URL. |
|
|
180
|
+
| `userId` | User identifier. |
|
|
181
|
+
| `projectId` | Project identifier. |
|
|
182
|
+
| `sdkVersion` | SDK version. |
|
|
183
|
+
| `deviceInfo` | Device, browser, OS, and fingerprint data. |
|
|
184
|
+
| `payload` | Original event payload. |
|
|
185
|
+
|
|
186
|
+
## Event Types
|
|
187
|
+
|
|
188
|
+
The SDK can report the following event categories:
|
|
189
|
+
|
|
190
|
+
| Type | Description |
|
|
191
|
+
| -------------------------- | ------------------------------- |
|
|
192
|
+
| `XMLHttpRequest` | XHR request. |
|
|
193
|
+
| `fetch` | fetch request. |
|
|
194
|
+
| `Click` | Declarative click. |
|
|
195
|
+
| `Event hashchange` | Hash navigation. |
|
|
196
|
+
| `History` | History navigation. |
|
|
197
|
+
| `Resource` | Static resource load failure. |
|
|
198
|
+
| `Event unhandledrejection` | Unhandled promise rejection. |
|
|
199
|
+
| `Error` | JavaScript runtime error. |
|
|
200
|
+
| `Vue` | Vue error. |
|
|
201
|
+
| `React` | React error. |
|
|
202
|
+
| `Performance` | Performance metric. |
|
|
203
|
+
| `ScreenRecord` | Screen record payload. |
|
|
204
|
+
| `Exposure` | Exposure duration event. |
|
|
205
|
+
| `WhiteScreen` | White-screen event. |
|
|
206
|
+
| `Custom` | Custom business event. |
|
|
207
|
+
| `PV` | Page view and dwell-time event. |
|
|
208
|
+
|
|
209
|
+
## Error Capture
|
|
210
|
+
|
|
211
|
+
The SDK captures:
|
|
212
|
+
|
|
213
|
+
- `window` `error` events.
|
|
214
|
+
- Static resource load errors.
|
|
215
|
+
- `console.error` error objects or error text.
|
|
216
|
+
- Unhandled promise rejections.
|
|
217
|
+
- React ErrorBoundary errors.
|
|
218
|
+
- Vue `app.config.errorHandler` errors.
|
|
219
|
+
|
|
220
|
+
Duplicate code errors are deduplicated by default. Enable duplicate reporting with:
|
|
221
|
+
|
|
222
|
+
```ts
|
|
223
|
+
init({
|
|
224
|
+
dsn: "/api/log",
|
|
225
|
+
repeatCodeError: true,
|
|
226
|
+
});
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Ignore known noise:
|
|
230
|
+
|
|
231
|
+
```ts
|
|
232
|
+
init({
|
|
233
|
+
dsn: "/api/log",
|
|
234
|
+
ignoreErrors: ["Script error.", /ResizeObserver loop limit exceeded/],
|
|
235
|
+
});
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
## HTTP Capture
|
|
239
|
+
|
|
240
|
+
The SDK decorates `XMLHttpRequest.prototype.open`, `XMLHttpRequest.prototype.send`, and `globalThis.fetch`. It captures method, URL, status code, elapsed time, request data, response data, and `Server-Timing`.
|
|
241
|
+
|
|
242
|
+
Status classification:
|
|
243
|
+
|
|
244
|
+
| Status code | SDK status |
|
|
245
|
+
| ------------ | ---------- |
|
|
246
|
+
| 100 to 399 | `OK` |
|
|
247
|
+
| 400 to 599 | `Error` |
|
|
248
|
+
| Other values | `Error` |
|
|
249
|
+
|
|
250
|
+
Exclude report endpoints or health checks:
|
|
251
|
+
|
|
252
|
+
```ts
|
|
253
|
+
init({
|
|
254
|
+
dsn: "/api/log",
|
|
255
|
+
excludeApis: ["/api/log", /\/health$/],
|
|
256
|
+
});
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Report successful HTTP requests as performance events:
|
|
260
|
+
|
|
261
|
+
```ts
|
|
262
|
+
init({
|
|
263
|
+
dsn: "/api/log",
|
|
264
|
+
enableHttpPerformance: true,
|
|
265
|
+
});
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
## Page Views and Dwell Time
|
|
269
|
+
|
|
270
|
+
The SDK reports an initial `PageLoad` PV event during initialization.
|
|
271
|
+
|
|
272
|
+
On hash or history route changes, it:
|
|
273
|
+
|
|
274
|
+
- Deduplicates unchanged URLs.
|
|
275
|
+
- Reports `PageDwell` for the previous page.
|
|
276
|
+
- Reports a new PV for the next page.
|
|
277
|
+
- Flushes current dwell time on `beforeunload` when possible.
|
|
278
|
+
|
|
279
|
+
Dwell time less than or equal to 100 ms is ignored to reduce noise.
|
|
280
|
+
|
|
281
|
+
Manual page-view reporting:
|
|
282
|
+
|
|
283
|
+
```ts
|
|
284
|
+
import { tracePageView } from "@lark.js/sentry";
|
|
285
|
+
|
|
286
|
+
tracePageView({
|
|
287
|
+
name: "ProductDetail",
|
|
288
|
+
message: location.href,
|
|
289
|
+
extra: {
|
|
290
|
+
productId: "sku-001",
|
|
291
|
+
},
|
|
292
|
+
});
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
## Declarative Clicks
|
|
296
|
+
|
|
297
|
+
Declarative click tracking uses `s-lark-*` attributes. Plain clicks are not reported unless the clicked element or one of its composed path ancestors has a tracking attribute.
|
|
298
|
+
|
|
299
|
+
```html
|
|
300
|
+
<section s-lark-view="profile-card" s-lark-src="home">
|
|
301
|
+
<button s-lark-ev="save-profile" s-lark-msg="Save">Save</button>
|
|
302
|
+
</section>
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
Reserved attributes:
|
|
306
|
+
|
|
307
|
+
| Attribute | Description |
|
|
308
|
+
| ------------- | ------------------------------ |
|
|
309
|
+
| `s-lark-ev` | Explicit event ID. |
|
|
310
|
+
| `s-lark-msg` | Human-readable message. |
|
|
311
|
+
| `s-lark-view` | View ID and event ID fallback. |
|
|
312
|
+
|
|
313
|
+
Custom `s-lark-*` attributes become `params`.
|
|
314
|
+
|
|
315
|
+
```html
|
|
316
|
+
<a
|
|
317
|
+
s-lark-ev="open-banner"
|
|
318
|
+
s-lark-msg="Open campaign banner"
|
|
319
|
+
s-lark-campaign="spring"
|
|
320
|
+
s-lark-rank="1"
|
|
321
|
+
>
|
|
322
|
+
Campaign
|
|
323
|
+
</a>
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
The reported click payload (`DeclarativeClickData`) includes:
|
|
327
|
+
|
|
328
|
+
| Field | Type | Description |
|
|
329
|
+
| ---------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
|
|
330
|
+
| `ev` | `string` | Event ID (from `s-lark-ev`, `title`, `s-lark-view`, or tag). |
|
|
331
|
+
| `msg` | `string` | Human-readable message (from `s-lark-msg`, text, `aria-label`, or tag). |
|
|
332
|
+
| `triggerPageUrl` | `string` | Current page URL (`location.href`). |
|
|
333
|
+
| `x` | `number` | Click X coordinate (element offset + scroll offset). |
|
|
334
|
+
| `y` | `number` | Click Y coordinate (element offset + scroll offset). |
|
|
335
|
+
| `params` | `Readonly<Record<string, string \| null>>` | Custom `s-lark-*` attributes (excluding reserved keys). |
|
|
336
|
+
| `elementPath` | `string` | XPath-like path from element to body (max 128 characters). |
|
|
337
|
+
| `triggerTime` | `number` | `Date.now()` at click time. |
|
|
338
|
+
|
|
339
|
+
## White-Screen Detection
|
|
340
|
+
|
|
341
|
+
White-screen detection samples viewport points after the page is ready and checks whether those points still resolve to configured root elements.
|
|
342
|
+
|
|
343
|
+
Default root selectors:
|
|
344
|
+
|
|
345
|
+
```ts
|
|
346
|
+
["html", "body", "#app", "#root"];
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
```ts
|
|
350
|
+
init({
|
|
351
|
+
dsn: "/api/log",
|
|
352
|
+
enableWhiteScreen: true,
|
|
353
|
+
rootCssSelectors: ["html", "body", "#app"],
|
|
354
|
+
});
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
Skeleton-screen pages can enable skeleton mode:
|
|
358
|
+
|
|
359
|
+
```ts
|
|
360
|
+
init({
|
|
361
|
+
dsn: "/api/log",
|
|
362
|
+
enableWhiteScreen: true,
|
|
363
|
+
hasSkeleton: true,
|
|
364
|
+
});
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
## Visitor Identity
|
|
368
|
+
|
|
369
|
+
The SDK tracks three identity values:
|
|
370
|
+
|
|
371
|
+
| Field | Description |
|
|
372
|
+
| ------------- | ------------------------------------------------------------------- |
|
|
373
|
+
| `anonymousId` | Anonymous visitor id generated by FingerprintJS and stored locally. |
|
|
374
|
+
| `visitorId` | Backend-bound visitor id. |
|
|
375
|
+
| `userId` | Current logged-in user id. |
|
|
376
|
+
|
|
377
|
+
Enable FingerprintJS:
|
|
378
|
+
|
|
379
|
+
```ts
|
|
380
|
+
import { getIdentity, init } from "@lark.js/sentry";
|
|
381
|
+
|
|
382
|
+
init({
|
|
383
|
+
dsn: "/api/log",
|
|
384
|
+
enableFingerprint: true,
|
|
385
|
+
});
|
|
386
|
+
|
|
387
|
+
console.log(getIdentity());
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
Update user and visitor ids:
|
|
391
|
+
|
|
392
|
+
```ts
|
|
393
|
+
import { setUserId, setVisitorId } from "@lark.js/sentry";
|
|
394
|
+
|
|
395
|
+
setUserId("user-001");
|
|
396
|
+
setVisitorId("visitor-001");
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
Read identity:
|
|
400
|
+
|
|
401
|
+
```ts
|
|
402
|
+
import { getIdentity } from "@lark.js/sentry";
|
|
403
|
+
|
|
404
|
+
const identity = getIdentity();
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
`anonymousId` is stored in localStorage with the key `lark_sentry_anonymous_id`.
|
|
408
|
+
|
|
409
|
+
## Reporter
|
|
410
|
+
|
|
411
|
+
Reporter is the unified data outlet. It transforms captured payloads into report data and sends batches to `dsn`.
|
|
412
|
+
|
|
413
|
+
Reporter behavior:
|
|
414
|
+
|
|
415
|
+
- Batches events.
|
|
416
|
+
- Applies sampling through `tracesSampleRate`.
|
|
417
|
+
- Persists offline events to localStorage.
|
|
418
|
+
- Flushes cached events after network recovery.
|
|
419
|
+
- Probes server recovery with HEAD requests after failed fetch reports.
|
|
420
|
+
- Avoids concurrent flush races with an `isFlushing` guard.
|
|
421
|
+
- Supports `sendBeacon`, image, and fetch transports.
|
|
422
|
+
|
|
423
|
+
Transport priority:
|
|
424
|
+
|
|
425
|
+
1. Use `navigator.sendBeacon` for batches up to 60 KB.
|
|
426
|
+
2. Use image transport when `useImageReport` is true and the batch is up to 2 KB.
|
|
427
|
+
3. Use fetch POST as the fallback.
|
|
428
|
+
|
|
429
|
+
Flush offline cache manually:
|
|
430
|
+
|
|
431
|
+
```ts
|
|
432
|
+
import { sendLocal } from "@lark.js/sentry";
|
|
433
|
+
|
|
434
|
+
await sendLocal();
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
## Reporter Hooks
|
|
438
|
+
|
|
439
|
+
Register hooks after initialization or provide equivalent hooks in `init` options.
|
|
440
|
+
|
|
441
|
+
```ts
|
|
442
|
+
import {
|
|
443
|
+
afterSendData,
|
|
444
|
+
beforePushEventList,
|
|
445
|
+
beforeSendData,
|
|
446
|
+
} from "@lark.js/sentry";
|
|
447
|
+
|
|
448
|
+
beforeSendData((data) => {
|
|
449
|
+
if (data.type === "Click") {
|
|
450
|
+
return false;
|
|
451
|
+
}
|
|
452
|
+
return data;
|
|
453
|
+
});
|
|
454
|
+
|
|
455
|
+
beforePushEventList((eventList) => {
|
|
456
|
+
return eventList.filter((item) => item.status !== "OK");
|
|
457
|
+
});
|
|
458
|
+
|
|
459
|
+
afterSendData((eventList) => {
|
|
460
|
+
console.log("reported", eventList.length);
|
|
461
|
+
});
|
|
462
|
+
```
|
|
463
|
+
|
|
464
|
+
Equivalent initialization form:
|
|
465
|
+
|
|
466
|
+
```ts
|
|
467
|
+
init({
|
|
468
|
+
dsn: "/api/log",
|
|
469
|
+
onBeforeReportData(data) {
|
|
470
|
+
return data;
|
|
471
|
+
},
|
|
472
|
+
beforePushEventList(eventList) {
|
|
473
|
+
return eventList;
|
|
474
|
+
},
|
|
475
|
+
afterSendData(eventList) {
|
|
476
|
+
console.log(eventList.length);
|
|
477
|
+
},
|
|
478
|
+
});
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
## Manual APIs
|
|
482
|
+
|
|
483
|
+
### traceError
|
|
484
|
+
|
|
485
|
+
```ts
|
|
486
|
+
import { traceError } from "@lark.js/sentry";
|
|
487
|
+
|
|
488
|
+
try {
|
|
489
|
+
throw new Error("Unexpected state");
|
|
490
|
+
} catch (error) {
|
|
491
|
+
traceError(error);
|
|
492
|
+
}
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
### tracePerformance
|
|
496
|
+
|
|
497
|
+
```ts
|
|
498
|
+
import { tracePerformance } from "@lark.js/sentry";
|
|
499
|
+
|
|
500
|
+
tracePerformance({
|
|
501
|
+
name: "SearchLatency",
|
|
502
|
+
message: "/api/search",
|
|
503
|
+
value: 128,
|
|
504
|
+
});
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
### traceCustomEvent
|
|
508
|
+
|
|
509
|
+
```ts
|
|
510
|
+
import { traceCustomEvent } from "@lark.js/sentry";
|
|
511
|
+
|
|
512
|
+
traceCustomEvent({
|
|
513
|
+
name: "CheckoutSuccess",
|
|
514
|
+
message: "Submit order",
|
|
515
|
+
extra: {
|
|
516
|
+
orderId: "order-001",
|
|
517
|
+
},
|
|
518
|
+
});
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
### tracePageView
|
|
522
|
+
|
|
523
|
+
```ts
|
|
524
|
+
import { tracePageView } from "@lark.js/sentry";
|
|
525
|
+
|
|
526
|
+
tracePageView({
|
|
527
|
+
name: "ManualPageView",
|
|
528
|
+
message: location.href,
|
|
529
|
+
});
|
|
530
|
+
```
|
|
531
|
+
|
|
532
|
+
### getBaseInfo and getUserId
|
|
533
|
+
|
|
534
|
+
```ts
|
|
535
|
+
import { getBaseInfo, getUserId } from "@lark.js/sentry";
|
|
536
|
+
|
|
537
|
+
const baseInfo = getBaseInfo();
|
|
538
|
+
const userId = getUserId();
|
|
539
|
+
```
|
|
540
|
+
|
|
541
|
+
### getIPs
|
|
542
|
+
|
|
543
|
+
`getIPs` attempts to collect WebRTC ICE candidate IP values in browsers that support the required APIs. It returns an empty array when unsupported.
|
|
544
|
+
|
|
545
|
+
```ts
|
|
546
|
+
import { getIPs } from "@lark.js/sentry";
|
|
547
|
+
|
|
548
|
+
const ips = await getIPs();
|
|
549
|
+
```
|
|
550
|
+
|
|
551
|
+
## Plugin System
|
|
552
|
+
|
|
553
|
+
Plugins extend the SDK without coupling optional capabilities to the core entry. A plugin class extends `SentryPlugin`, implements `init`, and can implement `destroy` for cleanup.
|
|
554
|
+
|
|
555
|
+
```ts
|
|
556
|
+
import { pluginEnable } from "@lark.js/sentry";
|
|
557
|
+
import { PerformancePlugin } from "@lark.js/sentry/plugins";
|
|
558
|
+
|
|
559
|
+
const plugin = pluginEnable(PerformancePlugin);
|
|
560
|
+
```
|
|
561
|
+
|
|
562
|
+
Enabled plugins are stored in the plugin registry. `destroy()` calls each plugin's `destroy()` method when available.
|
|
563
|
+
|
|
564
|
+
## PerformancePlugin
|
|
565
|
+
|
|
566
|
+
```ts
|
|
567
|
+
import { pluginEnable } from "@lark.js/sentry";
|
|
568
|
+
import { PerformancePlugin } from "@lark.js/sentry/plugins";
|
|
569
|
+
|
|
570
|
+
pluginEnable(PerformancePlugin);
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
The plugin collects:
|
|
574
|
+
|
|
575
|
+
- Web Vitals.
|
|
576
|
+
- Navigation Timing page-load metrics.
|
|
577
|
+
- Resource Timing metrics.
|
|
578
|
+
- Long Task entries.
|
|
579
|
+
- Fallback resource-element timing for dynamically inserted resources.
|
|
580
|
+
- `performance.measureUserAgentSpecificMemory` when supported.
|
|
581
|
+
|
|
582
|
+
Unsupported browser capabilities are skipped safely.
|
|
583
|
+
|
|
584
|
+
## ScreenRecordPlugin
|
|
585
|
+
|
|
586
|
+
```ts
|
|
587
|
+
import { pluginEnable } from "@lark.js/sentry";
|
|
588
|
+
import { ScreenRecordPlugin, unzipScreenRecord } from "@lark.js/sentry/plugins";
|
|
589
|
+
|
|
590
|
+
pluginEnable(ScreenRecordPlugin);
|
|
591
|
+
|
|
592
|
+
pluginEnable(ScreenRecordPlugin, {
|
|
593
|
+
durationMs: 5000,
|
|
594
|
+
});
|
|
595
|
+
```
|
|
596
|
+
|
|
597
|
+
Screen recording is based on rrweb. The plugin keeps a rolling record window. When selected error or network events occur, the recent record window is reported as a `ScreenRecord` event.
|
|
598
|
+
|
|
599
|
+
Decode a record payload:
|
|
600
|
+
|
|
601
|
+
```ts
|
|
602
|
+
const events = unzipScreenRecord(recordPayload);
|
|
603
|
+
```
|
|
604
|
+
|
|
605
|
+
## ExposurePlugin
|
|
606
|
+
|
|
607
|
+
```ts
|
|
608
|
+
import { pluginEnable } from "@lark.js/sentry";
|
|
609
|
+
import { ExposurePlugin } from "@lark.js/sentry/plugins";
|
|
610
|
+
|
|
611
|
+
const exposure = pluginEnable(ExposurePlugin);
|
|
612
|
+
```
|
|
613
|
+
|
|
614
|
+
Observe one element:
|
|
615
|
+
|
|
616
|
+
```ts
|
|
617
|
+
const element = document.querySelector("#banner");
|
|
618
|
+
|
|
619
|
+
if (element) {
|
|
620
|
+
exposure.observe({
|
|
621
|
+
target: element,
|
|
622
|
+
threshold: 0.5,
|
|
623
|
+
params: {
|
|
624
|
+
bannerId: "spring-001",
|
|
625
|
+
},
|
|
626
|
+
});
|
|
627
|
+
}
|
|
628
|
+
```
|
|
629
|
+
|
|
630
|
+
Observe multiple elements:
|
|
631
|
+
|
|
632
|
+
```ts
|
|
633
|
+
const first = document.querySelector("#first");
|
|
634
|
+
const second = document.querySelector("#second");
|
|
635
|
+
|
|
636
|
+
if (first && second) {
|
|
637
|
+
exposure.observe([
|
|
638
|
+
{
|
|
639
|
+
target: first,
|
|
640
|
+
threshold: 0.5,
|
|
641
|
+
params: { position: "first" },
|
|
642
|
+
},
|
|
643
|
+
{
|
|
644
|
+
target: second,
|
|
645
|
+
threshold: 0.75,
|
|
646
|
+
params: { position: "second" },
|
|
647
|
+
},
|
|
648
|
+
]);
|
|
649
|
+
}
|
|
650
|
+
```
|
|
651
|
+
|
|
652
|
+
Cancel observation:
|
|
653
|
+
|
|
654
|
+
```ts
|
|
655
|
+
exposure.unobserve(element);
|
|
656
|
+
exposure.unobserve([first, second]);
|
|
657
|
+
```
|
|
658
|
+
|
|
659
|
+
Exposure events are reported when an observed element leaves the viewport after becoming visible. The payload contains threshold, observe time, show time, show end time, duration, and user params.
|
|
660
|
+
|
|
661
|
+
## React Integration
|
|
662
|
+
|
|
663
|
+
```tsx
|
|
664
|
+
import { init } from "@lark.js/sentry";
|
|
665
|
+
import { ReactErrorBoundary } from "@lark.js/sentry/react";
|
|
666
|
+
|
|
667
|
+
init({ dsn: "/api/log" });
|
|
668
|
+
|
|
669
|
+
export function App() {
|
|
670
|
+
return (
|
|
671
|
+
<ReactErrorBoundary fallback={<div>Something went wrong</div>}>
|
|
672
|
+
<Page />
|
|
673
|
+
</ReactErrorBoundary>
|
|
674
|
+
);
|
|
675
|
+
}
|
|
676
|
+
```
|
|
677
|
+
|
|
678
|
+
`fallback` can also be a function:
|
|
679
|
+
|
|
680
|
+
```tsx
|
|
681
|
+
<ReactErrorBoundary
|
|
682
|
+
fallback={(error, errorInfo) => (
|
|
683
|
+
<div>
|
|
684
|
+
{error.message}
|
|
685
|
+
{errorInfo.componentStack}
|
|
686
|
+
</div>
|
|
687
|
+
)}
|
|
688
|
+
>
|
|
689
|
+
<Page />
|
|
690
|
+
</ReactErrorBoundary>
|
|
691
|
+
```
|
|
692
|
+
|
|
693
|
+
The boundary reports `React` events with the error, stack, and React `ErrorInfo`.
|
|
694
|
+
|
|
695
|
+
## Vue 3 Integration
|
|
696
|
+
|
|
697
|
+
```ts
|
|
698
|
+
import { createApp } from "vue";
|
|
699
|
+
import { vuePlugin } from "@lark.js/sentry/vue";
|
|
700
|
+
import App from "./app.vue";
|
|
701
|
+
|
|
702
|
+
const app = createApp(App);
|
|
703
|
+
|
|
704
|
+
app.use(vuePlugin, {
|
|
705
|
+
dsn: "/api/log",
|
|
706
|
+
projectId: "vue-app",
|
|
707
|
+
});
|
|
708
|
+
|
|
709
|
+
app.mount("#app");
|
|
710
|
+
```
|
|
711
|
+
|
|
712
|
+
The plugin installs `app.config.errorHandler`, reports `Vue` events, and then calls the previous error handler if one existed.
|
|
713
|
+
|
|
714
|
+
## Vite Dev-Server Plugin
|
|
715
|
+
|
|
716
|
+
The SDK provides a Vite plugin that creates a mock report endpoint during development, writing reported data to log files instead of sending it to a real server.
|
|
717
|
+
|
|
718
|
+
```ts
|
|
719
|
+
// vite.config.ts
|
|
720
|
+
import { defineConfig } from "vite";
|
|
721
|
+
import { sentryPlugin } from "@lark.js/sentry/vite";
|
|
722
|
+
|
|
723
|
+
export default defineConfig({
|
|
724
|
+
// `url` should equals to @lark.js/sentry `init({ dsn: "/api/log" })` config `dsn`
|
|
725
|
+
plugins: [sentryPlugin({ url: "/api/log" })],
|
|
726
|
+
});
|
|
727
|
+
```
|
|
728
|
+
|
|
729
|
+
### Available Exports
|
|
730
|
+
|
|
731
|
+
| Export | Vite Version | Description |
|
|
732
|
+
| --------------- | ------------ | --------------------------------------- |
|
|
733
|
+
| `sentryPlugin` | Vite 6/8 | Default export. For current Vite. |
|
|
734
|
+
| `sentryPlugin7` | Vite 7 | For projects using Vite 7 specifically. |
|
|
735
|
+
|
|
736
|
+
### Options
|
|
737
|
+
|
|
738
|
+
| Option | Type | Default | Description |
|
|
739
|
+
| ------ | -------- | ----------- | ---------------------------------------- |
|
|
740
|
+
| `url` | `string` | `"/sentry"` | The URL path to intercept POST requests. |
|
|
741
|
+
|
|
742
|
+
The plugin creates a `logs/` directory in `process.cwd()`, writes a timestamped log file (`sentry_YYYYMMDDHHMMSS.log`), parses each request body as JSON, and returns `{ code: 0, message: "success" }`.
|
|
743
|
+
|
|
744
|
+
## Browser Compatibility
|
|
745
|
+
|
|
746
|
+
- `sendBeacon` is preferred for small batches.
|
|
747
|
+
- Image and fetch transports are used as fallbacks.
|
|
748
|
+
- `PerformanceObserver` powers Web Vitals, long task, and resource timing when available.
|
|
749
|
+
- `MutationObserver` is used as a fallback for dynamically inserted resources.
|
|
750
|
+
- `IntersectionObserver` is required by `ExposurePlugin`.
|
|
751
|
+
- `performance.measureUserAgentSpecificMemory` is optional.
|
|
752
|
+
- `@rrweb/record` is used only by the screen record plugin.
|
|
753
|
+
|
|
754
|
+
## Quality Gates
|
|
755
|
+
|
|
756
|
+
```bash
|
|
757
|
+
pnpm exec eslint ./sentry --quiet --ext .js,.jsx,.ts,.tsx
|
|
758
|
+
pnpm --filter @lark.js/sentry typecheck
|
|
759
|
+
pnpm --filter @lark.js/sentry test
|
|
760
|
+
pnpm test:coverage
|
|
761
|
+
pnpm build
|
|
762
|
+
```
|
|
763
|
+
|
|
764
|
+
Coverage thresholds are 70 for lines, functions, branches, and statements.
|
|
765
|
+
|
|
766
|
+
## Build and Publish
|
|
767
|
+
|
|
768
|
+
```bash
|
|
769
|
+
pnpm build
|
|
770
|
+
pnpm build:tsup
|
|
771
|
+
python3 publish.py --dry-run
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
Publish after npm login:
|
|
775
|
+
|
|
776
|
+
```bash
|
|
777
|
+
python3 publish.py --publish --registry https://registry.npmjs.org/
|
|
778
|
+
```
|
|
779
|
+
|
|
780
|
+
The publish script validates lint, typecheck, tests, coverage, build output, ESM imports, CJS requires, package exports, absence of sourcemaps, absence of `dist/node_modules`, and absence of package tarball residue.
|
|
781
|
+
|
|
782
|
+
Published npm files are limited to `dist` and package metadata. Source files, tests, sourcemaps, and temporary tarballs are not published.
|
package/dist/package.json.cjs
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e="0.0.
|
|
1
|
+
"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e="0.0.6",r={version:e};exports.default=r,exports.version=e;
|
package/dist/package.json.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
var a="0.0.
|
|
1
|
+
var a="0.0.6",e={version:a};export{e as default,a as version};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lark.js/sentry",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.6",
|
|
4
4
|
"description": "sentry sdk",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"keywords": [
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
"types": "./dist/index.d.ts",
|
|
15
15
|
"files": [
|
|
16
16
|
"dist",
|
|
17
|
-
"
|
|
17
|
+
"./README.md"
|
|
18
18
|
],
|
|
19
19
|
"exports": {
|
|
20
20
|
".": {
|