@watchtowerobservability/node 0.6.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 (54) hide show
  1. package/README.md +51 -3
  2. package/dist/cjs/checkin.d.ts +7 -0
  3. package/dist/cjs/checkin.js +18 -0
  4. package/dist/cjs/filter.d.ts +2 -0
  5. package/dist/cjs/filter.js +16 -0
  6. package/dist/cjs/index.d.ts +21 -3
  7. package/dist/cjs/index.js +34 -6
  8. package/dist/cjs/instrument.d.ts +5 -2
  9. package/dist/cjs/instrument.js +26 -3
  10. package/dist/cjs/integrations/db.d.ts +3 -0
  11. package/dist/cjs/integrations/db.js +4 -1
  12. package/dist/cjs/integrations/next-build.d.ts +31 -0
  13. package/dist/cjs/integrations/next-build.js +95 -0
  14. package/dist/cjs/integrations/next-tunnel.d.ts +14 -0
  15. package/dist/cjs/integrations/next-tunnel.js +52 -0
  16. package/dist/cjs/integrations/next.d.ts +21 -1
  17. package/dist/cjs/integrations/next.js +28 -2
  18. package/dist/cjs/load.js +1 -0
  19. package/dist/cjs/next-sourcemaps-cli.d.ts +2 -0
  20. package/dist/cjs/next-sourcemaps-cli.js +9 -0
  21. package/dist/cjs/scrub.d.ts +7 -0
  22. package/dist/cjs/scrub.js +39 -0
  23. package/dist/cjs/shutdown.d.ts +14 -0
  24. package/dist/cjs/shutdown.js +26 -0
  25. package/dist/cjs/sql.js +11 -1
  26. package/dist/cjs/version.d.ts +2 -0
  27. package/dist/cjs/version.js +5 -0
  28. package/dist/esm/checkin.d.ts +7 -0
  29. package/dist/esm/checkin.js +15 -0
  30. package/dist/esm/filter.d.ts +2 -0
  31. package/dist/esm/filter.js +13 -0
  32. package/dist/esm/index.d.ts +21 -3
  33. package/dist/esm/index.js +32 -5
  34. package/dist/esm/instrument.d.ts +5 -2
  35. package/dist/esm/instrument.js +26 -3
  36. package/dist/esm/integrations/db.d.ts +3 -0
  37. package/dist/esm/integrations/db.js +5 -2
  38. package/dist/esm/integrations/next-build.d.ts +31 -0
  39. package/dist/esm/integrations/next-build.js +58 -0
  40. package/dist/esm/integrations/next-tunnel.d.ts +14 -0
  41. package/dist/esm/integrations/next-tunnel.js +49 -0
  42. package/dist/esm/integrations/next.d.ts +21 -1
  43. package/dist/esm/integrations/next.js +22 -1
  44. package/dist/esm/load.js +2 -0
  45. package/dist/esm/next-sourcemaps-cli.d.ts +2 -0
  46. package/dist/esm/next-sourcemaps-cli.js +7 -0
  47. package/dist/esm/scrub.d.ts +7 -0
  48. package/dist/esm/scrub.js +34 -0
  49. package/dist/esm/shutdown.d.ts +14 -0
  50. package/dist/esm/shutdown.js +23 -0
  51. package/dist/esm/sql.js +11 -1
  52. package/dist/esm/version.d.ts +2 -0
  53. package/dist/esm/version.js +2 -0
  54. package/package.json +8 -1
package/README.md CHANGED
@@ -37,10 +37,23 @@ 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.
41
46
 
42
47
  ## Auto-instrumentation and preload
43
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
+
44
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:
45
58
 
46
59
  ```sh
@@ -61,6 +74,31 @@ export const register = makeRegister({ redact: (k, v) => v }); // any InitOpti
61
74
  export { onRequestError } from '@watchtowerobservability/node/next';
62
75
  ```
63
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
+
64
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.
65
103
 
66
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.
@@ -154,6 +192,15 @@ active span, following the OTel database conventions: `db.system.name`, `db.oper
154
192
  server and spans join the Datastores views. The algorithm is specified in
155
193
  `docs/product/instrumentation/sql-normalization.md` and exported at `.../sql`.
156
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
+
157
204
  Statement text and parameters are never recorded by default. Pass `{ queryText: true }` (or set
158
205
  `WATCHTOWER_DB_QUERY_TEXT=1`) to add `db.query.text`, which is then the literal-free text. A
159
206
  statement that runs more than 5 times under one parent span gets `db.n_plus_one=true` and
@@ -303,11 +350,12 @@ See `docs/product/security/app-api-protection.md`.
303
350
  | `environment` | `WT_ENVIRONMENT` | unset |
304
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 |
305
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 |
306
- | `instrument` | `WT_INSTRUMENT` | `on` for installed http / undici / pg / ioredis instrumentations |
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 |
307
355
  | `bufferDir` | | no offline buffer (spans, logs and metrics spool to `traces/`, `logs/` and `metrics/`, 500 batches each) |
308
356
  | `logs` | `WATCHTOWER_LOGS` (`OTEL_LOGS_EXPORTER=none` also turns it off) | `on`: OTLP logs (`log()`, pino, winston) |
309
357
  | `metrics` | `WATCHTOWER_METRICS` (`OTEL_METRICS_EXPORTER=none` also turns it off) | `on`: OTLP metrics, see below |
310
- | `redact` | | none; 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`) |
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`) |
311
359
 
312
360
  Metrics: `init` sets the global meter provider, so `metrics.getMeter('app')` (re-exported from
313
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,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,7 +2,7 @@ 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';
@@ -63,8 +63,23 @@ export interface InitOptions {
63
63
  captureRules?: boolean;
64
64
  /** Replace the span exporter (tests). */
65
65
  exporter?: unknown;
66
- /** Patch node:http, fetch (undici), pg and ioredis for those whose `@opentelemetry/instrumentation-*` peer is installed; defaults to on unless WT_INSTRUMENT=0. `init` only: use the `/register` preload so it runs before the app imports them. */
67
- instrument?: boolean;
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;
68
83
  fetch?: typeof fetch;
69
84
  }
70
85
  export interface EvalRow {
@@ -114,6 +129,8 @@ export declare class Client {
114
129
  constructor(opts: InitOptions);
115
130
  /** Emit an OTLP log record; trace and span ids come from the active context. */
116
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>;
117
134
  forceFlush(): Promise<unknown>;
118
135
  toJSON(): {
119
136
  endpoint: string;
@@ -135,6 +152,7 @@ export declare class Client {
135
152
  shutdown(): Promise<void>;
136
153
  }
137
154
  export declare function init(opts: InitOptions): Client;
155
+ export declare const checkin: <T>(slug: string, fn: () => T | Promise<T>) => Promise<T>;
138
156
  export declare const flush: () => Promise<unknown>;
139
157
  export declare const log: (l: LogLevel, b: string, a?: Record<string, unknown>) => void;
140
158
  export declare const getPrompt: (id: string) => Promise<unknown>;
package/dist/cjs/index.js CHANGED
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.shutdown = exports.observe = exports.evaluateResume = exports.evaluate = exports.score = exports.getPrompt = exports.log = exports.flush = exports.Client = exports.DEFAULT_ENDPOINT = exports.capturePayload = exports.setCaptureRules = exports.trace = exports.metrics = exports.captureException = void 0;
36
+ exports.shutdown = exports.observe = exports.evaluateResume = exports.evaluate = exports.score = exports.getPrompt = exports.log = exports.flush = exports.checkin = exports.Client = exports.DEFAULT_ENDPOINT = exports.capturePayload = exports.setCaptureRules = exports.trace = exports.metrics = exports.captureException = void 0;
37
37
  exports.callerOf = callerOf;
38
38
  exports.safeResource = safeResource;
39
39
  exports.init = init;
@@ -47,6 +47,11 @@ const load_js_1 = require("./load.js");
47
47
  const env_js_1 = require("./env.js");
48
48
  const instrument_js_1 = require("./instrument.js");
49
49
  const redact_js_1 = require("./redact.js");
50
+ const scrub_js_1 = require("./scrub.js");
51
+ const filter_js_1 = require("./filter.js");
52
+ const checkin_js_1 = require("./checkin.js");
53
+ const shutdown_js_1 = require("./shutdown.js");
54
+ const version_js_1 = require("./version.js");
50
55
  const buffer_js_1 = require("./buffer.js");
51
56
  const metrics_js_1 = require("./metrics.js");
52
57
  const nodePath = __importStar(require("node:path"));
@@ -107,8 +112,15 @@ class Client {
107
112
  const environment = o.environment || env.WT_ENVIRONMENT || oe.resource['deployment.environment.name'];
108
113
  const release = o.release || env.WT_RELEASE || oe.resource['service.version'];
109
114
  // the OTel SDK packages are optional peers, loaded here (not at import time) with a clear error when missing
110
- const { resourceFromAttributes } = (0, load_js_1.need)('@opentelemetry/resources');
115
+ const { resourceFromAttributes, defaultResource } = (0, load_js_1.need)('@opentelemetry/resources');
116
+ // the SDK's own telemetry.sdk.* (name, language, version): a bare resourceFromAttributes does not add them
117
+ const sdk = (defaultResource().attributes ?? {});
111
118
  const resource = resourceFromAttributes({
119
+ 'telemetry.sdk.name': String(sdk['telemetry.sdk.name'] ?? 'opentelemetry'),
120
+ 'telemetry.sdk.language': String(sdk['telemetry.sdk.language'] ?? 'nodejs'),
121
+ 'telemetry.sdk.version': String(sdk['telemetry.sdk.version'] ?? 'unknown'),
122
+ 'telemetry.distro.name': 'watchtower',
123
+ 'telemetry.distro.version': version_js_1.VERSION,
112
124
  ...safeResource(oe.resource),
113
125
  'service.name': o.serviceName || env.WT_SERVICE || oe.serviceName || 'app',
114
126
  ...(environment ? { 'deployment.environment.name': environment } : {}),
@@ -127,7 +139,9 @@ class Client {
127
139
  if (o.bufferDir)
128
140
  exporter = new buffer_js_1.SpoolExporter(exporter, nodePath.join(o.bufferDir, 'traces'), url, this.headers, this.fetch);
129
141
  }
130
- // the redactor runs first, so the batch processor exports redacted attributes
142
+ if (o.spanFilter)
143
+ exporter = (0, filter_js_1.filterExporter)(exporter, o.spanFilter);
144
+ // the scrubber and redactor run first, so the batch processor exports scrubbed attributes (the user's `redact` sees scrubbed URLs)
131
145
  const { BatchSpanProcessor, TracerProvider: TP } = (0, load_js_1.need)('@opentelemetry/sdk-trace');
132
146
  let sampler;
133
147
  if (o.remoteSampling ?? env.WT_REMOTE_SAMPLING === '1') {
@@ -143,6 +157,7 @@ class Client {
143
157
  ...(sampler ? { sampler: sampler } : {}),
144
158
  spanProcessors: [
145
159
  ...(o.codeOrigin ?? env.WT_CODE_ORIGIN === '1' ? [(0, origin_js_1.codeOrigin)()] : []),
160
+ ...(o.urlScrubbing ?? true ? [(0, scrub_js_1.urlScrubber)()] : []),
146
161
  ...(o.redact ? [(0, redact_js_1.redactor)(o.redact)] : []),
147
162
  new BatchSpanProcessor({ exporter }),
148
163
  ],
@@ -190,6 +205,10 @@ class Client {
190
205
  attributes: attrs,
191
206
  });
192
207
  }
208
+ /** 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. */
209
+ checkin(monitorSlug, fn) {
210
+ return (0, checkin_js_1.checkin)(this, monitorSlug, fn);
211
+ }
193
212
  forceFlush() {
194
213
  return Promise.all([this.provider.forceFlush(), this.loggerProvider.forceFlush(), this.meterProvider?.forceFlush()]);
195
214
  }
@@ -329,8 +348,13 @@ function init(opts) {
329
348
  const c = new Client(opts);
330
349
  state.current = c;
331
350
  registerGlobals(c);
332
- if (opts?.instrument ?? !['0', 'off', 'false', 'no'].includes((process.env.WT_INSTRUMENT || '').trim().toLowerCase())) {
333
- (0, instrument_js_1.instrumentAll)({ tracerProvider: c.provider, meterProvider: c.meterProvider }, [c.endpoint, c.apiUrl]);
351
+ const env = (process.env.WT_INSTRUMENT || '').trim().toLowerCase();
352
+ const mode = opts?.instrument ?? (env === 'auto' ? 'auto' : !['0', 'off', 'false', 'no'].includes(env));
353
+ if (mode) {
354
+ const names = (0, instrument_js_1.instrumentAll)({ tracerProvider: c.provider, meterProvider: c.meterProvider }, [c.endpoint, c.apiUrl], mode === 'auto');
355
+ if (mode === 'auto' && (opts?.instrumentLog ?? !['0', 'off', 'false', 'no'].includes((process.env.WT_INSTRUMENT_LOG || '').trim().toLowerCase()))) {
356
+ console.info(`[watchtower] instrumented: ${names.map((n) => n.replace('@opentelemetry/instrumentation-', '')).join(', ') || 'nothing (no supported package found)'}`);
357
+ }
334
358
  }
335
359
  if (process.env.WT_PROFILING === '1') {
336
360
  const attrs = c.resource.attributes;
@@ -342,7 +366,9 @@ function init(opts) {
342
366
  }).catch(() => undefined); // best effort: never break init
343
367
  }
344
368
  if ((opts || {}).captureProcessErrors !== false) {
345
- c.uninstall = (0, errors_js_1.installProcessHandlers)(() => c.forceFlush());
369
+ const offErrors = (0, errors_js_1.installProcessHandlers)(() => c.forceFlush());
370
+ const offSignals = (0, shutdown_js_1.installSignalFlush)(() => c.forceFlush());
371
+ c.uninstall = () => { offErrors(); offSignals(); };
346
372
  }
347
373
  return c;
348
374
  }
@@ -351,6 +377,8 @@ function need() {
351
377
  throw new Error('watchtower.init() has not been called');
352
378
  return state.current;
353
379
  }
380
+ const checkin = (slug, fn) => need().checkin(slug, fn);
381
+ exports.checkin = checkin;
354
382
  const flush = () => (state.current ? state.current.forceFlush() : Promise.resolve());
355
383
  exports.flush = flush;
356
384
  const log = (l, b, a) => need().log(l, b, a);
@@ -2,6 +2,9 @@ interface Providers {
2
2
  tracerProvider: unknown;
3
3
  meterProvider?: unknown;
4
4
  }
5
- /** Register whichever of the four instrumentations is installed. Returns the package names that were enabled. */
6
- export declare function instrumentAll(p: Providers, selfUrls: string[]): string[];
5
+ /**
6
+ * Register whichever of the OTel instrumentations is installed (http, undici, pg, ioredis; with `auto` also mysql2) and,
7
+ * with `auto`, patch postgres.js and better-sqlite3 when installed. Returns the names that were enabled.
8
+ */
9
+ export declare function instrumentAll(p: Providers, selfUrls: string[], auto?: boolean): string[];
7
10
  export {};
@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.instrumentAll = instrumentAll;
4
4
  // Auto-instrumentation: node:http, fetch (undici), pg and ioredis, each only when its optional peer package is installed.
5
5
  const load_js_1 = require("./load.js");
6
+ const sqlite_js_1 = require("./integrations/sqlite.js");
7
+ const postgres_js_1 = require("./integrations/postgres.js");
6
8
  const ENTRIES = [
7
9
  {
8
10
  pkg: '@opentelemetry/instrumentation-http', ctor: 'HttpInstrumentation',
@@ -15,15 +17,24 @@ const ENTRIES = [
15
17
  },
16
18
  { pkg: '@opentelemetry/instrumentation-pg', ctor: 'PgInstrumentation', opts: () => ({}) },
17
19
  { pkg: '@opentelemetry/instrumentation-ioredis', ctor: 'IORedisInstrumentation', opts: () => ({}) },
20
+ { pkg: '@opentelemetry/instrumentation-mysql2', ctor: 'MySQL2Instrumentation', opts: () => ({}), auto: true },
18
21
  ];
19
- /** Register whichever of the four instrumentations is installed. Returns the package names that were enabled. */
20
- function instrumentAll(p, selfUrls) {
22
+ /** Drivers patched in place (no OTel package): `instrument: 'auto'` only. Each loads the app's installed copy or is skipped. */
23
+ const DRIVERS = [
24
+ { name: 'postgres.js', run: () => { (0, load_js_1.load)('postgres'); (0, postgres_js_1.instrumentPostgres)(); } }, // only when `postgres` is installed
25
+ { name: 'better-sqlite3', run: () => (0, sqlite_js_1.instrumentBetterSqlite3)((0, load_js_1.load)('better-sqlite3')) },
26
+ ];
27
+ /**
28
+ * Register whichever of the OTel instrumentations is installed (http, undici, pg, ioredis; with `auto` also mysql2) and,
29
+ * with `auto`, patch postgres.js and better-sqlite3 when installed. Returns the names that were enabled.
30
+ */
31
+ function instrumentAll(p, selfUrls, auto = false) {
21
32
  let registerInstrumentations;
22
33
  try {
23
34
  ({ registerInstrumentations } = (0, load_js_1.load)('@opentelemetry/instrumentation'));
24
35
  }
25
36
  catch {
26
- return []; // optional peer not installed
37
+ return auto ? patchDrivers([]) : []; // optional peer not installed
27
38
  }
28
39
  const self = selfUrls.flatMap((u) => { try {
29
40
  return [new URL(u)];
@@ -34,6 +45,8 @@ function instrumentAll(p, selfUrls) {
34
45
  const found = [];
35
46
  const names = [];
36
47
  for (const e of ENTRIES) {
48
+ if (e.auto && !auto)
49
+ continue;
37
50
  try {
38
51
  const Ctor = (0, load_js_1.load)(e.pkg)[e.ctor];
39
52
  if (Ctor) {
@@ -47,5 +60,15 @@ function instrumentAll(p, selfUrls) {
47
60
  }
48
61
  if (found.length)
49
62
  registerInstrumentations({ instrumentations: found, tracerProvider: p.tracerProvider, meterProvider: p.meterProvider });
63
+ return auto ? patchDrivers(names) : names;
64
+ }
65
+ function patchDrivers(names) {
66
+ for (const d of DRIVERS) {
67
+ try {
68
+ d.run();
69
+ names.push(d.name);
70
+ }
71
+ catch { /* driver not installed */ }
72
+ }
50
73
  return names;
51
74
  }
@@ -5,6 +5,9 @@ export interface DbOptions {
5
5
  /** Flag a statement run more than this many times under one parent span. Default:
6
6
  * `WATCHTOWER_DB_N_PLUS_ONE` or 5; 0 turns it off. */
7
7
  nPlusOne?: number;
8
+ /** Record a query only when a span is active (a request, job or `observe` span). Default true (`WATCHTOWER_DB_REQUIRE_PARENT=0`
9
+ * turns it off): startup DDL, migrations and polling loops run outside any span and would otherwise each become a root trace. */
10
+ requireParent?: boolean;
8
11
  }
9
12
  export interface DbOp {
10
13
  /** `db.system.name`, e.g. `sqlite`. */
@@ -76,6 +76,10 @@ function repeats(parent, key) {
76
76
  }
77
77
  /** A CLIENT span for `op` (not made active): summary, hash, N+1 hint. Prefer `traced`. */
78
78
  function startDbSpan(op, opts, parent, startTime) {
79
+ const p = api_1.trace.getSpan(parent)?.spanContext();
80
+ const requireParent = opts?.requireParent ?? !['0', 'false', 'off', 'no'].includes((process.env.WATCHTOWER_DB_REQUIRE_PARENT || '').trim().toLowerCase());
81
+ if (requireParent && !(p && api_1.trace.isSpanContextValid(p)))
82
+ return api_1.trace.wrapSpanContext(api_1.INVALID_SPAN_CONTEXT); // non-recording: nothing is exported
79
83
  const attrs = { 'db.system.name': op.system, ...op.attributes };
80
84
  let { operation, collection } = op;
81
85
  let name = [operation, collection].filter(Boolean).join(' ') || op.system;
@@ -98,7 +102,6 @@ function startDbSpan(op, opts, parent, startTime) {
98
102
  attrs['db.collection.name'] = collection;
99
103
  if (op.namespace)
100
104
  attrs['db.namespace'] = op.namespace;
101
- const p = api_1.trace.getSpan(parent)?.spanContext();
102
105
  const max = threshold(opts);
103
106
  if (p && max > 0) {
104
107
  const n = repeats(p.spanId, key);
@@ -0,0 +1,31 @@
1
+ export interface SourcemapOptions {
2
+ /** Directory holding the client build; default `.next/static`. */
3
+ dir?: string;
4
+ /** Default WT_API_URL, then https://api.watchtower.observer. */
5
+ apiUrl?: string;
6
+ /** A key with scope `ci:write` (it covers releases and artifacts; `admin:write` also works). Default WT_API_KEY. */
7
+ apiKey?: string;
8
+ /** Project id or slug the maps belong to. Default WT_PROJECT. */
9
+ project?: string;
10
+ /** Release version: must equal the `release` the browser SDK reports. Default WT_RELEASE. */
11
+ release?: string;
12
+ /** Keep the .map files after a successful upload (default: delete them so they are never served). */
13
+ keep?: boolean;
14
+ fetch?: typeof fetch;
15
+ log?: (line: string) => void;
16
+ }
17
+ type NextConfig = Record<string, unknown>;
18
+ type ConfigOrFn = NextConfig | ((...a: unknown[]) => NextConfig | Promise<NextConfig>);
19
+ /**
20
+ * `module.exports = withWatchtower(nextConfig, { sourcemaps: true })`: turns on `productionBrowserSourceMaps` so
21
+ * `next build` writes client maps (works with webpack and Turbopack). Then run `wt-next-sourcemaps` after the build
22
+ * (`"build": "next build && wt-next-sourcemaps"`) to upload them and delete the .map files from `.next/static`.
23
+ */
24
+ export declare function withWatchtower(config?: ConfigOrFn, opts?: {
25
+ sourcemaps?: boolean;
26
+ }): ConfigOrFn;
27
+ /** Upload every `.map` under `dir` as `_next/static/<path>` for the release, then delete them. Throws (leaving the files) when an upload fails. */
28
+ export declare function uploadSourcemaps(o?: SourcemapOptions): Promise<{
29
+ uploaded: number;
30
+ }>;
31
+ export {};
@@ -0,0 +1,95 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.withWatchtower = withWatchtower;
37
+ exports.uploadSourcemaps = uploadSourcemaps;
38
+ // Build-time helpers for Next.js: `withWatchtower` (next.config) and `uploadSourcemaps` (after `next build`).
39
+ const fs = __importStar(require("node:fs"));
40
+ const nodePath = __importStar(require("node:path"));
41
+ /**
42
+ * `module.exports = withWatchtower(nextConfig, { sourcemaps: true })`: turns on `productionBrowserSourceMaps` so
43
+ * `next build` writes client maps (works with webpack and Turbopack). Then run `wt-next-sourcemaps` after the build
44
+ * (`"build": "next build && wt-next-sourcemaps"`) to upload them and delete the .map files from `.next/static`.
45
+ */
46
+ function withWatchtower(config = {}, opts = {}) {
47
+ const apply = (c) => (opts.sourcemaps ? { ...c, productionBrowserSourceMaps: true } : c);
48
+ if (typeof config !== 'function')
49
+ return apply(config);
50
+ return async (...a) => apply(await config(...a));
51
+ }
52
+ function* maps(dir) {
53
+ for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
54
+ const p = nodePath.join(dir, e.name);
55
+ if (e.isDirectory())
56
+ yield* maps(p);
57
+ else if (e.name.endsWith('.map'))
58
+ yield p;
59
+ }
60
+ }
61
+ /** Upload every `.map` under `dir` as `_next/static/<path>` for the release, then delete them. Throws (leaving the files) when an upload fails. */
62
+ async function uploadSourcemaps(o = {}) {
63
+ const env = process.env;
64
+ const key = o.apiKey || env.WT_API_KEY;
65
+ const project = o.project || env.WT_PROJECT;
66
+ const release = o.release || env.WT_RELEASE;
67
+ if (!key)
68
+ throw new Error('WT_API_KEY is required (a key with scope ci:write)');
69
+ if (!project)
70
+ throw new Error('WT_PROJECT (project id) is required');
71
+ if (!release)
72
+ throw new Error('WT_RELEASE is required');
73
+ const dir = nodePath.resolve(o.dir || '.next/static');
74
+ const f = o.fetch || fetch;
75
+ const log = o.log || (() => { });
76
+ const root = `${(o.apiUrl || env.WT_API_URL || 'https://api.watchtower.observer').replace(/\/+$/, '')}/v1/projects/${encodeURIComponent(project)}`;
77
+ const call = async (path, init, okStatus = []) => {
78
+ const res = await f(root + path, { ...init, headers: { authorization: `Bearer ${key}`, ...init.headers } });
79
+ if (!res.ok && !okStatus.includes(res.status))
80
+ throw new Error(`watchtower ${init.method} ${path.split('?')[0]} -> HTTP ${res.status}`);
81
+ };
82
+ const files = fs.existsSync(dir) ? [...maps(dir)] : [];
83
+ await call('/releases', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ version: release }) }, [409]); // 409: exists
84
+ for (const file of files) {
85
+ const name = `_next/static/${nodePath.relative(dir, file).split(nodePath.sep).join('/')}`;
86
+ await call(`/artifacts?${new URLSearchParams({ kind: 'sourcemap', name, release })}`, {
87
+ method: 'POST', headers: { 'content-type': 'application/octet-stream' }, body: new Uint8Array(fs.readFileSync(file)),
88
+ });
89
+ }
90
+ if (!o.keep)
91
+ for (const file of files)
92
+ fs.rmSync(file);
93
+ log(`uploaded ${files.length} source maps for release ${release}${o.keep ? '' : ' and deleted them'}`);
94
+ return { uploaded: files.length };
95
+ }
@@ -0,0 +1,14 @@
1
+ export interface TunnelOptions {
2
+ /** Edge base URL the requests are forwarded to. */
3
+ endpoint: string;
4
+ /** Route prefix to strip; default `/api/wt`. */
5
+ basePath?: string;
6
+ /** Request body cap in bytes; default 1 MiB (over it: 413). */
7
+ maxBodyBytes?: number;
8
+ fetch?: typeof fetch;
9
+ }
10
+ /** Next route handlers `{ GET, POST }` forwarding allow-listed RUM paths to the edge. Only the publishable key (`?k=` or a `wtp_` bearer) is forwarded as auth; cookies and other headers are not. */
11
+ export declare function tunnelHandler(o: TunnelOptions): {
12
+ GET: (r: Request) => Promise<Response>;
13
+ POST: (r: Request) => Promise<Response>;
14
+ };
@@ -0,0 +1,52 @@
1
+ "use strict";
2
+ // First-party tunnel for browser telemetry (ad blockers block third-party telemetry hosts).
3
+ // app/api/wt/[...path]/route.ts: export const { GET, POST } = tunnelHandler({ endpoint: process.env.WT_EDGE_URL! });
4
+ // Browser SDK: init({ endpoint: '/api/wt', publishableKey: 'wtp_...' }).
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.tunnelHandler = tunnelHandler;
7
+ // only what the browser SDK calls: /v1/rum/*, /v1/replay/<session>/chunks and /v1/logs
8
+ const ALLOWED = /^\/v1\/(rum\/[A-Za-z0-9/_-]+|replay\/[A-Za-z0-9_-]+\/chunks|logs)$/;
9
+ const FORWARD = ['content-type', 'content-encoding', 'user-agent'];
10
+ /** Next route handlers `{ GET, POST }` forwarding allow-listed RUM paths to the edge. Only the publishable key (`?k=` or a `wtp_` bearer) is forwarded as auth; cookies and other headers are not. */
11
+ function tunnelHandler(o) {
12
+ const base = (o.basePath ?? '/api/wt').replace(/\/+$/, '');
13
+ const max = o.maxBodyBytes ?? 1024 * 1024;
14
+ const edge = o.endpoint.replace(/\/+$/, '');
15
+ const send = o.fetch ?? fetch;
16
+ const handle = async (req) => {
17
+ const url = new URL(req.url);
18
+ const path = url.pathname.startsWith(base) ? url.pathname.slice(base.length) : url.pathname;
19
+ if (!ALLOWED.test(path) || path.includes('..'))
20
+ return new Response('not found', { status: 404 });
21
+ const headers = {};
22
+ for (const h of FORWARD) {
23
+ const v = req.headers.get(h);
24
+ if (v)
25
+ headers[h] = v;
26
+ }
27
+ const bearer = /^Bearer (wtp_\S+)$/.exec(req.headers.get('authorization') ?? '');
28
+ if (bearer)
29
+ headers.authorization = `Bearer ${bearer[1]}`;
30
+ const k = url.searchParams.get('k');
31
+ let body;
32
+ if (req.method === 'POST') {
33
+ if (Number(req.headers.get('content-length') ?? 0) > max)
34
+ return new Response('payload too large', { status: 413 });
35
+ body = await req.arrayBuffer();
36
+ if (body.byteLength > max)
37
+ return new Response('payload too large', { status: 413 });
38
+ }
39
+ try {
40
+ const res = await send(`${edge}${path}${k ? `?k=${encodeURIComponent(k)}` : ''}`, { method: req.method, headers, body });
41
+ const out = new Headers();
42
+ const ct = res.headers.get('content-type');
43
+ if (ct)
44
+ out.set('content-type', ct);
45
+ return new Response(res.status === 204 ? null : await res.arrayBuffer(), { status: res.status, headers: out });
46
+ }
47
+ catch {
48
+ return new Response('bad gateway', { status: 502 });
49
+ }
50
+ };
51
+ return { GET: handle, POST: handle };
52
+ }
@@ -1,6 +1,26 @@
1
+ import type { ReadableSpan } from '@opentelemetry/sdk-trace';
1
2
  import * as wt from '../index.js';
3
+ export { withWatchtower, uploadSourcemaps } from './next-build.js';
4
+ export type { SourcemapOptions } from './next-build.js';
5
+ export { tunnelHandler } from './next-tunnel.js';
6
+ export type { TunnelOptions } from './next-tunnel.js';
7
+ export interface NextOptions extends wt.InitOptions {
8
+ /**
9
+ * Next.js's own spans (`next.span_type` set: load route module, prepare route module, resolve page components, start
10
+ * response, middleware, generateMetadata ...). `"sample"` (default) keeps `nextInternalsRate` of them, `"drop"` none,
11
+ * `"keep"` all. Request (`BaseServer.handleRequest`), route handler, render, server action and fetch spans, every
12
+ * SERVER/CLIENT span and every errored span are always kept. A dropped span's children stay in the trace.
13
+ */
14
+ nextInternals?: 'drop' | 'sample' | 'keep';
15
+ /** Share of internal spans kept with `nextInternals: "sample"`; default 0.1. */
16
+ nextInternalsRate?: number;
17
+ }
18
+ /** Whether `span` is one of Next's internal spans (not a request, route handler, render, server action or fetch). */
19
+ export declare function isNextInternal(span: ReadableSpan): boolean;
20
+ /** The `spanFilter` for a `nextInternals` mode; `rand` is injectable for tests. */
21
+ export declare function nextInternalsFilter(mode?: 'drop' | 'sample' | 'keep', rate?: number, rand?: () => number): (s: ReadableSpan) => boolean;
2
22
  /** Build a Next.js instrumentation `register` that passes `options` to `init`; no-op off the Node.js runtime or without a key. */
3
- export declare function makeRegister(options?: wt.InitOptions): () => Promise<void>;
23
+ export declare function makeRegister(options?: NextOptions): () => Promise<void>;
4
24
  /** Next.js instrumentation hook: init from WT_* env on the Node.js runtime; no-op without WT_INGEST_KEY. */
5
25
  export declare const register: () => Promise<void>;
6
26
  /** Next.js onRequestError: server render, route handler and server action errors. */