@starko-one/sdk 0.0.0-stage → 0.1.0-beta.1
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/CHANGELOG.md +248 -0
- package/LICENSE +17 -0
- package/NOTICE +58 -0
- package/README.md +81 -2
- package/dist/api-BAFm4Lxj.d.ts +558 -0
- package/dist/api-DNrctwJu.d.cts +558 -0
- package/dist/browser/index.cjs +168 -0
- package/dist/browser/index.d.cts +131 -0
- package/dist/browser/index.d.ts +131 -0
- package/dist/browser/index.js +7 -0
- package/dist/build/rollup.cjs +22 -0
- package/dist/build/rollup.d.cts +34 -0
- package/dist/build/rollup.d.ts +34 -0
- package/dist/build/rollup.js +3 -0
- package/dist/build/vite.cjs +51 -0
- package/dist/build/vite.d.cts +23 -0
- package/dist/build/vite.d.ts +23 -0
- package/dist/build/vite.js +46 -0
- package/dist/build/webpack.cjs +18 -0
- package/dist/build/webpack.d.cts +39 -0
- package/dist/build/webpack.d.ts +39 -0
- package/dist/build/webpack.js +3 -0
- package/dist/chunk-2PM4FRM5.cjs +431 -0
- package/dist/chunk-335HNCOJ.js +249 -0
- package/dist/chunk-3AW5B2WW.js +115 -0
- package/dist/chunk-3R5TQAWD.js +216 -0
- package/dist/chunk-6H5MOPTQ.cjs +1230 -0
- package/dist/chunk-7TKNT3QJ.cjs +2487 -0
- package/dist/chunk-A4WLNFMU.cjs +220 -0
- package/dist/chunk-ALYFFOPR.cjs +134 -0
- package/dist/chunk-BVVFVRMO.js +1113 -0
- package/dist/chunk-CIHNKN62.cjs +15 -0
- package/dist/chunk-CMGCH6HD.js +1212 -0
- package/dist/chunk-D6QAPQ7L.cjs +56 -0
- package/dist/chunk-DUO5V6WZ.js +213 -0
- package/dist/chunk-EC2WZ6PG.js +90 -0
- package/dist/chunk-EFURLFJT.cjs +187 -0
- package/dist/chunk-EROUORMY.js +53 -0
- package/dist/chunk-LXBXFOAP.cjs +96 -0
- package/dist/chunk-MF6SA6DB.js +563 -0
- package/dist/chunk-N5R6ORIB.js +413 -0
- package/dist/chunk-N6R6BWHK.cjs +142 -0
- package/dist/chunk-QAGGN2T7.cjs +225 -0
- package/dist/chunk-QV4HRIDD.cjs +659 -0
- package/dist/chunk-TKNDYQB3.cjs +583 -0
- package/dist/chunk-UI5YC4TH.js +131 -0
- package/dist/chunk-VEHZYLK6.cjs +1151 -0
- package/dist/chunk-VNCWOGTI.js +12 -0
- package/dist/chunk-VWNIOGE6.js +180 -0
- package/dist/chunk-WDKRKGYF.js +608 -0
- package/dist/chunk-XOZIXBUK.js +2462 -0
- package/dist/chunk-ZS3K3SDR.cjs +258 -0
- package/dist/cli/index.cjs +2780 -0
- package/dist/common-DLFAqL2d.d.cts +36 -0
- package/dist/common-DbSXkaw6.d.ts +36 -0
- package/dist/dedupe-Bh5riD8Z.d.cts +13 -0
- package/dist/dedupe-DoYiSx-9.d.ts +13 -0
- package/dist/handler-BcnsnvhF.d.cts +82 -0
- package/dist/handler-qHzilC9T.d.ts +82 -0
- package/dist/index.cjs +309 -0
- package/dist/index.d.cts +187 -0
- package/dist/index.d.ts +187 -0
- package/dist/index.js +4 -0
- package/dist/next/client.cjs +113 -0
- package/dist/next/client.d.cts +26 -0
- package/dist/next/client.d.ts +26 -0
- package/dist/next/client.js +41 -0
- package/dist/next/config.cjs +277 -0
- package/dist/next/config.d.cts +193 -0
- package/dist/next/config.d.ts +193 -0
- package/dist/next/config.js +263 -0
- package/dist/next/index.cjs +148 -0
- package/dist/next/index.d.cts +32 -0
- package/dist/next/index.d.ts +32 -0
- package/dist/next/index.js +59 -0
- package/dist/node/index.cjs +257 -0
- package/dist/node/index.d.cts +145 -0
- package/dist/node/index.d.ts +145 -0
- package/dist/node/index.js +83 -0
- package/dist/options-BUhWuWJX.d.cts +79 -0
- package/dist/options-BUhWuWJX.d.ts +79 -0
- package/dist/react/index.cjs +107 -0
- package/dist/react/index.d.cts +84 -0
- package/dist/react/index.d.ts +84 -0
- package/dist/react/index.js +103 -0
- package/dist/scope-D1ouJm2h.d.cts +628 -0
- package/dist/scope-D1ouJm2h.d.ts +628 -0
- package/dist/server-edge-7624N3WF.cjs +51 -0
- package/dist/server-edge-BEEXWL7T.js +48 -0
- package/dist/server-node-ET4LIPEC.cjs +27 -0
- package/dist/server-node-TQUVMZUC.js +24 -0
- package/dist/session-C_WzbEN2.d.cts +4 -0
- package/dist/session-C_WzbEN2.d.ts +4 -0
- package/dist/session-propagation-Pr0Zb9Zn.d.cts +30 -0
- package/dist/session-propagation-RM5py1bp.d.ts +30 -0
- package/dist/starko.min.js +6 -0
- package/docs/browser.md +386 -0
- package/docs/configuration.md +310 -0
- package/docs/nextjs.md +488 -0
- package/docs/node.md +427 -0
- package/docs/other-backends.md +232 -0
- package/docs/privacy.md +112 -0
- package/docs/react.md +187 -0
- package/docs/source-maps.md +482 -0
- package/docs/troubleshooting.md +263 -0
- package/docs/widget.md +84 -0
- package/docs/wire-format.md +547 -0
- package/package.json +191 -4
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
Start every investigation with `debug: true` in `init` (script tag:
|
|
4
|
+
`data-debug`). The SDK then logs to the console, every line starting with
|
|
5
|
+
`[starko]`: `started` once it runs, `dropped <why>` for each event it drops,
|
|
6
|
+
and the status of each request it sends. Remove `debug` again in production.
|
|
7
|
+
|
|
8
|
+
Some messages are printed even without `debug`: events dropped by a rate
|
|
9
|
+
limit (`events dropped by …`, at most once a minute per limit), and, once
|
|
10
|
+
each, other dropped events (`events dropped: …`), a host that redirects, a
|
|
11
|
+
secret key the ingest API refused, and, on the Edge runtime, a server user
|
|
12
|
+
set outside a request.
|
|
13
|
+
|
|
14
|
+
## 1. Nothing arrives
|
|
15
|
+
|
|
16
|
+
Work down this list:
|
|
17
|
+
|
|
18
|
+
1. **Did the SDK start?** With `debug: true`, look for `[starko] started`.
|
|
19
|
+
`[starko] no workspaceKey` means the key is missing. `init` must run
|
|
20
|
+
before the error happens: errors thrown before it are not captured.
|
|
21
|
+
2. **Is the workspace key right?** It is the workspace id shown in Starko
|
|
22
|
+
under Settings. A wrong key gets `401` with reason `unknown_workspace`;
|
|
23
|
+
the SDK then stops sending for the rest of the page load or process
|
|
24
|
+
(`[starko] 401 unknown_workspace: off`).
|
|
25
|
+
3. **Is the secret key right?** (servers with `apiKey`) A wrong, revoked or
|
|
26
|
+
malformed `apiKey` gets `401` with reason `invalid`. The SDK drops each
|
|
27
|
+
batch it was refused for, without retrying, and prints
|
|
28
|
+
``[starko] 401: secret key refused, events dropped. Check `apiKey`.``
|
|
29
|
+
once, even without `debug`. Later batches are sent and refused the same
|
|
30
|
+
way. Fix `apiKey`, or remove it: without it, events are accepted like a
|
|
31
|
+
browser's.
|
|
32
|
+
4. **Is error tracking enabled for the workspace?** If not, the remote
|
|
33
|
+
config says so (`[starko] config: disabled`) or the ingest API answers
|
|
34
|
+
`403` with reason `disabled`, and the SDK switches itself off.
|
|
35
|
+
5. **Is the page's origin allowed?** If the workspace restricts which
|
|
36
|
+
origins may send errors, a page on another origin (a preview deployment,
|
|
37
|
+
`localhost`) gets `403` with reason `origin_not_allowed`, and the SDK
|
|
38
|
+
stops for that page load.
|
|
39
|
+
6. **Is the request blocked before it leaves?** Ad blockers and privacy
|
|
40
|
+
extensions may block requests to error-tracking endpoints. In the
|
|
41
|
+
browser's network tab, look for the `POST …/api/v1/ingest/errors`
|
|
42
|
+
request: blocked, or never sent. Errors from those visitors do not
|
|
43
|
+
arrive.
|
|
44
|
+
7. **Was the event dropped on purpose?** With `debug: true` each drop says
|
|
45
|
+
why: `InboundFilters` (noise, see [browser.md](./browser.md#filter-noise)),
|
|
46
|
+
`ignoreErrors`, `allowUrls` / `denyUrls`, `suppress` (a rule set for the
|
|
47
|
+
workspace), `sample`, `beforeSend`, or a rate limit.
|
|
48
|
+
8. **Did it have time to leave?** Events are sent a second after capture.
|
|
49
|
+
A script or serverless function that ends at once loses them unless it
|
|
50
|
+
flushes; see [5](#5-events-missing-when-a-process-or-function-ends).
|
|
51
|
+
|
|
52
|
+
## 2. Stack traces are minified
|
|
53
|
+
|
|
54
|
+
Upload source maps at build time: [source-maps.md](./source-maps.md), and its
|
|
55
|
+
[troubleshooting](./source-maps.md#troubleshooting-unresolved-frames) for
|
|
56
|
+
frames that stay unresolved.
|
|
57
|
+
|
|
58
|
+
## 3. The same error is reported twice
|
|
59
|
+
|
|
60
|
+
- **With the Starko widget on the page:** see
|
|
61
|
+
[widget.md](./widget.md#duplicate-reports).
|
|
62
|
+
- **Two copies of `init`** in different bundles: one client replaces the
|
|
63
|
+
other, which is fine; but two different Starko SDK versions of different
|
|
64
|
+
compatibility lines (`0.1.x` next to `1.x`, for example) keep separate
|
|
65
|
+
state and both report. Use one version.
|
|
66
|
+
- **Your own handler and the SDK:** the SDK reports the same error object
|
|
67
|
+
once, however many times it is captured. A copy of the error (a new
|
|
68
|
+
`Error` with the same message) is a new event, unless it arrives right
|
|
69
|
+
after an identical one (same type, message, frames, fingerprint, user and
|
|
70
|
+
session, and on a server the same request).
|
|
71
|
+
|
|
72
|
+
## 4. Events missing when the page closes
|
|
73
|
+
|
|
74
|
+
When the page is hidden or closed, the SDK sends its queue with `keepalive`
|
|
75
|
+
so the request survives the page. Browsers allow 64 KiB of `keepalive`
|
|
76
|
+
request bodies in flight per page; beyond that the rest is sent without
|
|
77
|
+
`keepalive` and may be cut off. Events captured in the last moment of a
|
|
78
|
+
page (in an `unload` handler) may not be sent at all. A very large `extra`
|
|
79
|
+
or many breadcrumbs make each event bigger: keep them small.
|
|
80
|
+
|
|
81
|
+
## 5. Events missing when a process or function ends
|
|
82
|
+
|
|
83
|
+
- `process.exit()` ends the process before anything can be sent. Call
|
|
84
|
+
`await Starko.flush(2000)` first.
|
|
85
|
+
- Serverless functions may be frozen as soon as the handler returns. Wrap
|
|
86
|
+
the handler in `wrapHandler`, or `await Starko.flush(2000)` before
|
|
87
|
+
returning. See [node.md](./node.md#other-frameworks-and-serverless-wraphandler).
|
|
88
|
+
- `next start` exits on `SIGTERM` without waiting; see
|
|
89
|
+
[nextjs.md](./nextjs.md#vercel-and-long-lived-servers).
|
|
90
|
+
|
|
91
|
+
## 6. The process does not exit, or exits later than before
|
|
92
|
+
|
|
93
|
+
The SDK never keeps a Node process alive on its own. It holds it open only
|
|
94
|
+
to send what is queued, for a bounded time:
|
|
95
|
+
|
|
96
|
+
- when the event loop empties: at most `shutdownTimeout` (2 s), only if
|
|
97
|
+
events are queued;
|
|
98
|
+
- on `SIGTERM` / `SIGINT` without an app handler: at most `shutdownTimeout`;
|
|
99
|
+
- after a crash: at most `fatalFlushTimeout` (1 s);
|
|
100
|
+
- with the `fetch` option (a proxy): a request in flight, at most 10 s.
|
|
101
|
+
|
|
102
|
+
A process that stays up longer is held by something else (an open server,
|
|
103
|
+
a database pool, a timer).
|
|
104
|
+
|
|
105
|
+
## 7. `401`, `403` and `429`: what each reason means
|
|
106
|
+
|
|
107
|
+
Seen in the browser's network tab, or in the console with `debug: true`.
|
|
108
|
+
|
|
109
|
+
| Status | Reason | Meaning | What the SDK does | What to do |
|
|
110
|
+
| --- | --- | --- | --- | --- |
|
|
111
|
+
| 401 | `unknown_workspace` | The workspace key is not known. | Stops sending for this page load or process. | Fix `workspaceKey`. |
|
|
112
|
+
| 401 | `invalid` | The secret key (`apiKey`, servers only) is not valid. | Drops the batch without retrying and prints `secret key refused` once; later batches are still sent. | Fix or remove `apiKey`. |
|
|
113
|
+
| 401 / 403 | none, or not JSON | Not from Starko: a proxy, a firewall, a captive portal. | Retries with back-off; never switches off. | Check what sits between your app and Starko. |
|
|
114
|
+
| 403 | `disabled` | Error tracking is off for the workspace. | Stops sending. | Enable it in Starko. |
|
|
115
|
+
| 403 | `origin_not_allowed` | The page's origin is not on the workspace's allow-list. | Stops sending for this page load. | Add the origin in Starko, or ignore it for preview hosts. |
|
|
116
|
+
| 429 | `rate_limit` | Too many requests right now. | Waits `Retry-After`, then retries. | Usually nothing. If constant, lower `sampleRate` or fix the error loop. |
|
|
117
|
+
| 429 | `quota` | The workspace's allowance is used up. | Drops the batch and sends nothing until `Retry-After` has passed. | Check the workspace's usage in Starko. |
|
|
118
|
+
|
|
119
|
+
Other answers: `413` (batch too large: halved and retried once), `400`
|
|
120
|
+
(malformed: dropped), and `503` (busy). The ingest API answers `503` with
|
|
121
|
+
`Retry-After: 30` while its queue store is unavailable; the SDK waits at
|
|
122
|
+
least that long before it tries the batch again. Each batch gets at most
|
|
123
|
+
three attempts (network failures and 5xx included), so events can arrive a
|
|
124
|
+
minute or more late, or not at all during a longer outage. The back-off
|
|
125
|
+
and the number of attempts cannot be changed from `init`. The full table
|
|
126
|
+
is in [wire-format.md](./wire-format.md#responses).
|
|
127
|
+
|
|
128
|
+
## 8. `host answered 3xx … not followed`
|
|
129
|
+
|
|
130
|
+
Your `host` redirects (`http://` to `https://`, an apex domain to `www.`).
|
|
131
|
+
The SDK never follows redirects (the event would be lost and a secret key
|
|
132
|
+
could go to another host), so those events were dropped. Set `host` to the
|
|
133
|
+
final address.
|
|
134
|
+
|
|
135
|
+
## 9. The error arrives, but is not linked to the customer
|
|
136
|
+
|
|
137
|
+
A user is linked only when verified:
|
|
138
|
+
|
|
139
|
+
- browser: send a user hash with `identify(user, userHash)`
|
|
140
|
+
([browser.md](./browser.md#identify-the-user)), or have the Starko widget
|
|
141
|
+
on the page;
|
|
142
|
+
- server: set `apiKey` (then `user.id` is trusted), or send a user hash;
|
|
143
|
+
- through the widget's token: verified when that customer's profile is
|
|
144
|
+
anonymous or identity-verified; a customer identified in the widget
|
|
145
|
+
without verification is linked too, labelled "unverified" in Starko;
|
|
146
|
+
- events sent through the PostHog-compatible route are never linked.
|
|
147
|
+
|
|
148
|
+
On a server, a user set outside a request never reaches a request's
|
|
149
|
+
errors: requests start from the `user` passed to `init` (see
|
|
150
|
+
[node.md](./node.md#code-outside-a-request)). Set the user inside the
|
|
151
|
+
request. On the Edge runtime a `setUser` outside a request scope is
|
|
152
|
+
refused, with a warning; set it inside `wrapHandler`.
|
|
153
|
+
|
|
154
|
+
## 10. `events dropped: …` in the console
|
|
155
|
+
|
|
156
|
+
A limit dropped events. For the three rate limits the line is printed at
|
|
157
|
+
most once a minute per limit, with the number dropped since the previous
|
|
158
|
+
line:
|
|
159
|
+
|
|
160
|
+
- `events dropped by rate limit per error (10, then 1 per 10 s): N …,
|
|
161
|
+
latest "TypeError: Order <n> not found"`: one error was reported more
|
|
162
|
+
than 10 times at once. An error is its type and message with numbers and
|
|
163
|
+
ids masked (`<n>`, `<id>`), as the line shows;
|
|
164
|
+
- `events dropped by maxEventsPerLifetime`: 100 per page load in the
|
|
165
|
+
browser;
|
|
166
|
+
- `events dropped by maxEventsPerMinute`: 300 a minute on servers.
|
|
167
|
+
|
|
168
|
+
Printed once: the queue size (`maxQueueSize`), more than 30 events before
|
|
169
|
+
the remote config arrived, and an async `beforeSend` that did not settle in
|
|
170
|
+
time. A page or server that hits these is usually throwing the same error
|
|
171
|
+
in a loop: fix the loop, or raise the limit if the volume is expected.
|
|
172
|
+
|
|
173
|
+
## 11. Source-map upload: storage, expired URLs, the allowance
|
|
174
|
+
|
|
175
|
+
These come from the build plugins, `withStarko` and `starko sourcemaps
|
|
176
|
+
upload`, not from the runtime SDK. With the bulk upload (the default when
|
|
177
|
+
the server offers it) every map is sent from the build machine straight to
|
|
178
|
+
Starko's storage through a short-lived signed URL, so the build needs to
|
|
179
|
+
reach two hosts: the Starko host and the storage host the server names.
|
|
180
|
+
The first line of the upload says which protocol is used:
|
|
181
|
+
`source map upload: using the bulk upload: …` or
|
|
182
|
+
`source map upload: using the v1 upload through <host>: …`.
|
|
183
|
+
|
|
184
|
+
**`uploads to Starko's storage at <origin> fail (3 in a row, last: …)`.**
|
|
185
|
+
The build machine cannot reach the storage host: a proxy, a firewall or an
|
|
186
|
+
allow-list that lets only the Starko host through. With the default
|
|
187
|
+
`uploadProtocol: "auto"` the upload goes on through the Starko host (v1)
|
|
188
|
+
for every map storage does not hold, and the warning says so. That
|
|
189
|
+
includes the few maps reserved before the failure was detected (until a
|
|
190
|
+
first upload to storage succeeds, maps are reserved 4 at a time): the
|
|
191
|
+
server lets v1 take those reservations over at once, since nothing was
|
|
192
|
+
stored under them. Fix it either way, so later builds use the faster bulk
|
|
193
|
+
upload:
|
|
194
|
+
|
|
195
|
+
- allow the storage host named in the warning (only its host is printed;
|
|
196
|
+
the signed URL never is), or
|
|
197
|
+
- set `uploadProtocol: "v1"` (CLI: `--protocol v1`): every map goes through
|
|
198
|
+
the Starko host, and the storage host is never contacted.
|
|
199
|
+
|
|
200
|
+
With `uploadProtocol: "bulk"` there is no fallback: the upload stops with
|
|
201
|
+
the same message.
|
|
202
|
+
|
|
203
|
+
Behind a proxy: the build tools send with Node's global `fetch`, to the
|
|
204
|
+
Starko host and to storage alike. It uses `HTTPS_PROXY` / `HTTP_PROXY` and
|
|
205
|
+
`NO_PROXY` only when Node runs with `NODE_USE_ENV_PROXY=1` (checked on Node
|
|
206
|
+
24), or when your build installs a global dispatcher with a proxy
|
|
207
|
+
(undici's `setGlobalDispatcher`). The storage host must not be in
|
|
208
|
+
`NO_PROXY` if it is only reachable through the proxy.
|
|
209
|
+
|
|
210
|
+
**An expired URL.** A signed URL is valid for 10 minutes. The tools time
|
|
211
|
+
it from the server's "seconds left" (`expires_in_s`) on the build
|
|
212
|
+
machine's own monotonic clock, so a build machine whose clock is wrong
|
|
213
|
+
still renews it in time: a new `bulk/start` for the map (the server signs
|
|
214
|
+
the same object again) when it has less than a minute left before its
|
|
215
|
+
upload starts. An upload storage refuses (an expired URL included) is
|
|
216
|
+
never repeated to the same URL: it is confirmed with the server (an
|
|
217
|
+
earlier attempt may have landed) and, when it did not, started again for a
|
|
218
|
+
fresh URL. Nothing to do. When a map reports `not uploaded after 4
|
|
219
|
+
bulk/start requests`, check the build machine's connection to storage.
|
|
220
|
+
|
|
221
|
+
**`no answer within 135 s` (or 45 s, 75 s).** Each request waits for its
|
|
222
|
+
route's longest run on the server plus 15 s (`bulk/finish`, which
|
|
223
|
+
verifies maps, up to 2 minutes): a slow answer is waited for. Three
|
|
224
|
+
requests in a row without an answer stop the upload with `cannot reach
|
|
225
|
+
<host>`: check the build machine's connection to the Starko host.
|
|
226
|
+
|
|
227
|
+
**`the server refused the uploaded map (failed: Verification failed: …);
|
|
228
|
+
it is not sent again by this build`.** Starko read the map back and it was
|
|
229
|
+
not what the build declared: its sha256, its `debugId`, its size or its
|
|
230
|
+
gzip. The same bytes would fail again, and every failed map counts against
|
|
231
|
+
the key's daily upload budget, so the tools do not retry it. Check that
|
|
232
|
+
nothing changes the bundle or the map after the upload starts (another
|
|
233
|
+
plugin, a minifier run afterwards; see [One tool per
|
|
234
|
+
build](./source-maps.md#one-tool-per-build)); a later build with the fixed
|
|
235
|
+
map sends it again.
|
|
236
|
+
|
|
237
|
+
**`… storage allowance … (over_allowance); the upload stops here`.** The
|
|
238
|
+
workspace's source-map storage is full. The maps already reserved are
|
|
239
|
+
finished, nothing more is sent, and the build log says how far it got.
|
|
240
|
+
Delete maps you no longer need in Starko, then build again. v1
|
|
241
|
+
reports the same as `413: Source-map storage allowance reached`.
|
|
242
|
+
|
|
243
|
+
**`the server asks to wait 10 h before the next request (429: … daily
|
|
244
|
+
source-map upload budget …)`.** The API key's daily upload budget is
|
|
245
|
+
spent. The upload stops at once; the next day's build continues.
|
|
246
|
+
|
|
247
|
+
**`earlier uploads of this debug id may still be under way on the server
|
|
248
|
+
… (busy)`.** Rare: the map's debug id was restarted more than three times
|
|
249
|
+
within about 20 minutes (builds of other content for the same id, or maps
|
|
250
|
+
that failed verification), and the server waits for one of those uploads
|
|
251
|
+
to be over. The tools wait out a `busy` of up to a minute; a longer one
|
|
252
|
+
fails that map, and a later build sends it. v1 reports a map whose bulk
|
|
253
|
+
upload already put an object in Starko's storage less than about 20
|
|
254
|
+
minutes ago as `Starko is receiving this map through a direct upload to
|
|
255
|
+
its storage that may still be under way` (a reservation with nothing in
|
|
256
|
+
storage is taken over by v1 at once).
|
|
257
|
+
|
|
258
|
+
**`Starko has disabled source-map uploads (423: …)`.** The server found an
|
|
259
|
+
uploaded map readable without a signature and switched source-map uploads
|
|
260
|
+
off, for every build, until an operator fixes its storage (this can take
|
|
261
|
+
hours). Nothing more is sent and nothing is retried; the build goes on
|
|
262
|
+
(unless `failOnError` is set). This is a problem on Starko's side: contact
|
|
263
|
+
Starko. Maps that were not uploaded are sent by a build after it is fixed.
|
package/docs/widget.md
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Using the SDK with the Starko widget
|
|
2
|
+
|
|
3
|
+
The Starko widget (chat, help center, session recording) can report page
|
|
4
|
+
errors on its own. When the SDK is on the same page, the SDK takes over
|
|
5
|
+
error capture and the two share what links an error to a customer and to a
|
|
6
|
+
recording. Install both as usual; there is nothing to configure, and they
|
|
7
|
+
may load in either order.
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
import * as Starko from "@starko-one/sdk/browser";
|
|
11
|
+
|
|
12
|
+
Starko.init({ workspaceKey: "<STARKO_WORKSPACE_KEY>" });
|
|
13
|
+
// The widget's own snippet stays as it is.
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Who captures errors
|
|
17
|
+
|
|
18
|
+
The two meet through one global object, `window.__STARKO_BRIDGE__`. The SDK
|
|
19
|
+
announces on it whether it is capturing page errors (`capturesErrors`), and
|
|
20
|
+
announces every change with a `starko:bridge` event on `window`.
|
|
21
|
+
|
|
22
|
+
- While `capturesErrors` is true, the widget does not install its own error
|
|
23
|
+
hooks: each error is reported once, by the SDK.
|
|
24
|
+
- `capturesErrors` is true only while the SDK is running **and** its global
|
|
25
|
+
error handlers are installed. It becomes false after `close()`, when the
|
|
26
|
+
workspace's error tracking is switched off, or when you remove the
|
|
27
|
+
`GlobalHandlers` integration. The widget then reports page errors itself
|
|
28
|
+
again.
|
|
29
|
+
- The widget also reports errors a page passes to `console.error` (for
|
|
30
|
+
example from a framework's error boundary) and stops doing so when the SDK
|
|
31
|
+
is there. So, while the widget is on the page, the SDK captures them
|
|
32
|
+
instead: an `Error` object passed to `console.error` is reported as a
|
|
33
|
+
handled error. Remove the `ConsoleErrorCapture` integration to stop that;
|
|
34
|
+
add `consoleErrorCaptureIntegration()` yourself to capture them without the
|
|
35
|
+
widget too.
|
|
36
|
+
|
|
37
|
+
## The session: errors linked to recordings
|
|
38
|
+
|
|
39
|
+
With the widget on the page and recording, the SDK stamps the recorder's
|
|
40
|
+
session id on every error, so the error links to the recording of the
|
|
41
|
+
session it happened in. Without the widget, the SDK creates its own session
|
|
42
|
+
id, kept per tab in `sessionStorage` under `starko:errors:session`, the same
|
|
43
|
+
key the widget uses, so both agree whichever loads first.
|
|
44
|
+
|
|
45
|
+
## The customer: verified through the widget
|
|
46
|
+
|
|
47
|
+
When the widget is on the page, the SDK sends the widget's client token
|
|
48
|
+
with every error. Starko verifies it and links the error to the widget's
|
|
49
|
+
customer, with no user hash needed. The link is verified when that
|
|
50
|
+
customer's profile is anonymous or identity-verified. A customer who was
|
|
51
|
+
identified in the widget without verification (an email typed into it, or
|
|
52
|
+
`identify` without a hash) is linked too, and Starko labels that link
|
|
53
|
+
"unverified" on the error, in the affected customers list and in a ticket
|
|
54
|
+
filed from it. Starko also checks the user hash you sent with `identify`:
|
|
55
|
+
a valid hash links your user as verified and replaces the unverified link.
|
|
56
|
+
The token is a credential: the SDK
|
|
57
|
+
sends it with the event and nowhere else (never in logs, breadcrumbs or
|
|
58
|
+
extra data), and Starko does not store it.
|
|
59
|
+
|
|
60
|
+
Without the widget, identify users with `identify(user, userHash)`; see
|
|
61
|
+
[browser.md](./browser.md#identify-the-user).
|
|
62
|
+
|
|
63
|
+
## Load order and lifecycle
|
|
64
|
+
|
|
65
|
+
| Situation | What happens |
|
|
66
|
+
| --- | --- |
|
|
67
|
+
| SDK first, widget later | The widget finds the SDK on the bridge and leaves error capture to it. The SDK reads the widget's session and token on every event, so events after the widget arrived carry them. |
|
|
68
|
+
| Widget first, SDK later | The SDK registers on the bridge and announces it; the widget stands its error capture down. |
|
|
69
|
+
| `Starko.close()` | `capturesErrors` becomes false and is announced; the widget reports errors itself again. |
|
|
70
|
+
| Error tracking switched off for the workspace | Same as `close()`. |
|
|
71
|
+
| `init` called again, or a second copy of the SDK (script tag and npm package) | One bridge entry, always routed to the current SDK client. |
|
|
72
|
+
| The page sets `__STARKO_BRIDGE__` to something that is not an object | The SDK leaves it alone and runs without the bridge. |
|
|
73
|
+
|
|
74
|
+
## Duplicate reports
|
|
75
|
+
|
|
76
|
+
Each error should arrive once. If you see the same error twice, once from
|
|
77
|
+
the widget and once from the SDK:
|
|
78
|
+
|
|
79
|
+
- check that `Starko.init` actually ran and is enabled (with `debug: true`
|
|
80
|
+
the console shows `[starko] started`);
|
|
81
|
+
- check that `GlobalHandlers` was not removed (then `capturesErrors` is false
|
|
82
|
+
and the widget reports instead, which is expected);
|
|
83
|
+
- check that the widget build on the page reads the bridge. A widget that
|
|
84
|
+
does not know `__STARKO_BRIDGE__` keeps capturing next to the SDK.
|