@watchtowerobservability/node 0.5.0 → 0.7.0

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.
Files changed (90) hide show
  1. package/README.md +88 -9
  2. package/dist/cjs/checkin.d.ts +7 -0
  3. package/dist/cjs/checkin.js +18 -0
  4. package/dist/cjs/env.d.ts +12 -0
  5. package/dist/cjs/env.js +37 -0
  6. package/dist/cjs/errors.d.ts +8 -0
  7. package/dist/cjs/errors.js +23 -0
  8. package/dist/cjs/filter.d.ts +2 -0
  9. package/dist/cjs/filter.js +16 -0
  10. package/dist/cjs/index.d.ts +48 -10
  11. package/dist/cjs/index.js +119 -53
  12. package/dist/cjs/instrument.d.ts +10 -0
  13. package/dist/cjs/instrument.js +74 -0
  14. package/dist/cjs/integrations/db.d.ts +3 -0
  15. package/dist/cjs/integrations/db.js +4 -1
  16. package/dist/cjs/integrations/genai-agents.d.ts +4 -1
  17. package/dist/cjs/integrations/genai-agents.js +27 -24
  18. package/dist/cjs/integrations/genai-frameworks.d.ts +25 -0
  19. package/dist/cjs/integrations/genai-frameworks.js +211 -0
  20. package/dist/cjs/integrations/genai.d.ts +1 -0
  21. package/dist/cjs/integrations/genai.js +7 -2
  22. package/dist/cjs/integrations/next-build.d.ts +31 -0
  23. package/dist/cjs/integrations/next-build.js +95 -0
  24. package/dist/cjs/integrations/next-tunnel.d.ts +14 -0
  25. package/dist/cjs/integrations/next-tunnel.js +52 -0
  26. package/dist/cjs/integrations/next.d.ts +24 -1
  27. package/dist/cjs/integrations/next.js +39 -7
  28. package/dist/cjs/load.js +37 -5
  29. package/dist/cjs/next-sourcemaps-cli.d.ts +2 -0
  30. package/dist/cjs/next-sourcemaps-cli.js +9 -0
  31. package/dist/cjs/origin.d.ts +9 -0
  32. package/dist/cjs/origin.js +43 -0
  33. package/dist/cjs/redact.d.ts +8 -0
  34. package/dist/cjs/redact.js +43 -0
  35. package/dist/cjs/register.d.ts +1 -0
  36. package/dist/cjs/register.js +29 -0
  37. package/dist/cjs/sampling.d.ts +53 -0
  38. package/dist/cjs/sampling.js +98 -0
  39. package/dist/cjs/scrub.d.ts +7 -0
  40. package/dist/cjs/scrub.js +39 -0
  41. package/dist/cjs/shutdown.d.ts +14 -0
  42. package/dist/cjs/shutdown.js +26 -0
  43. package/dist/cjs/sql.js +11 -1
  44. package/dist/cjs/version.d.ts +2 -0
  45. package/dist/cjs/version.js +5 -0
  46. package/dist/esm/checkin.d.ts +7 -0
  47. package/dist/esm/checkin.js +15 -0
  48. package/dist/esm/env.d.ts +12 -0
  49. package/dist/esm/env.js +33 -0
  50. package/dist/esm/errors.d.ts +8 -0
  51. package/dist/esm/errors.js +22 -0
  52. package/dist/esm/filter.d.ts +2 -0
  53. package/dist/esm/filter.js +13 -0
  54. package/dist/esm/index.d.ts +48 -10
  55. package/dist/esm/index.js +117 -53
  56. package/dist/esm/instrument.d.ts +10 -0
  57. package/dist/esm/instrument.js +71 -0
  58. package/dist/esm/integrations/db.d.ts +3 -0
  59. package/dist/esm/integrations/db.js +5 -2
  60. package/dist/esm/integrations/genai-agents.d.ts +4 -1
  61. package/dist/esm/integrations/genai-agents.js +4 -4
  62. package/dist/esm/integrations/genai-frameworks.d.ts +25 -0
  63. package/dist/esm/integrations/genai-frameworks.js +206 -0
  64. package/dist/esm/integrations/genai.d.ts +1 -0
  65. package/dist/esm/integrations/genai.js +3 -1
  66. package/dist/esm/integrations/next-build.d.ts +31 -0
  67. package/dist/esm/integrations/next-build.js +58 -0
  68. package/dist/esm/integrations/next-tunnel.d.ts +14 -0
  69. package/dist/esm/integrations/next-tunnel.js +49 -0
  70. package/dist/esm/integrations/next.d.ts +24 -1
  71. package/dist/esm/integrations/next.js +32 -6
  72. package/dist/esm/load.js +80 -2
  73. package/dist/esm/next-sourcemaps-cli.d.ts +2 -0
  74. package/dist/esm/next-sourcemaps-cli.js +7 -0
  75. package/dist/esm/origin.d.ts +9 -0
  76. package/dist/esm/origin.js +39 -0
  77. package/dist/esm/redact.d.ts +8 -0
  78. package/dist/esm/redact.js +39 -0
  79. package/dist/esm/register.d.ts +1 -0
  80. package/dist/esm/register.js +27 -0
  81. package/dist/esm/sampling.d.ts +53 -0
  82. package/dist/esm/sampling.js +91 -0
  83. package/dist/esm/scrub.d.ts +7 -0
  84. package/dist/esm/scrub.js +34 -0
  85. package/dist/esm/shutdown.d.ts +14 -0
  86. package/dist/esm/shutdown.js +23 -0
  87. package/dist/esm/sql.js +11 -1
  88. package/dist/esm/version.d.ts +2 -0
  89. package/dist/esm/version.js +2 -0
  90. package/package.json +40 -2
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  ## Install
6
6
 
7
- GitHub Packages needs a token with `read:packages` even for public packages:
7
+ Published on npm:
8
8
 
9
9
  ```sh
10
10
  npm install @watchtowerobservability/node @opentelemetry/context-async-hooks @opentelemetry/core \
@@ -14,8 +14,8 @@ npm install @watchtowerobservability/node @opentelemetry/context-async-hooks @op
14
14
 
15
15
  `@opentelemetry/api` is the only hard dependency; the OpenTelemetry SDK packages above are optional peers (so your app controls their versions) and are loaded by `init`, which throws an error naming the missing ones.
16
16
 
17
- Or install the attested tarball from a release without a token:
18
- `npm install https://github.com/watchtowerobservability/watchtower-node/releases/download/v0.2.0/watchtowerobservability-node-0.2.0.tgz`.
17
+ Optional auto-instrumentation peers (installed ones are used, see below):
18
+ `npm install @opentelemetry/instrumentation @opentelemetry/instrumentation-http @opentelemetry/instrumentation-undici @opentelemetry/instrumentation-pg @opentelemetry/instrumentation-ioredis`.
19
19
 
20
20
  Written in TypeScript and shipped as both ESM and CommonJS (`import` and `require` both work); the `.d.ts`
21
21
  typings are generated from the source. A thin layer over the OpenTelemetry Node SDK (ruling L1): `Authorization: Bearer` header, endpoint default (`WT_OTLP_ENDPOINT`), disk offline buffer,
@@ -37,7 +37,71 @@ wt.log('info', 'started', { port: 3000 }); // OTLP log, linked to the active
37
37
 
38
38
  `init` hooks `uncaughtException` and `unhandledRejection` (pass `captureProcessErrors: false` to opt out). It
39
39
  flushes and exits with code 1 like Node does, only when no other handler is registered.
40
- Request bodies, headers, query strings and query arguments are never recorded.
40
+ Request bodies, headers and query arguments are never recorded. URLs are scrubbed on every span, including spans other
41
+ libraries create (Next.js, `node:http`, `fetch`): the query string is dropped (`url.query` is removed) and path segments
42
+ that look like secrets or ids (24 characters or more, or 10 or more mixing letters and digits; UUIDs included) become
43
+ `:redacted`, in `http.target`, `url.full`, `url.path`, `http.url` and URLs in span names; `http.route` is kept.
44
+ `/api/feed/<token>/csv?since=x` is recorded as `/api/feed/:redacted/csv`. Plain words, numbers and short ids stay readable.
45
+ Pass `urlScrubbing: false` to record URLs as the instrumentation produced them. Your `redact` hook sees scrubbed values.
46
+
47
+ ## Auto-instrumentation and preload
48
+
49
+ `instrument: 'auto'` (or `WT_INSTRUMENT=auto`) also patches whichever of postgres.js, better-sqlite3 and mysql2
50
+ (`@opentelemetry/instrumentation-mysql2`) is installed, and prints one line (`[watchtower] instrumented: http, undici, pg, better-sqlite3`);
51
+ silence it with `instrumentLog: false` or `WT_INSTRUMENT_LOG=0`.
52
+
53
+ `wt.checkin('nightly-report', async () => { ... })` wraps a cron or scheduler job in check-ins to the monitor with that slug
54
+ (`in_progress`, then `ok` or `error` with the duration; the key needs scope `ingest:checkins`; the edge accepts 6 a minute per monitor;
55
+ failed check-ins never affect the job).
56
+
57
+ `init` patches `node:http`, `fetch` (undici), `pg` and `ioredis` for each `@opentelemetry/instrumentation-*` package you have installed (the list above); pass `instrument: false` or set `WT_INSTRUMENT=0` to skip. Patching only reaches modules loaded after it runs, so load the SDK first:
58
+
59
+ ```sh
60
+ node --require @watchtowerobservability/node/register app.js # CommonJS app (also: node -r ...)
61
+ node --import @watchtowerobservability/node/register app.mjs # ESM app
62
+ ```
63
+
64
+ `register` calls `init({})` when `WT_INGEST_KEY` is set. For an ESM app it also registers OpenTelemetry's ESM loader hook (`@opentelemetry/instrumentation/hook.mjs`, resolved from your project, so install `@opentelemetry/instrumentation`) so `node:http` and other ES-module imports get patched; no extra flag is needed. The CommonJS and ESM copies of this package share one client (kept on `globalThis`), so `flush()` and `shutdown()` work from either. Start a CommonJS app with `--require` and an ES-module app with `--import`.
65
+
66
+ `init` registers the global tracer provider, context manager, propagator and meter provider only when none is registered yet (OpenTelemetry allows each once): call `init` before other OTel setup. It no longer disables globals set earlier; a warning (via the OTel `diag` logger) says when one was kept. A second `init` replaces only what the first one installed.
67
+
68
+ ## Next.js
69
+
70
+ ```ts
71
+ // instrumentation.ts
72
+ import { makeRegister } from '@watchtowerobservability/node/next';
73
+ export const register = makeRegister({ redact: (k, v) => v }); // any InitOptions; plain `register` takes env only
74
+ export { onRequestError } from '@watchtowerobservability/node/next';
75
+ ```
76
+
77
+ `makeRegister` also takes `nextInternals: 'drop' | 'sample' | 'keep'` (default `'sample'`, `nextInternalsRate` 0.1) for Next's
78
+ own spans (those with a `next.span_type` attribute: load route module, prepare route module, resolve page components, start
79
+ response, middleware, generateMetadata). Request, route handler, render, server action and fetch spans, all SERVER/CLIENT
80
+ spans and errored spans are always kept; children of a dropped internal span stay in the trace.
81
+
82
+ **Source maps.** `next.config.js`: `module.exports = withWatchtower(nextConfig, { sourcemaps: true })` (from
83
+ `@watchtowerobservability/node/next`) turns on `productionBrowserSourceMaps`. Build with
84
+ `"build": "next build && wt-next-sourcemaps"`: the `wt-next-sourcemaps` bin (or `uploadSourcemaps()`) uploads every `.map` under
85
+ `.next/static` as `_next/static/<path>` for release `$WT_RELEASE` (create it first or let the upload create it; it must equal
86
+ the browser SDK's `release`), with `$WT_API_KEY` and `$WT_PROJECT` (and `$WT_API_URL`), then deletes the `.map` files so they are
87
+ never served. If an upload fails the command exits 1 and leaves the files. **Key scope: `ci:write`** (it covers releases and
88
+ artifacts; `admin:write` also works). Ingest keys cannot upload. Turbopack and webpack both emit these maps; Next does not inject
89
+ debug ids, so maps match by release and file name.
90
+
91
+ **First-party tunnel** (ad blockers block third-party telemetry hosts): `app/api/wt/[...path]/route.ts`:
92
+ `export const { GET, POST } = tunnelHandler({ endpoint: process.env.WT_EDGE_URL! });`, then `init({ endpoint: '/api/wt', publishableKey })`
93
+ in the browser SDK. Only `/v1/rum/*`, `/v1/replay/<session>/chunks` and `/v1/logs` are forwarded; the only credential passed on
94
+ is the publishable key (`?k=` or a `wtp_` bearer), cookies and other headers are dropped, bodies over 1 MiB get 413
95
+ (`maxBodyBytes`). The visitor's IP is the server's, so geo comes from the Next host unless the edge is told otherwise.
96
+
97
+ **Flushing on SIGTERM.** `init` flushes spans, logs and metrics (2 s cap) on SIGTERM and SIGINT, and if no other handler is
98
+ registered it re-sends the signal so the exit is unchanged. Under `next start`, Next installs its own SIGTERM handler that closes
99
+ the server and calls `process.exit`; our flush starts first (the `register` hook runs before) and gets the time the server takes
100
+ to close, so a very slow export can still be cut.
101
+
102
+ Install the OpenTelemetry peers above in the app itself (with pnpm, as direct dependencies, so Next's standalone tracer copies them). The SDK requires each peer by its literal name, so webpack and Next's file tracer can follow them; if the SDK arrives through a transpiled workspace package, add it to `transpilePackages`. Add `outputFileTracingIncludes` for the peers only if the standalone build still reports a missing `@opentelemetry/*` package.
103
+
104
+ Bundling with esbuild or webpack (ESM or CommonJS output) works: both the CommonJS and ESM builds name every optional peer with a literal `require`/`import()` inside try, so the bundler follows the peers you have installed and skips the rest.
41
105
 
42
106
  ## Integrations
43
107
 
@@ -86,7 +150,10 @@ Each lives at its own subpath, so nothing is loaded that you do not import.
86
150
  | Mistral, Ollama | `.../genai` | `instrumentMistral(new Mistral())`, `instrumentOllama(ollama)` |
87
151
  | LlamaIndex.TS | `.../genai` | `instrumentLlamaIndex(Settings)` |
88
152
  | OpenAI Agents SDK | `.../genai` | `instrumentOpenAIAgents(addTraceProcessor)` |
89
- | Vercel AI SDK | `.../genai` | `generateText({ experimental_telemetry: vercelAiTelemetry() })` |
153
+ | LangChain.js / LangGraph.js | `.../genai` | `graph.invoke(x, { callbacks: [langchainCallbackHandler()] })` |
154
+ | Vercel AI SDK agent loop | `.../genai` | `const { generateText } = instrumentVercelAI({ generateText })` |
155
+ | Mastra | `.../genai` | `instrumentMastra(agent)` |
156
+ | Vercel AI SDK (telemetry only) | `.../genai` | `generateText({ experimental_telemetry: vercelAiTelemetry() })` |
90
157
 
91
158
  GenAI spans follow the OTel GenAI semantic conventions (model, token usage, finish reasons); prompt and
92
159
  completion text is not recorded. Streaming calls end their span at creation, without token usage.
@@ -125,6 +192,15 @@ active span, following the OTel database conventions: `db.system.name`, `db.oper
125
192
  server and spans join the Datastores views. The algorithm is specified in
126
193
  `docs/product/instrumentation/sql-normalization.md` and exported at `.../sql`.
127
194
 
195
+ DDL summaries name the table: `CREATE TABLE IF NOT EXISTS forms` is `CREATE TABLE forms`, `CREATE [UNIQUE] INDEX x ON forms` is
196
+ `CREATE INDEX forms` (TEMP and VIRTUAL tables too).
197
+
198
+ **`requireParent` (default true):** a query is recorded only when a span is active (a request, job or `observe` span).
199
+ Startup DDL, migrations and polling loops run outside any span and would otherwise each become a root trace (one app start
200
+ produced 300 of them). It applies to every datastore integration and postgres.js through the shared `DbOptions`; pass
201
+ `{ requireParent: false }` or set `WATCHTOWER_DB_REQUIRE_PARENT=0` to record root queries again. To see a background loop,
202
+ wrap it in `observe('poll', fn)`.
203
+
128
204
  Statement text and parameters are never recorded by default. Pass `{ queryText: true }` (or set
129
205
  `WATCHTOWER_DB_QUERY_TEXT=1`) to add `db.query.text`, which is then the literal-free text. A
130
206
  statement that runs more than 5 times under one parent span gets `db.n_plus_one=true` and
@@ -269,14 +345,17 @@ See `docs/product/security/app-api-protection.md`.
269
345
  | Option | Env var | Default |
270
346
  | --- | --- | --- |
271
347
  | `apiKey` | `WT_INGEST_KEY` | required, sent as `Authorization: Bearer`, masked in output |
272
- | `endpoint` | `WT_OTLP_ENDPOINT` | `http://localhost:4318` |
273
- | `serviceName` | `WT_SERVICE` | `app` |
348
+ | `endpoint` | `WT_OTLP_ENDPOINT`, then `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` |
349
+ | `serviceName` | `WT_SERVICE`, then `OTEL_SERVICE_NAME` | `app` |
274
350
  | `environment` | `WT_ENVIRONMENT` | unset |
275
- | `release` | `WT_RELEASE` | unset |
351
+ | `release` | `WT_RELEASE`, then `service.version` in `OTEL_RESOURCE_ATTRIBUTES` | unset; sent as `service.version`, and an issue's first release is linked when a release with that version exists in the project |
352
+ | `resource` | `OTEL_RESOURCE_ATTRIBUTES` | none; `OTEL_EXPORTER_OTLP_HEADERS` adds extra headers, and its `Authorization=Bearer <key>` is used when `WT_INGEST_KEY` is unset |
353
+ | `instrument` | `WT_INSTRUMENT` (`0` off, `auto` adds postgres.js, better-sqlite3, mysql2) | `on` for installed http / undici / pg / ioredis instrumentations |
354
+ | `urlScrubbing` | | `true`: drop query strings and redact secret-looking path segments on every span |
276
355
  | `bufferDir` | | no offline buffer (spans, logs and metrics spool to `traces/`, `logs/` and `metrics/`, 500 batches each) |
277
356
  | `logs` | `WATCHTOWER_LOGS` (`OTEL_LOGS_EXPORTER=none` also turns it off) | `on`: OTLP logs (`log()`, pino, winston) |
278
357
  | `metrics` | `WATCHTOWER_METRICS` (`OTEL_METRICS_EXPORTER=none` also turns it off) | `on`: OTLP metrics, see below |
279
- | `redact` | | none; called for every span and log attribute |
358
+ | `redact` | | none; runs after URL scrubbing; called for every span and log attribute, every span event's attributes (`exception.message`, `exception.stacktrace`), the span name (key `span.name`), the status message (`status.message`) and log bodies (`log.body`) |
280
359
 
281
360
  Metrics: `init` sets the global meter provider, so `metrics.getMeter('app')` (re-exported from
282
361
  `@opentelemetry/api`) records to Watchtower. A periodic reader exports to `/v1/metrics` every
@@ -0,0 +1,7 @@
1
+ export interface CheckinTarget {
2
+ endpoint: string;
3
+ headers: Record<string, string>;
4
+ fetch: typeof fetch;
5
+ }
6
+ /** Send `in_progress`, run `fn`, then send `ok` or `error` with its duration. Check-in failures never affect `fn`; its result or error is passed through. */
7
+ export declare function checkin<T>(c: CheckinTarget, slug: string, fn: () => T | Promise<T>): Promise<T>;
@@ -0,0 +1,18 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.checkin = checkin;
4
+ /** Send `in_progress`, run `fn`, then send `ok` or `error` with its duration. Check-in failures never affect `fn`; its result or error is passed through. */
5
+ async function checkin(c, slug, fn) {
6
+ const send = (status, ms) => c.fetch(`${c.endpoint}/v1/checkins/${encodeURIComponent(slug)}?status=${status}${ms === undefined ? '' : `&duration_ms=${Math.min(ms, 86_400_000)}`}`, { method: 'POST', headers: c.headers }).catch(() => undefined);
7
+ await send('in_progress');
8
+ const t = Date.now();
9
+ try {
10
+ const r = await fn();
11
+ await send('ok', Date.now() - t);
12
+ return r;
13
+ }
14
+ catch (e) {
15
+ await send('error', Date.now() - t);
16
+ throw e;
17
+ }
18
+ }
@@ -0,0 +1,12 @@
1
+ /** Parse `k=v,k2=v2` (OTEL_RESOURCE_ATTRIBUTES / OTEL_EXPORTER_OTLP_HEADERS); values are percent-decoded. */
2
+ export declare function parseKv(s: string | undefined): Record<string, string>;
3
+ export interface OtelEnv {
4
+ endpoint?: string;
5
+ /** Header names are lower-cased by nobody: they are kept as written, except `Authorization` is matched case-insensitively. */
6
+ headers: Record<string, string>;
7
+ /** `Authorization: Bearer <key>` from OTEL_EXPORTER_OTLP_HEADERS, the key only. */
8
+ bearer?: string;
9
+ serviceName?: string;
10
+ resource: Record<string, string>;
11
+ }
12
+ export declare function otelEnv(env?: NodeJS.ProcessEnv): OtelEnv;
@@ -0,0 +1,37 @@
1
+ "use strict";
2
+ // Standard OTEL_* environment variables, used as fallbacks after the WT_* ones.
3
+ Object.defineProperty(exports, "__esModule", { value: true });
4
+ exports.parseKv = parseKv;
5
+ exports.otelEnv = otelEnv;
6
+ /** Parse `k=v,k2=v2` (OTEL_RESOURCE_ATTRIBUTES / OTEL_EXPORTER_OTLP_HEADERS); values are percent-decoded. */
7
+ function parseKv(s) {
8
+ const out = {};
9
+ for (const part of (s || '').split(',')) {
10
+ const i = part.indexOf('=');
11
+ if (i <= 0)
12
+ continue;
13
+ const dec = (x) => { try {
14
+ return decodeURIComponent(x.trim());
15
+ }
16
+ catch {
17
+ return x.trim();
18
+ } };
19
+ out[dec(part.slice(0, i))] = dec(part.slice(i + 1));
20
+ }
21
+ return out;
22
+ }
23
+ function otelEnv(env = process.env) {
24
+ const headers = parseKv(env.OTEL_EXPORTER_OTLP_HEADERS);
25
+ const authKey = Object.keys(headers).find((k) => k.toLowerCase() === 'authorization');
26
+ const auth = authKey ? headers[authKey] : undefined;
27
+ if (authKey)
28
+ delete headers[authKey];
29
+ const resource = parseKv(env.OTEL_RESOURCE_ATTRIBUTES);
30
+ return {
31
+ endpoint: env.OTEL_EXPORTER_OTLP_ENDPOINT || undefined,
32
+ headers,
33
+ bearer: auth && /^bearer\s+/i.test(auth) ? auth.replace(/^bearer\s+/i, '') : undefined,
34
+ serviceName: env.OTEL_SERVICE_NAME || resource['service.name'] || undefined,
35
+ resource,
36
+ };
37
+ }
@@ -2,7 +2,15 @@ export interface CaptureContext {
2
2
  /** false for crashes (uncaught); default true. Keys starting with `wt.` are dropped. */
3
3
  handled?: boolean;
4
4
  attributes?: Record<string, string | number | boolean | undefined>;
5
+ /**
6
+ * Exception replay: variables to show on the throwing frame. Node cannot read another frame's locals, so
7
+ * the caller names them. Secret-looking names are masked, values are shortened; the project must also turn
8
+ * on "exception replay" in its issue settings or the server drops them.
9
+ */
10
+ locals?: Record<string, unknown>;
5
11
  }
12
+ /** `exception.locals` for the innermost stack frame of `e`: the function and line come from its stack, the values from `locals`. */
13
+ export declare function localsAttribute(e: Error, locals: Record<string, unknown>): string | undefined;
6
14
  /** The slice of `process` the hooks need; tests pass an EventEmitter. */
7
15
  export interface ProcessLike {
8
16
  on(event: string, listener: (arg: unknown) => void): unknown;
@@ -1,11 +1,31 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.localsAttribute = localsAttribute;
3
4
  exports.dropReserved = dropReserved;
4
5
  exports.captureException = captureException;
5
6
  exports.installProcessHandlers = installProcessHandlers;
6
7
  // Error capture: an exception becomes an OTel span event (exception.*) with trace and span ids.
7
8
  const api_1 = require("@opentelemetry/api");
8
9
  const captured = new WeakMap(); // error object -> traceId, so framework + process hooks never double-report
10
+ const SENSITIVE = /pass|secret|token|api[-_]?key|auth|cookie|session|credit|card|ssn|private|bearer/i;
11
+ /** `exception.locals` for the innermost stack frame of `e`: the function and line come from its stack, the values from `locals`. */
12
+ function localsAttribute(e, locals) {
13
+ const m = /^\s+at (?:(\S+) \()?(.*?):(\d+):\d+\)?$/m.exec(e.stack || '');
14
+ const vars = {};
15
+ for (const [k, v] of Object.entries(locals).slice(0, 20)) {
16
+ let text;
17
+ try {
18
+ text = typeof v === 'string' ? v : JSON.stringify(v) ?? String(v);
19
+ }
20
+ catch {
21
+ text = '<unrepresentable>';
22
+ }
23
+ vars[k] = SENSITIVE.test(k) ? '[Filtered]' : text.slice(0, 120);
24
+ }
25
+ if (!Object.keys(vars).length)
26
+ return undefined;
27
+ return JSON.stringify([{ function: m?.[1] ?? '', filename: m?.[2] ?? '', lineno: m ? Number(m[3]) : undefined, vars }]);
28
+ }
9
29
  function dropReserved(attrs) {
10
30
  return Object.fromEntries(Object.entries(attrs || {}).filter(([k]) => !k.startsWith('wt.')));
11
31
  }
@@ -20,7 +40,10 @@ function captureException(err, ctx) {
20
40
  const active = api_1.trace.getActiveSpan();
21
41
  const span = active && active.isRecording() ? active : api_1.trace.getTracer('watchtower').startSpan('exception');
22
42
  span.setAttributes(attrs);
43
+ const replay = o.locals ? localsAttribute(e, o.locals) : undefined;
23
44
  span.recordException(e);
45
+ if (replay)
46
+ span.setAttribute('exception.locals', replay); // the OTel JS exception event takes no attributes
24
47
  span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: e.message });
25
48
  const traceId = span.spanContext().traceId;
26
49
  if (span !== active)
@@ -0,0 +1,2 @@
1
+ import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace';
2
+ export declare function filterExporter(inner: SpanExporter, keep: (s: ReadableSpan) => boolean): SpanExporter;
@@ -0,0 +1,16 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.filterExporter = filterExporter;
4
+ function filterExporter(inner, keep) {
5
+ return {
6
+ export(spans, done) {
7
+ const kept = spans.filter(keep);
8
+ if (kept.length)
9
+ inner.export(kept, done);
10
+ else
11
+ done({ code: 0 });
12
+ },
13
+ shutdown: () => inner.shutdown(),
14
+ forceFlush: () => inner.forceFlush?.() ?? Promise.resolve(),
15
+ };
16
+ }
@@ -2,11 +2,12 @@ import { inspect } from 'node:util';
2
2
  import { metrics, trace } from '@opentelemetry/api';
3
3
  import type { Tracer } from '@opentelemetry/api';
4
4
  import type { Resource } from '@opentelemetry/resources';
5
- import type { TracerProvider } from '@opentelemetry/sdk-trace';
5
+ import type { ReadableSpan, TracerProvider } from '@opentelemetry/sdk-trace';
6
6
  import type { LoggerProvider } from '@opentelemetry/sdk-logs';
7
7
  import type { MeterProvider } from '@opentelemetry/sdk-metrics';
8
8
  import { captureException } from './errors.js';
9
9
  import type { CaptureContext } from './errors.js';
10
+ import { RemoteSampler } from './sampling.js';
10
11
  import type { Profiler } from './profiling.js';
11
12
  export { captureException, metrics, trace };
12
13
  export { setCaptureRules, capturePayload } from './payload.js';
@@ -14,40 +15,71 @@ export type { CaptureRule } from './payload.js';
14
15
  export type { CaptureContext };
15
16
  export declare const DEFAULT_ENDPOINT = "http://localhost:4318";
16
17
  export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
18
+ /** code.filepath/code.lineno of the frame that called `log()` (stack line 0 is "Error", 1 is `log`, 2 the caller). */
19
+ export declare function callerOf(stack: string | undefined): Record<string, string | number>;
17
20
  export interface InitOptions {
18
- /** Ingest key; defaults to WT_INGEST_KEY. */
21
+ /** Ingest key; defaults to WT_INGEST_KEY, then a `Bearer` Authorization in OTEL_EXPORTER_OTLP_HEADERS. */
19
22
  apiKey?: string;
20
23
  /** Defaults to WT_ENVIRONMENT. */
21
24
  environment?: string;
22
- /** Defaults to WT_RELEASE. */
25
+ /** Sent as `service.version`; the server links an issue's first release by matching it to an existing release's version. Defaults to WT_RELEASE, then `service.version` in OTEL_RESOURCE_ATTRIBUTES. */
23
26
  release?: string;
24
27
  /** Hook uncaughtException / unhandledRejection (default true). */
25
28
  captureProcessErrors?: boolean;
26
- /** Replace the log exporter (tests). */
29
+ /** Replace the log exporter (tests); setting it turns logs on unless `logs` is false. Exported through a batch processor. */
27
30
  logExporter?: unknown;
28
31
  /** Export OTLP logs; defaults to WATCHTOWER_LOGS (on unless `off`; OTEL_LOGS_EXPORTER=none also turns it off). */
29
32
  logs?: boolean;
33
+ /** Stamp code.filepath/code.lineno of the `log()` caller (reads the stack); defaults to WATCHTOWER_LOG_CALLER=1. */
34
+ logCaller?: boolean;
30
35
  /** Export OTLP metrics; defaults to WATCHTOWER_METRICS (on unless `off`; OTEL_METRICS_EXPORTER=none also turns it off). */
31
36
  metrics?: boolean;
32
- /** Replace the metric exporter (tests). */
37
+ /** Replace the metric exporter (tests); setting it turns metrics on unless `metrics` is false. */
33
38
  metricExporter?: unknown;
34
- /** OTLP/HTTP base URL; defaults to WT_OTLP_ENDPOINT or http://localhost:4318. */
39
+ /** OTLP/HTTP base URL; defaults to WT_OTLP_ENDPOINT, then OTEL_EXPORTER_OTLP_ENDPOINT, then http://localhost:4318. */
35
40
  endpoint?: string;
36
41
  /** REST API base URL for getPrompt/score; defaults to WT_API_URL or endpoint. */
37
42
  apiUrl?: string;
38
43
  project?: string;
39
- /** Defaults to WT_SERVICE. */
44
+ /** Defaults to WT_SERVICE, then OTEL_SERVICE_NAME, then `service.name` in OTEL_RESOURCE_ATTRIBUTES, then `app`. */
40
45
  serviceName?: string;
41
- /** Resource attributes; keys starting with `wt.` are dropped. */
46
+ /** Resource attributes (on top of OTEL_RESOURCE_ATTRIBUTES); keys starting with `wt.` are dropped. */
42
47
  resource?: Record<string, string | number | boolean>;
43
- /** Called for every span attribute before export; return the value to keep. */
48
+ /**
49
+ * Called before export for every span attribute, every span event's and link's attributes (so `exception.message`
50
+ * and `exception.stacktrace`), the span name (key `span.name`), the status message (`status.message`) and each log
51
+ * body (`log.body`) and log attribute; return the value to keep.
52
+ */
44
53
  redact?: (key: string, value: unknown) => unknown;
45
54
  /** Directory for the offline buffer. */
46
55
  bufferDir?: string;
56
+ /** Apply the project's head sampling rules in the SDK, polled from /v1/sampling; defaults to WT_REMOTE_SAMPLING=1. Spans dropped here never reach the gateway, so its exact request counts see only what is kept. */
57
+ remoteSampling?: boolean;
58
+ /** Seconds between sampling polls; defaults to WT_SAMPLING_INTERVAL_S or 30. */
59
+ samplingIntervalS?: number;
60
+ /** Stamp code.filepath / code.lineno / code.function on spans (the code that started the span); defaults to WT_CODE_ORIGIN=1. */
61
+ codeOrigin?: boolean;
47
62
  /** Fetch the service's payload capture rules (APM-016) and record bodies/GraphQL where a rule matches; defaults to WT_CAPTURE_RULES=1. */
48
63
  captureRules?: boolean;
49
64
  /** Replace the span exporter (tests). */
50
65
  exporter?: unknown;
66
+ /**
67
+ * Scrub URLs on every span, including spans other libraries create (Next.js, node:http, fetch): the query string is dropped
68
+ * (`url.query` removed) and path segments that look like secrets or ids (>= 24 chars, or >= 10 chars mixing letters and digits,
69
+ * UUIDs included) become `:redacted`, in `http.target`, `url.full`, `url.path`, `http.url` and URLs in span names.
70
+ * `http.route` is kept. Default true; `false` records URLs as the instrumentation produced them.
71
+ */
72
+ urlScrubbing?: boolean;
73
+ /** Return false to drop a finished span before export (the `/next` entry uses it for `nextInternals`). */
74
+ spanFilter?: (span: ReadableSpan) => boolean;
75
+ /**
76
+ * Patch node:http, fetch (undici), pg and ioredis for those whose `@opentelemetry/instrumentation-*` peer is installed; defaults to on unless WT_INSTRUMENT=0.
77
+ * `'auto'` (or WT_INSTRUMENT=auto) also instruments whichever of postgres.js, better-sqlite3 and mysql2 is installed and logs one line naming what it patched
78
+ * (`instrumentLog: false` or WT_INSTRUMENT_LOG=0 silences it). `init` only: use the `/register` preload so it runs before the app imports them.
79
+ */
80
+ instrument?: boolean | 'auto';
81
+ /** Print the one-line list of what `instrument: 'auto'` patched (default true). */
82
+ instrumentLog?: boolean;
51
83
  fetch?: typeof fetch;
52
84
  }
53
85
  export interface EvalRow {
@@ -77,9 +109,10 @@ export declare class Client {
77
109
  readonly project: string | undefined;
78
110
  readonly headers: {
79
111
  Authorization: string;
80
- };
112
+ } & Record<string, string>;
81
113
  readonly fetch: typeof fetch;
82
114
  readonly redact: InitOptions['redact'];
115
+ private readonly logCaller;
83
116
  readonly provider: TracerProvider;
84
117
  readonly resource: Resource;
85
118
  readonly tracer: Tracer;
@@ -89,11 +122,15 @@ export declare class Client {
89
122
  readonly meterProvider?: MeterProvider;
90
123
  private readonly stopRuntime;
91
124
  uninstall?: () => void;
125
+ /** Set when remote sampling is on. */
126
+ remoteSampler?: RemoteSampler;
92
127
  /** Set when WT_PROFILING=1 started the continuous profiler. */
93
128
  profiler?: Promise<Profiler | undefined>;
94
129
  constructor(opts: InitOptions);
95
130
  /** Emit an OTLP log record; trace and span ids come from the active context. */
96
131
  log(level: LogLevel, body: string, attributes?: Record<string, unknown>): void;
132
+ /** Run `fn` as a cron / scheduler job with check-ins to the monitor `monitorSlug` (needs the `ingest:checkins` key scope): `in_progress`, then `ok` or `error` with the duration. */
133
+ checkin<T>(monitorSlug: string, fn: () => T | Promise<T>): Promise<T>;
97
134
  forceFlush(): Promise<unknown>;
98
135
  toJSON(): {
99
136
  endpoint: string;
@@ -115,6 +152,7 @@ export declare class Client {
115
152
  shutdown(): Promise<void>;
116
153
  }
117
154
  export declare function init(opts: InitOptions): Client;
155
+ export declare const checkin: <T>(slug: string, fn: () => T | Promise<T>) => Promise<T>;
118
156
  export declare const flush: () => Promise<unknown>;
119
157
  export declare const log: (l: LogLevel, b: string, a?: Record<string, unknown>) => void;
120
158
  export declare const getPrompt: (id: string) => Promise<unknown>;