@guidelytech/node 0.15.0 → 0.17.0

package/README.md

@@ -3,7 +3,8 @@
 Send product data to [Guidely](https://guidelytech.com) from your Node.js backend: who a user is
 (`identify`), what they did (`track`) and which account they belong to (`group`). Server events land
 next to browser and app events, so they work in Events, Funnels, Retention, audiences and guide
-targeting.
+targeting. It also reports errors and crashes ([Error monitoring](#error-monitoring)) with the same
+API as Sentry's Node SDK.
 
 * Node.js 18+, no runtime dependencies (uses the global `fetch`). ESM and CommonJS.
 * Calls never throw and never wait for the network: they validate, queue and return.
@@ -20,7 +21,8 @@ Feature flags for servers live in [`@guidelytech/flags`](../flags).
 
 Create a **secret key** (`gly_sk_…`) with the **`events:write`** scope in **Settings → API keys**.
 Keep it in your secret manager; never ship it to a browser or app. Each client writes to one
-environment: `development`, `staging` or `production`.
+environment, named by its key: `development`, `staging`, `production`, or one you added in
+**Settings → Environments & Install** (`qa`, `uat`…).
 
 ## Usage
 
@@ -78,7 +80,7 @@ export const handler = async (event) => {
 | Option | Default | |
 |---|---|---|
 | `secretKey` | — | **Required.** A `gly_sk_…` key with `events:write`. |
-| `environment` | — | **Required.** `development`, `staging` or `production`. |
+| `environment` | — | **Required.** The environment key: `development`, `staging`, `production` or one you added (`qa`). |
 | `apiUrl` | `https://guidelytech.com` | For self-hosted or local servers. |
 | `flushAt` | `100` | Send when this many messages are queued (a batch holds at most 100 messages and 500 KB). |
 | `flushIntervalMs` | `5000` | Send what is queued at least this often. The timer never keeps the process alive. |
@@ -89,20 +91,162 @@ export const handler = async (event) => {
 | `onError` | `console.warn` | Receives a `GuidelyError` for every problem (see below). |
 | `handleExit` | `true` | Flush on `beforeExit`. |
 | `fetch` | global `fetch` | Any `fetch`-compatible function (proxies, tests). |
+| `appVersion` | — | Your app's version, sent with every `track` for [App versions](https://guidelytech.com/docs/product-analytics#app-versions); a message's own `appVersion` wins. Also the default release of errors. |
+| `errors` | `{}` | [Error monitoring](#error-monitoring) options; `false` turns off the automatic breadcrumbs. |
+
+## Error monitoring
+
+Errors become `exception` events grouped into issues on the Errors page. The API is Sentry's, so
+moving off `@sentry/node` is mostly a rename. Every capture call returns at once and never throws;
+events go out through the same batched, retried queue as `track` calls, sent right away instead of
+waiting for the flush interval.
+
+```ts
+try {
+  await chargeCard(order);
+} catch (err) {
+  guidely.captureException(err, {
+    userId: "u_42", // default: the scope user's id
+    tags: { area: "billing" },
+    extra: { orderId: order.id },
+    level: "error", // fatal | error | warning | log | info | debug
+    fingerprint: ["{{ default }}", "billing"],
+    contexts: { payment: { provider: "stripe" } },
+    request: req, // an Express/Fastify/Koa request: method, URL, headers (no credentials)
+  }); // → the event id
+}
+
+guidely.captureMessage("Disk almost full", "warning");
+```
+
+Other keys of the second argument (`orderId: "o_1"`) are kept as event properties. Errors carry their
+`cause` chain and an `AggregateError`'s `errors` (up to 20, causes first), stack frames marked
+in-app unless they are in `node_modules` or Node itself, and five source lines around each in-app
+frame, read from disk (cached, files over 1 MB skipped; `contextLines: 0` turns it off).
+
+### Scopes and breadcrumbs
+
+```ts
+guidely.setTag("region", "eu-west-1");
+guidely.setTags({ tier: "pro" });
+guidely.setExtra("build", 512);
+guidely.setContext("queue", { name: "emails", depth: 40 }); // null removes it
+guidely.setUser({ id: "u_42", email: "ada@example.com" }); // null clears it
+guidely.addBreadcrumb({ category: "auth", message: "Signed in", level: "info", data: { method: "sso" } });
+
+await guidely.withScope(async (scope) => {
+  scope.setTag("job", "nightly-export");
+  await runExport(); // errors captured in here (and in what it starts) carry the tag
+});
+```
+
+The client has one process-wide scope. `withScope()` runs a callback with a copy of the current one,
+through `AsyncLocalStorage`, so what is set inside (tags, user, breadcrumbs) never leaks into other
+work running at the same time; the framework middlewares below open one per request. The last 100
+breadcrumbs of a scope ride along with each error.
+
+Breadcrumbs are recorded automatically for `console.warn` / `console.error` and for outgoing
+`http`/`https` requests and `fetch` (method, URL without the query string, status, duration; never
+requests to Guidely). HTTP requests are observed through `diagnostics_channel`, so nothing is
+patched; console methods are wrapped once and restored by `shutdown()`.
+
+### Process handlers
+
+```ts
+const uninstall = guidely.installProcessHandlers();
+```
+
+Opt-in. Reports `uncaughtException` (level `fatal`, `handled: false`) and `unhandledRejection`, then
+behaves as Node would without them: the error is printed, queued events are sent (waiting at most
+`flushTimeoutMs`, default 2000 ms) and the process exits with code 1.
+
+* It does not exit when your app has its own `uncaughtException` listener (Node would not either),
+  or with `exitOnUncaught: false`, which keeps the process running in whatever state the error left
+  it, like any `uncaughtException` listener.
+* `unhandledRejection` follows Node's `--unhandled-rejections` mode (the flag, else the `throw`
+  default): `throw` ends the process unless something else listens for rejections, `strict` even
+  then (both unless your app listens for `uncaughtException`, as in Node), `warn` prints a warning,
+  `none` stays silent. A rejection that ends the process is `fatal`,
+  otherwise `error`. Override it with `{ unhandledRejection: "warn" }`.
+* `shutdown()` removes the handlers, as does the returned function.
+
+### Frameworks
+
+The SDK has no framework dependencies; the middlewares are typed structurally.
+
+```ts
+// Express
+app.use(guidely.expressRequestHandler()); // first: a scope per request
+// …routes…
+app.use(guidely.expressErrorHandler()); // after the routes, before your own error handlers
+
+// Fastify
+await app.register(guidely.fastifyPlugin()); // request scopes + an onError hook
+// or only the hook: app.addHook("onError", guidely.fastifyErrorHook());
+// inside your own setErrorHandler: guidely.captureException(error, { request });
+
+// Koa
+app.use(guidely.koaMiddleware()); // first: reports errors from downstream and rethrows them
+```
+
+Errors are reported with the request (method, URL, query string with token-like values
+`[Filtered]`, headers without cookies, `Authorization`, API keys or forwarding addresses) and the
+transaction `METHOD /route` when the router exposes the matched route. By default only errors with
+no HTTP status or a 5xx status (`status`, `statusCode`) are reported; pass
+`{ shouldHandleError: (err) => boolean }` to change that. An error passing through two hooks is
+reported once.
+
+### Options
+
+```ts
+const guidely = new Guidely({
+  secretKey: process.env.GUIDELY_SECRET_KEY!,
+  environment: "production",
+  appVersion: "2.4.1",
+  errors: {
+    sampleRate: 1,
+    ignoreErrors: ["ECONNRESET", /^AbortError/],
+    beforeSend: (event, hint) => (event.tags?.area === "health" ? null : event),
+    beforeBreadcrumb: (crumb) => (crumb.category === "console" && crumb.level === "warning" ? null : crumb),
+  },
+});
+```
+
+| `errors.` option | Default | |
+|---|---|---|
+| `sampleRate` | `1` | Share of errors sent (0–1). |
+| `ignoreErrors` | `[]` | Strings match `"<type>: <message>"` or the message as substrings; RegExps as patterns. |
+| `beforeSend` | — | `(event, hint) => event \| null`, may be async. Edit the Sentry-shaped event or return `null` to drop it. A hook that throws leaves the event unchanged. |
+| `beforeBreadcrumb` | — | `(crumb, hint) => crumb \| null`. |
+| `release` | `appVersion` | The release errors belong to. |
+| `serverName` | `os.hostname()` | |
+| `inAppExclude` | `[]` | Paths (substrings or RegExps) that are not your code. |
+| `captureConsole` | `true` | `warn` + `error` breadcrumbs; a list picks the levels (`["log", "warn", "error"]`); `false` turns them off. |
+| `captureHttp` | `true` | Breadcrumbs for outgoing requests. |
+| `contextLines` | `5` | Source lines before and after in-app frames (up to 10; `0` turns it off). |
+| `sendDefaultPii` | `false` | Send the client IP of requests (`user.ip_address`, forwarding headers). |
+| `maxBreadcrumbs` | `100` | Breadcrumbs kept per scope (at most 100). |
+
+Credentials never leave the process: keys that look like `password`, `secret`, `token`, `card`,
+`apiKey`… are removed from extras, contexts, the user, breadcrumb data and event properties, before
+and again after `beforeSend`. Each event carries the `runtime`, `os`, `device`, `app` and `culture`
+contexts. The wire format is in [docs/error-monitoring/sdks.md](../../docs/error-monitoring/sdks.md):
+an `exception` message in the server batch, with Guidely `properties` and a Sentry-shaped `detail`
+trimmed to 64 KB (breadcrumbs first, then source lines).
 
 ## Validation and errors
 
 Invalid calls are dropped and reported, never thrown: `identify` needs a `userId`; `track` needs an
 `event` (1–120 characters) and a `userId` or `anonymousId`; `group` needs an `accountId`. Ids are
 strings of 1–256 characters (integers are converted); `traits` and `properties` must be plain
-objects. Messages over 32 KB are dropped.
+objects. Messages over 32 KB are dropped (80 KB for an exception, which first loses its `detail`).
 
 `onError` receives a `GuidelyError` with a `code`:
 
 | `code` | |
 |---|---|
 | `invalid_message` | A call was invalid and dropped. |
-| `message_too_large` | A message serialized to more than 32 KB. |
+| `message_too_large` | A message serialized to more than 32 KB (an exception: 80 KB). |
 | `queue_full` | The queue was full; `count` oldest messages were dropped. |
 | `delivery_failed` | A batch of `count` messages was rejected (`status`: `400`, `401`/`403` = bad key or missing scope, …), failed after every retry (`status` `0` = unreachable) or was cut short by the shutdown timeout. |
 | `closed` | A call was made after `shutdown()`. |