@watchtowerobservability/node 0.7.4 → 0.7.5

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 (89) hide show
  1. package/CHANGELOG.md +36 -1
  2. package/README.md +96 -12
  3. package/dist/cjs/attach.d.ts +7 -0
  4. package/dist/cjs/attach.js +29 -0
  5. package/dist/cjs/checkin.js +4 -13
  6. package/dist/cjs/cron/monitor.d.ts +47 -0
  7. package/dist/cjs/cron/monitor.js +95 -0
  8. package/dist/cjs/cron/schedulers.d.ts +36 -0
  9. package/dist/cjs/cron/schedulers.js +65 -0
  10. package/dist/cjs/env.d.ts +10 -0
  11. package/dist/cjs/env.js +98 -1
  12. package/dist/cjs/index.d.ts +50 -6
  13. package/dist/cjs/index.js +114 -37
  14. package/dist/cjs/instrument-for.d.ts +17 -0
  15. package/dist/cjs/instrument-for.js +44 -0
  16. package/dist/cjs/instrument.d.ts +4 -0
  17. package/dist/cjs/instrument.js +32 -1
  18. package/dist/cjs/integrations/bullmq.d.ts +8 -2
  19. package/dist/cjs/integrations/bullmq.js +32 -5
  20. package/dist/cjs/integrations/db.d.ts +7 -2
  21. package/dist/cjs/integrations/db.js +32 -4
  22. package/dist/cjs/integrations/fastify.d.ts +1 -1
  23. package/dist/cjs/integrations/fastify.js +3 -2
  24. package/dist/cjs/integrations/logs.js +16 -5
  25. package/dist/cjs/integrations/next-build.d.ts +25 -8
  26. package/dist/cjs/integrations/next-build.js +159 -34
  27. package/dist/cjs/integrations/next-tunnel.d.ts +6 -1
  28. package/dist/cjs/integrations/next-tunnel.js +13 -2
  29. package/dist/cjs/integrations/postgres.d.ts +2 -0
  30. package/dist/cjs/integrations/postgres.js +43 -1
  31. package/dist/cjs/integrations/temporal.d.ts +97 -0
  32. package/dist/cjs/integrations/temporal.js +144 -0
  33. package/dist/cjs/integrations/util.d.ts +17 -0
  34. package/dist/cjs/integrations/util.js +38 -0
  35. package/dist/cjs/load.d.ts +6 -0
  36. package/dist/cjs/load.js +28 -4
  37. package/dist/cjs/next-doctor-cli.d.ts +2 -0
  38. package/dist/cjs/next-doctor-cli.js +15 -0
  39. package/dist/cjs/next-doctor.d.ts +2 -0
  40. package/dist/cjs/next-doctor.js +50 -0
  41. package/dist/cjs/redact-presets.d.ts +16 -0
  42. package/dist/cjs/redact-presets.js +66 -0
  43. package/dist/cjs/register.js +19 -6
  44. package/dist/cjs/version.d.ts +1 -1
  45. package/dist/cjs/version.js +1 -1
  46. package/dist/esm/attach.d.ts +7 -0
  47. package/dist/esm/attach.js +25 -0
  48. package/dist/esm/checkin.js +4 -13
  49. package/dist/esm/cron/monitor.d.ts +47 -0
  50. package/dist/esm/cron/monitor.js +85 -0
  51. package/dist/esm/cron/schedulers.d.ts +36 -0
  52. package/dist/esm/cron/schedulers.js +61 -0
  53. package/dist/esm/env.d.ts +10 -0
  54. package/dist/esm/env.js +62 -0
  55. package/dist/esm/index.d.ts +50 -6
  56. package/dist/esm/index.js +109 -39
  57. package/dist/esm/instrument-for.d.ts +17 -0
  58. package/dist/esm/instrument-for.js +41 -0
  59. package/dist/esm/instrument.d.ts +4 -0
  60. package/dist/esm/instrument.js +30 -1
  61. package/dist/esm/integrations/bullmq.d.ts +8 -2
  62. package/dist/esm/integrations/bullmq.js +32 -5
  63. package/dist/esm/integrations/db.d.ts +7 -2
  64. package/dist/esm/integrations/db.js +29 -4
  65. package/dist/esm/integrations/fastify.d.ts +1 -1
  66. package/dist/esm/integrations/fastify.js +4 -3
  67. package/dist/esm/integrations/logs.js +16 -5
  68. package/dist/esm/integrations/next-build.d.ts +25 -8
  69. package/dist/esm/integrations/next-build.js +158 -34
  70. package/dist/esm/integrations/next-tunnel.d.ts +6 -1
  71. package/dist/esm/integrations/next-tunnel.js +13 -2
  72. package/dist/esm/integrations/postgres.d.ts +2 -0
  73. package/dist/esm/integrations/postgres.js +43 -2
  74. package/dist/esm/integrations/temporal.d.ts +97 -0
  75. package/dist/esm/integrations/temporal.js +139 -0
  76. package/dist/esm/integrations/util.d.ts +17 -0
  77. package/dist/esm/integrations/util.js +35 -0
  78. package/dist/esm/load.d.ts +6 -0
  79. package/dist/esm/load.js +21 -3
  80. package/dist/esm/next-doctor-cli.d.ts +2 -0
  81. package/dist/esm/next-doctor-cli.js +13 -0
  82. package/dist/esm/next-doctor.d.ts +2 -0
  83. package/dist/esm/next-doctor.js +14 -0
  84. package/dist/esm/redact-presets.d.ts +16 -0
  85. package/dist/esm/redact-presets.js +58 -0
  86. package/dist/esm/register.js +20 -7
  87. package/dist/esm/version.d.ts +1 -1
  88. package/dist/esm/version.js +1 -1
  89. package/package.json +42 -1
@@ -1,15 +1,21 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.registered = void 0;
4
+ exports.instrumentOne = instrumentOne;
3
5
  exports.instrumentAll = instrumentAll;
4
6
  // Auto-instrumentation: node:http, fetch (undici), pg and ioredis, each only when its optional peer package is installed.
5
7
  const load_js_1 = require("./load.js");
6
8
  const sqlite_js_1 = require("./integrations/sqlite.js");
7
9
  const postgres_js_1 = require("./integrations/postgres.js");
10
+ const util_js_1 = require("./integrations/util.js");
11
+ /** Instrumentation packages already registered in this process (by `init` or `instrument()`), so none is patched twice. */
12
+ exports.registered = new Set();
8
13
  const ENTRIES = [
9
14
  {
10
15
  pkg: '@opentelemetry/instrumentation-http', ctor: 'HttpInstrumentation',
11
16
  // our own exports and API calls must not become spans
12
- opts: (self) => ({ ignoreOutgoingRequestHook: (r) => self.some((u) => (r.hostname || r.host) === u.hostname && String(r.port ?? (u.protocol === 'https:' ? 443 : 80)) === String(u.port || (u.protocol === 'https:' ? 443 : 80))) }),
17
+ // routeNamer: server spans become `GET /users/:id` from the matched Express / Nest route (http alone names them just `GET`)
18
+ opts: (self) => ({ applyCustomAttributesOnSpan: util_js_1.routeNamer, ignoreOutgoingRequestHook: (r) => self.some((u) => (r.hostname || r.host) === u.hostname && String(r.port ?? (u.protocol === 'https:' ? 443 : 80)) === String(u.port || (u.protocol === 'https:' ? 443 : 80))) }),
13
19
  },
14
20
  {
15
21
  pkg: '@opentelemetry/instrumentation-undici', ctor: 'UndiciInstrumentation',
@@ -19,6 +25,30 @@ const ENTRIES = [
19
25
  { pkg: '@opentelemetry/instrumentation-ioredis', ctor: 'IORedisInstrumentation', opts: () => ({}) },
20
26
  { pkg: '@opentelemetry/instrumentation-mysql2', ctor: 'MySQL2Instrumentation', opts: () => ({}), auto: true },
21
27
  ];
28
+ /** Register one entry by package name (for `instrument(name)`); false when already registered or not installed. Uses the global providers. */
29
+ function instrumentOne(pkg, selfUrls = []) {
30
+ const e = ENTRIES.find((x) => x.pkg === pkg);
31
+ if (!e || exports.registered.has(pkg))
32
+ return false;
33
+ const self = selfUrls.flatMap((u) => { try {
34
+ return [new URL(u)];
35
+ }
36
+ catch {
37
+ return [];
38
+ } });
39
+ try {
40
+ const { registerInstrumentations } = (0, load_js_1.load)('@opentelemetry/instrumentation');
41
+ const Ctor = (0, load_js_1.load)(pkg)[e.ctor];
42
+ if (!Ctor)
43
+ return false;
44
+ registerInstrumentations({ instrumentations: [new Ctor(e.opts(self))] });
45
+ exports.registered.add(pkg);
46
+ return true;
47
+ }
48
+ catch {
49
+ return false;
50
+ } // peer not installed
51
+ }
22
52
  /** Drivers patched in place (no OTel package): `instrument: 'auto'` only. Each loads the app's installed copy or is skipped. */
23
53
  const DRIVERS = [
24
54
  { name: 'postgres.js', run: () => { (0, load_js_1.load)('postgres'); (0, postgres_js_1.instrumentPostgres)(); } }, // only when `postgres` is installed
@@ -52,6 +82,7 @@ function instrumentAll(p, selfUrls, auto = false) {
52
82
  if (Ctor) {
53
83
  found.push(new Ctor(e.opts(self)));
54
84
  names.push(e.pkg);
85
+ exports.registered.add(e.pkg);
55
86
  }
56
87
  }
57
88
  catch {
@@ -8,12 +8,18 @@ interface BullMQLike {
8
8
  prototype: Record<string | symbol, unknown>;
9
9
  };
10
10
  }
11
+ export interface BullMQOptions {
12
+ /** Report a job's failure as an error when it is the last attempt (no retry left): queue, job name and id, attempt, attemptsMade and attempts as attributes. */
13
+ captureFailures?: boolean;
14
+ /** Run repeatable jobs (`repeat.pattern`/`cron`) as cron monitors named `<queue>-<job name>`; needs the `ingest:checkins` key scope. */
15
+ cronMonitors?: boolean;
16
+ }
11
17
  /**
12
18
  * `import * as bullmq from 'bullmq'; instrumentBullMQ(bullmq)` (ESM or CJS): PRODUCER spans on
13
19
  * `Queue.add`/`addBulk`, CONSUMER spans around each job a `Worker` processes, parented by the
14
20
  * producer's context carried in job data under `_wt` (stripped before your processor runs; object
15
21
  * data only). Call it once, before creating queues and workers. Returns false when this bullmq
16
- * has no `Worker.callProcessJob` (consumer spans off; producer spans still on).
22
+ * has no `Worker.callProcessJob` (consumer spans off; producer spans still on). Options: see `BullMQOptions`.
17
23
  * shortcut: sandboxed (file path) processors run in a child process and get no consumer span.
18
24
  */
19
- export declare function instrumentBullMQ(bullmq: BullMQLike): boolean;
25
+ export declare function instrumentBullMQ(bullmq: BullMQLike, options?: BullMQOptions): boolean;
@@ -5,6 +5,8 @@ exports.instrumentBullMQ = instrumentBullMQ;
5
5
  const api_1 = require("@opentelemetry/api");
6
6
  const messaging_js_1 = require("./messaging.js");
7
7
  Object.defineProperty(exports, "CONTEXT_KEY", { enumerable: true, get: function () { return messaging_js_1.CONTEXT_KEY; } });
8
+ const errors_js_1 = require("../errors.js");
9
+ const monitor_js_1 = require("../cron/monitor.js");
8
10
  const PATCHED = Symbol.for('watchtower.bullmq');
9
11
  const tracer = () => api_1.trace.getTracer('watchtower');
10
12
  const base = (queue, op, name) => ({
@@ -13,12 +15,13 @@ const base = (queue, op, name) => ({
13
15
  'messaging.operation.type': op,
14
16
  'messaging.operation.name': name,
15
17
  });
16
- async function run(span, fn) {
18
+ async function run(span, fn, recorded) {
17
19
  try {
18
20
  return await fn();
19
21
  }
20
22
  catch (e) {
21
- span.recordException(e);
23
+ if (!recorded?.())
24
+ span.recordException(e);
22
25
  span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: e?.message });
23
26
  throw e;
24
27
  }
@@ -31,10 +34,10 @@ async function run(span, fn) {
31
34
  * `Queue.add`/`addBulk`, CONSUMER spans around each job a `Worker` processes, parented by the
32
35
  * producer's context carried in job data under `_wt` (stripped before your processor runs; object
33
36
  * data only). Call it once, before creating queues and workers. Returns false when this bullmq
34
- * has no `Worker.callProcessJob` (consumer spans off; producer spans still on).
37
+ * has no `Worker.callProcessJob` (consumer spans off; producer spans still on). Options: see `BullMQOptions`.
35
38
  * shortcut: sandboxed (file path) processors run in a child process and get no consumer span.
36
39
  */
37
- function instrumentBullMQ(bullmq) {
40
+ function instrumentBullMQ(bullmq, options = {}) {
38
41
  const q = bullmq.Queue.prototype;
39
42
  const w = bullmq.Worker.prototype;
40
43
  if (q[PATCHED])
@@ -77,7 +80,31 @@ function instrumentBullMQ(bullmq) {
77
80
  attrs['messaging.message.id'] = job.id;
78
81
  if (job.opts?.delay)
79
82
  attrs['messaging.bullmq.job.delay_ms'] = job.opts.delay;
80
- return tracer().startActiveSpan(`process ${this.name}`, { kind: api_1.SpanKind.CONSUMER, attributes: attrs }, parent, (span) => run(span, () => call.call(this, job, ...rest)));
83
+ const queue = this.name;
84
+ const rep = job.opts?.repeat;
85
+ const cron = options.cronMonitors ? rep?.pattern ?? rep?.cron : undefined;
86
+ return tracer().startActiveSpan(`process ${queue}`, { kind: api_1.SpanKind.CONSUMER, attributes: attrs }, parent, (span) => {
87
+ let recorded = false;
88
+ const exec = async () => {
89
+ try {
90
+ return await call.call(this, job, ...rest);
91
+ }
92
+ catch (e) {
93
+ const attempts = job.opts?.attempts ?? 1;
94
+ const made = (job.attemptsMade ?? 0) + 1;
95
+ if (options.captureFailures && (made >= attempts || e?.name === 'UnrecoverableError')) {
96
+ (0, errors_js_1.captureException)(e, { attributes: {
97
+ 'bullmq.queue': queue, 'bullmq.job.name': job.name, 'bullmq.job.id': job.id, 'bullmq.job.attempt': made,
98
+ 'bullmq.job.attempts_made': made, 'bullmq.job.attempts': attempts,
99
+ } });
100
+ recorded = true;
101
+ }
102
+ throw e;
103
+ }
104
+ };
105
+ const slug = cron ? (0, monitor_js_1.slugify)(`${queue}-${job.name}`) : '';
106
+ return run(span, () => (slug ? (0, monitor_js_1.monitorJob)(slug, exec, { schedule: cron, timezone: rep?.tz }) : exec()), () => recorded);
107
+ });
81
108
  };
82
109
  return true;
83
110
  }
@@ -5,8 +5,7 @@ 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. */
8
+ /** Record a query only when a span is active (a request, job or `observe` span). Default: true when HTTP server instrumentation is active, else false (`WATCHTOWER_DB_REQUIRE_PARENT=0/1` overrides): startup DDL, migrations and polling loops run outside any span and would otherwise each become a root trace. */
10
9
  requireParent?: boolean;
11
10
  }
12
11
  export interface DbOp {
@@ -22,6 +21,12 @@ export interface DbOp {
22
21
  export declare const inside: (ctx?: Context) => boolean;
23
22
  /** `parent` with `span` active; `nested` marks it as inside an instrumented call (no inner spans). */
24
23
  export declare const enter: (parent: Context, span: Span, nested?: boolean) => Context;
24
+ /** Set by `init()`: whether node:http server instrumentation is on (requests then give queries a parent span). */
25
+ export declare const setHttpServerActive: (v: boolean) => void;
26
+ /** Explicit option, then `WATCHTOWER_DB_REQUIRE_PARENT`, else only when HTTP server instrumentation is active (a queue worker has no request spans, so its queries become root spans). */
27
+ export declare function dbRequireParent(opt: boolean | undefined): boolean;
28
+ /** Datastore spans dropped so far because `requireParent` found no active parent span. */
29
+ export declare const droppedDbSpans: () => number;
25
30
  /** A CLIENT span for `op` (not made active): summary, hash, N+1 hint. Prefer `traced`. */
26
31
  export declare function startDbSpan(op: DbOp, opts: DbOptions | undefined, parent: Context, startTime?: TimeInput): Span;
27
32
  /** A finished CLIENT span for a query a library reports after the fact (ORM loggers): it ends now. */
@@ -33,7 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.enter = exports.inside = void 0;
36
+ exports.droppedDbSpans = exports.setHttpServerActive = exports.enter = exports.inside = void 0;
37
+ exports.dbRequireParent = dbRequireParent;
37
38
  exports.startDbSpan = startDbSpan;
38
39
  exports.recordDbSpan = recordDbSpan;
39
40
  exports.fail = fail;
@@ -74,12 +75,39 @@ function repeats(parent, key) {
74
75
  m.set(key, n);
75
76
  return n;
76
77
  }
78
+ let httpServerActive = false;
79
+ /** Set by `init()`: whether node:http server instrumentation is on (requests then give queries a parent span). */
80
+ const setHttpServerActive = (v) => { httpServerActive = v; };
81
+ exports.setHttpServerActive = setHttpServerActive;
82
+ /** Explicit option, then `WATCHTOWER_DB_REQUIRE_PARENT`, else only when HTTP server instrumentation is active (a queue worker has no request spans, so its queries become root spans). */
83
+ function dbRequireParent(opt) {
84
+ if (opt !== undefined)
85
+ return opt;
86
+ const e = (process.env.WATCHTOWER_DB_REQUIRE_PARENT || '').trim().toLowerCase();
87
+ if (['0', 'false', 'off', 'no'].includes(e))
88
+ return false;
89
+ if (['1', 'true', 'on', 'yes'].includes(e))
90
+ return true;
91
+ return httpServerActive;
92
+ }
93
+ let droppedSpans = 0;
94
+ let droppedCounter;
95
+ /** Datastore spans dropped so far because `requireParent` found no active parent span. */
96
+ const droppedDbSpans = () => droppedSpans;
97
+ exports.droppedDbSpans = droppedDbSpans;
98
+ /** Count a dropped span: the `wt.sdk.db.dropped_spans` counter (exported with the SDK's metrics) and one diag warning. */
99
+ function dropped() {
100
+ if (droppedSpans++ === 0)
101
+ api_1.diag.warn('watchtower: a datastore span was dropped because it has no parent span (requireParent); counted in wt.sdk.db.dropped_spans. Set WATCHTOWER_DB_REQUIRE_PARENT=0 to keep such queries as root spans');
102
+ droppedCounter ??= api_1.metrics.getMeter('watchtower').createCounter('wt.sdk.db.dropped_spans', { description: 'Datastore spans dropped for lack of a parent span (requireParent)' });
103
+ droppedCounter.add(1);
104
+ return api_1.trace.wrapSpanContext(api_1.INVALID_SPAN_CONTEXT);
105
+ }
77
106
  /** A CLIENT span for `op` (not made active): summary, hash, N+1 hint. Prefer `traced`. */
78
107
  function startDbSpan(op, opts, parent, startTime) {
79
108
  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
109
+ if (dbRequireParent(opts?.requireParent) && !(p && api_1.trace.isSpanContextValid(p)))
110
+ return dropped(); // non-recording: nothing is exported
83
111
  const attrs = { 'db.system.name': op.system, ...op.attributes };
84
112
  let { operation, collection } = op;
85
113
  let name = [operation, collection].filter(Boolean).join(' ') || op.system;
@@ -2,5 +2,5 @@
2
2
  export interface FastifyLike {
3
3
  addHook(name: string, fn: (...args: any[]) => void): unknown;
4
4
  }
5
- /** await app.register(plugin): server span per request plus 5xx error capture. */
5
+ /** await app.register(plugin): server span per request (or the http instrumentation's own server span, enriched) plus 5xx error capture. */
6
6
  export declare function plugin(fastify: FastifyLike, _opts: unknown, done: (err?: Error) => void): void;
@@ -7,10 +7,11 @@ const payload_js_1 = require("../payload.js");
7
7
  const util_js_1 = require("./util.js");
8
8
  const KEY = Symbol('wt.span');
9
9
  const SENT = Symbol('wt.sent');
10
- /** await app.register(plugin): server span per request plus 5xx error capture. */
10
+ /** await app.register(plugin): server span per request (or the http instrumentation's own server span, enriched) plus 5xx error capture. */
11
11
  function plugin(fastify, _opts, done) {
12
12
  fastify.addHook('onRequest', (req, _reply, next) => {
13
- const s = (0, util_js_1.serverSpan)(req.method, req.url);
13
+ // with the http instrumentation active its server span is enriched (route, status) instead of starting a second one
14
+ const s = (0, util_js_1.adoptServerSpan)(req.method) ?? (0, util_js_1.serverSpan)(req.method, req.url);
14
15
  req[KEY] = s;
15
16
  api_1.context.with(s.ctx, next);
16
17
  });
@@ -41,11 +41,22 @@ const load_js_1 = require("../load.js");
41
41
  const defaultSink = { log: (level, body, attrs) => wt.log(level, body, attrs) };
42
42
  const PINO = { 10: 'trace', 20: 'debug', 30: 'info', 40: 'warn', 50: 'error', 60: 'fatal' };
43
43
  const CORE = new Set(['level', 'time', 'msg', 'pid', 'hostname', 'v']);
44
- const flat = (o, skip) => {
45
- const attrs = {};
46
- for (const [k, v] of Object.entries(o))
47
- if (!skip || !skip.has(k))
48
- attrs[k] = typeof v === 'object' ? JSON.stringify(v) : v;
44
+ const MAX_DEPTH = 4;
45
+ const plain = (v) => !!v && typeof v === 'object' && Object.getPrototypeOf(v) === Object.prototype;
46
+ const prim = (v) => v == null || ['string', 'number', 'boolean'].includes(typeof v);
47
+ /** Nested plain objects become dotted attributes (`req.url`) up to depth 4 so `redact` and the presets see each leaf; arrays of primitives stay arrays, anything else is a JSON string. */
48
+ const flat = (o, skip, prefix = '', depth = 1, attrs = {}) => {
49
+ for (const [k, v] of Object.entries(o)) {
50
+ if (skip && skip.has(k))
51
+ continue;
52
+ const key = prefix + k;
53
+ if (plain(v) && depth < MAX_DEPTH)
54
+ flat(v, undefined, `${key}.`, depth + 1, attrs);
55
+ else if (Array.isArray(v) && v.every(prim))
56
+ attrs[key] = v;
57
+ else
58
+ attrs[key] = typeof v === 'object' && v !== null ? JSON.stringify(v) : v;
59
+ }
49
60
  return attrs;
50
61
  };
51
62
  /** pino(opts, pinoStream()) or pino.multistream([{ stream: pinoStream() }, { stream: process.stdout }]). */
@@ -18,17 +18,34 @@ export interface SourcemapOptions {
18
18
  }
19
19
  type NextConfig = Record<string, unknown>;
20
20
  type ConfigOrFn = NextConfig | ((...a: unknown[]) => NextConfig | Promise<NextConfig>);
21
+ export interface WatchtowerNextOptions {
22
+ /**
23
+ * `true` turns on `productionBrowserSourceMaps`. `{ upload: true }` also uploads `.next/static/**\/*.map` when the
24
+ * webpack client build finishes (CI: needs WT_API_KEY, WT_PROJECT; the release is `release` below) and, unless
25
+ * `deleteAfterUpload: false`, deletes the maps. Turbopack has no webpack hooks: run `wt-next-sourcemaps` after `next build`.
26
+ * Other fields are `uploadSourcemaps` options (`apiUrl`, `project`, `inject`, `fetch`, ...).
27
+ */
28
+ sourcemaps?: boolean | (Omit<SourcemapOptions, 'keep' | 'release'> & {
29
+ upload?: boolean;
30
+ deleteAfterUpload?: boolean;
31
+ });
32
+ /** Release: injected as `NEXT_PUBLIC_WT_RELEASE` (read by `<WatchtowerRUM>`). Default WT_RELEASE, then the git sha of the CI/host env. */
33
+ release?: string;
34
+ }
21
35
  /**
22
- * `module.exports = withWatchtower(nextConfig, { sourcemaps: true })`: turns on `productionBrowserSourceMaps` so
23
- * `next build` writes client maps (works with webpack and Turbopack). Then run `wt-next-sourcemaps` after the build
24
- * (`"build": "next build && wt-next-sourcemaps"`) to upload them and delete the .map files from `.next/static`.
36
+ * `module.exports = withWatchtower(nextConfig, { sourcemaps: true })`. Makes `output: 'standalone'` work with no other
37
+ * config: the node SDK and its OpenTelemetry peers go into `serverExternalPackages` and (npm and pnpm layouts) into
38
+ * `outputFileTracingIncludes` for every route. Sets `NEXT_PUBLIC_WT_RELEASE`. With `sourcemaps` it turns on
39
+ * `productionBrowserSourceMaps` (webpack and Turbopack); `{ upload: true }` uploads and deletes them after the webpack
40
+ * client build, otherwise run `wt-next-sourcemaps` after `next build` (`"build": "next build && wt-next-sourcemaps"`).
25
41
  */
26
- export declare function withWatchtower(config?: ConfigOrFn, opts?: {
27
- sourcemaps?: boolean;
28
- }): ConfigOrFn;
42
+ export declare function withWatchtower(config?: ConfigOrFn, opts?: WatchtowerNextOptions): ConfigOrFn;
43
+ /** A ustar archive of `[name, bytes]` (names up to 100 bytes). */
44
+ export declare function makeTar(files: [string, Buffer][]): Buffer;
29
45
  /**
30
- * Upload every `.map` under `dir` as `_next/static/<path>` for the release (8 at a time, 429/5xx retried with backoff
31
- * honoring Retry-After; a failed map does not stop the others), then delete them when none failed. Returns
46
+ * Upload every `.map` under `dir` as `_next/static/<path>` for the release: one `POST /artifacts/bundle` per ~120 MB
47
+ * batch (tar.gz plus manifest), falling back to single uploads (8 at a time) when the server has no bundle route.
48
+ * 429/5xx are retried with backoff honoring Retry-After; a failed map does not stop the others. The maps are deleted when none failed. Returns
32
49
  * `{uploaded, skipped, failed}`: `skipped` = the server already had those exact bytes (HTTP 200). Bodies are sent
33
50
  * gzipped (`Content-Encoding: gzip`).
34
51
  */
@@ -34,19 +34,69 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.withWatchtower = withWatchtower;
37
+ exports.makeTar = makeTar;
37
38
  exports.uploadSourcemaps = uploadSourcemaps;
38
39
  // Build-time helpers for Next.js: `withWatchtower` (next.config) and `uploadSourcemaps` (after `next build`).
39
40
  const fs = __importStar(require("node:fs"));
40
41
  const nodePath = __importStar(require("node:path"));
41
42
  const zlib = __importStar(require("node:zlib"));
42
43
  const next_debugid_js_1 = require("./next-debugid.js");
44
+ // what the node SDK loads at run time through createRequire (invisible to Next's file tracer): see src/load.ts
45
+ const OTEL = [
46
+ '@opentelemetry/api', '@opentelemetry/context-async-hooks', '@opentelemetry/core', '@opentelemetry/exporter-logs-otlp-http',
47
+ '@opentelemetry/exporter-metrics-otlp-http', '@opentelemetry/exporter-trace-otlp-http', '@opentelemetry/instrumentation',
48
+ '@opentelemetry/otlp-transformer', '@opentelemetry/resources', '@opentelemetry/sdk-logs', '@opentelemetry/sdk-metrics',
49
+ '@opentelemetry/sdk-trace',
50
+ ];
51
+ const EXTERNAL = ['@watchtowerobservability/node', ...OTEL];
52
+ const SHA_ENV = ['WT_RELEASE', 'GITHUB_SHA', 'CI_COMMIT_SHA', 'VERCEL_GIT_COMMIT_SHA', 'SOURCE_VERSION', 'BUILD_SHA', 'RENDER_GIT_COMMIT', 'HEROKU_SLUG_COMMIT'];
53
+ const INCLUDE = ['@watchtowerobservability/node', '@opentelemetry'].flatMap((p) => [`./node_modules/${p}/**/*`, `./node_modules/.pnpm/${p.replace('/', '+')}*/**/*`]);
43
54
  /**
44
- * `module.exports = withWatchtower(nextConfig, { sourcemaps: true })`: turns on `productionBrowserSourceMaps` so
45
- * `next build` writes client maps (works with webpack and Turbopack). Then run `wt-next-sourcemaps` after the build
46
- * (`"build": "next build && wt-next-sourcemaps"`) to upload them and delete the .map files from `.next/static`.
55
+ * `module.exports = withWatchtower(nextConfig, { sourcemaps: true })`. Makes `output: 'standalone'` work with no other
56
+ * config: the node SDK and its OpenTelemetry peers go into `serverExternalPackages` and (npm and pnpm layouts) into
57
+ * `outputFileTracingIncludes` for every route. Sets `NEXT_PUBLIC_WT_RELEASE`. With `sourcemaps` it turns on
58
+ * `productionBrowserSourceMaps` (webpack and Turbopack); `{ upload: true }` uploads and deletes them after the webpack
59
+ * client build, otherwise run `wt-next-sourcemaps` after `next build` (`"build": "next build && wt-next-sourcemaps"`).
47
60
  */
48
61
  function withWatchtower(config = {}, opts = {}) {
49
- const apply = (c) => (opts.sourcemaps ? { ...c, productionBrowserSourceMaps: true } : c);
62
+ const sm = opts.sourcemaps === true ? {} : opts.sourcemaps || undefined;
63
+ const release = opts.release || SHA_ENV.map((k) => process.env[k]).find((v) => v && v !== 'unknown');
64
+ const apply = (c) => {
65
+ const inc = { ...c.outputFileTracingIncludes };
66
+ inc['/*'] = [...new Set([...(inc['/*'] ?? []), ...INCLUDE])];
67
+ const out = {
68
+ ...c,
69
+ serverExternalPackages: [...new Set([...(c.serverExternalPackages ?? []), ...EXTERNAL])],
70
+ outputFileTracingIncludes: inc,
71
+ };
72
+ if (release)
73
+ out.env = { NEXT_PUBLIC_WT_RELEASE: release, ...c.env };
74
+ if (sm)
75
+ out.productionBrowserSourceMaps = true;
76
+ if (sm && 'upload' in sm && sm.upload) {
77
+ const { upload: _u, deleteAfterUpload, ...so } = sm;
78
+ const w = c.webpack;
79
+ out.webpack = (cfg, ctx) => {
80
+ const r = (w ? w(cfg, ctx) : cfg);
81
+ if (!ctx.dev && !ctx.isServer) {
82
+ (r.plugins ??= []).push({
83
+ apply(compiler) {
84
+ compiler.hooks.done.tapPromise('watchtower-sourcemaps', async () => {
85
+ try {
86
+ await uploadSourcemaps({ log: (l) => console.log(`[watchtower] ${l}`), ...so, release, keep: deleteAfterUpload === false });
87
+ }
88
+ catch (e) {
89
+ console.warn(`[watchtower] source map upload skipped: ${e.message}`);
90
+ }
91
+ });
92
+ },
93
+ });
94
+ }
95
+ return r;
96
+ };
97
+ }
98
+ return out;
99
+ };
50
100
  if (typeof config !== 'function')
51
101
  return apply(config);
52
102
  return async (...a) => apply(await config(...a));
@@ -60,6 +110,30 @@ function* maps(dir) {
60
110
  yield p;
61
111
  }
62
112
  }
113
+ /** A ustar archive of `[name, bytes]` (names up to 100 bytes). */
114
+ function makeTar(files) {
115
+ const parts = [];
116
+ for (const [name, data] of files) {
117
+ const h = Buffer.alloc(512);
118
+ h.write(name, 0, 100, 'utf8');
119
+ h.write('0000644\0', 100);
120
+ h.write('0000000\0', 108);
121
+ h.write('0000000\0', 116);
122
+ h.write(`${data.length.toString(8).padStart(11, '0')}\0`, 124);
123
+ h.write('00000000000\0', 136);
124
+ h.write(' ', 148);
125
+ h.write('0', 156);
126
+ h.write('ustar\0', 257);
127
+ h.write('00', 263);
128
+ let sum = 0;
129
+ for (const b of h)
130
+ sum += b;
131
+ h.write(`${sum.toString(8).padStart(6, '0')}\0 `, 148);
132
+ parts.push(h, data, Buffer.alloc((512 - (data.length % 512)) % 512));
133
+ }
134
+ parts.push(Buffer.alloc(1024));
135
+ return Buffer.concat(parts);
136
+ }
63
137
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
64
138
  /** The client chunk (`_next/static/...`) a map belongs to: the sibling JS's `//# sourceMappingURL=` target, else the map's own `file` field. */
65
139
  function chunkFor(mapFile, name) {
@@ -78,8 +152,9 @@ function chunkFor(mapFile, name) {
78
152
  return undefined;
79
153
  }
80
154
  /**
81
- * Upload every `.map` under `dir` as `_next/static/<path>` for the release (8 at a time, 429/5xx retried with backoff
82
- * honoring Retry-After; a failed map does not stop the others), then delete them when none failed. Returns
155
+ * Upload every `.map` under `dir` as `_next/static/<path>` for the release: one `POST /artifacts/bundle` per ~120 MB
156
+ * batch (tar.gz plus manifest), falling back to single uploads (8 at a time) when the server has no bundle route.
157
+ * 429/5xx are retried with backoff honoring Retry-After; a failed map does not stop the others. The maps are deleted when none failed. Returns
83
158
  * `{uploaded, skipped, failed}`: `skipped` = the server already had those exact bytes (HTTP 200). Bodies are sent
84
159
  * gzipped (`Content-Encoding: gzip`).
85
160
  */
@@ -126,38 +201,88 @@ async function uploadSourcemaps(o = {}) {
126
201
  if (!rel.ok && rel.status !== 409)
127
202
  throw new Error(`watchtower POST /releases -> HTTP ${rel.status}${rel.status === 401 || rel.status === 403 ? ' (check WT_API_KEY scope ci:write)' : ''}`);
128
203
  let uploaded = 0, skipped = 0, failed = 0;
129
- let next = 0;
130
- const worker = async () => {
131
- for (let file = files[next++]; file !== undefined; file = files[next++]) {
132
- const name = `_next/static/${nodePath.relative(dir, file).split(nodePath.sep).join('/')}`;
133
- const q = { kind: 'sourcemap', name, release };
134
- const chunk = chunkFor(file, name);
135
- if (chunk)
136
- q.for = chunk;
137
- const id = ids.get(file);
138
- if (id)
139
- q.debug_id = id;
140
- try {
141
- const res = await send(`/artifacts?${new URLSearchParams(q)}`, {
142
- method: 'POST', headers: { 'content-type': 'application/octet-stream', 'content-encoding': 'gzip' },
143
- body: new Uint8Array(zlib.gzipSync(fs.readFileSync(file))),
144
- }, 4);
145
- if (res.status === 200)
146
- skipped++;
147
- else if (res.ok)
148
- uploaded++;
149
- else {
150
- failed++;
151
- log(`failed ${name}: HTTP ${res.status}`);
152
- }
153
- }
154
- catch (e) {
204
+ const entries = files.map((file) => {
205
+ const name = `_next/static/${nodePath.relative(dir, file).split(nodePath.sep).join('/')}`;
206
+ return { file, name, chunk: chunkFor(file, name), id: ids.get(file) };
207
+ });
208
+ const single = async (e) => {
209
+ const q = { kind: 'sourcemap', name: e.name, release };
210
+ if (e.chunk)
211
+ q.for = e.chunk;
212
+ if (e.id)
213
+ q.debug_id = e.id;
214
+ try {
215
+ const res = await send(`/artifacts?${new URLSearchParams(q)}`, {
216
+ method: 'POST', headers: { 'content-type': 'application/octet-stream', 'content-encoding': 'gzip' },
217
+ body: new Uint8Array(zlib.gzipSync(fs.readFileSync(e.file))),
218
+ }, 4);
219
+ if (res.status === 200)
220
+ skipped++;
221
+ else if (res.ok)
222
+ uploaded++;
223
+ else {
155
224
  failed++;
156
- log(`failed ${name}: ${e.message}`);
225
+ log(`failed ${e.name}: HTTP ${res.status}`);
157
226
  }
158
227
  }
228
+ catch (err) {
229
+ failed++;
230
+ log(`failed ${e.name}: ${err.message}`);
231
+ }
232
+ };
233
+ const concurrently = async (list) => {
234
+ let next = 0;
235
+ const worker = async () => {
236
+ for (let e = list[next++]; e !== undefined; e = list[next++])
237
+ await single(e);
238
+ };
239
+ await Promise.all(Array.from({ length: Math.min(8, list.length) }, worker));
159
240
  };
160
- await Promise.all(Array.from({ length: Math.min(8, files.length) }, worker));
241
+ // One request per batch (tar.gz + manifest). A server without the bundle route (or a request that
242
+ // never got through) falls back to concurrent single uploads for that batch.
243
+ const BATCH_BYTES = 120 * 1024 * 1024;
244
+ const batches = [];
245
+ let cur = [], curBytes = 0;
246
+ for (const e of entries) {
247
+ const size = fs.statSync(e.file).size;
248
+ if (cur.length && curBytes + size > BATCH_BYTES) {
249
+ batches.push(cur);
250
+ cur = [];
251
+ curBytes = 0;
252
+ }
253
+ cur.push(e);
254
+ curBytes += size;
255
+ }
256
+ if (cur.length)
257
+ batches.push(cur);
258
+ for (const batch of batches) {
259
+ let handled = false;
260
+ try {
261
+ const manifest = { files: batch.map((e, i) => ({ path: `m${i}.map`, name: e.name, ...(e.chunk ? { for: e.chunk } : {}), ...(e.id ? { debug_id: e.id } : {}) })) };
262
+ const tar = makeTar([['manifest.json', Buffer.from(JSON.stringify(manifest))], ...batch.map((e, i) => [`m${i}.map`, fs.readFileSync(e.file)])]);
263
+ const res = await send(`/artifacts/bundle?${new URLSearchParams({ release })}`, {
264
+ method: 'POST', headers: { 'content-type': 'application/octet-stream' }, body: new Uint8Array(zlib.gzipSync(tar)),
265
+ }, 4);
266
+ const r = res.ok ? (await res.json().catch(() => ({}))) : {};
267
+ if (typeof r.uploaded === 'number') { // anything else is not our bundle route: fall back
268
+ uploaded += r.uploaded;
269
+ skipped += r.skipped || 0;
270
+ failed += r.failed || 0;
271
+ for (const e of r.errors || [])
272
+ log(`failed ${e.name}: ${e.reason}`);
273
+ handled = true;
274
+ }
275
+ else if (res.status === 401 || res.status === 403) {
276
+ throw new Error(`watchtower POST /artifacts/bundle -> HTTP ${res.status} (check WT_API_KEY scope ci:write)`);
277
+ }
278
+ }
279
+ catch (e) {
280
+ if (e.message.startsWith('watchtower ') || e.message.startsWith('cannot reach'))
281
+ throw e;
282
+ }
283
+ if (!handled)
284
+ await concurrently(batch);
285
+ }
161
286
  if (!o.keep && failed === 0)
162
287
  for (const file of files)
163
288
  fs.rmSync(file);
@@ -5,9 +5,14 @@ export interface TunnelOptions {
5
5
  basePath?: string;
6
6
  /** Request body cap in bytes; default 1 MiB (over it: 413). */
7
7
  maxBodyBytes?: number;
8
+ /**
9
+ * Only forward beacons whose publishable key is one of these (`?k=` or a `wtp_` bearer); others get 403. Stops
10
+ * a third party from using your tunnel as a relay for another project's key.
11
+ */
12
+ allowKey?: string | string[];
8
13
  fetch?: typeof fetch;
9
14
  }
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. */
15
+ /** 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, plus the visitor's `Origin`/`Referer` (the edge checks the Origin against the key's allowed origins); cookies and other headers are not. */
11
16
  export declare function tunnelHandler(o: TunnelOptions): {
12
17
  GET: (r: Request) => Promise<Response>;
13
18
  POST: (r: Request) => Promise<Response>;
@@ -6,12 +6,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
6
6
  exports.tunnelHandler = tunnelHandler;
7
7
  // only what the browser SDK calls: /v1/rum/*, /v1/replay/<session>/chunks /v1/logs and /v1/traces
8
8
  const ALLOWED = /^\/v1\/(rum\/[A-Za-z0-9/_-]+|replay\/[A-Za-z0-9_-]+\/chunks|logs|traces)$/;
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. */
9
+ // `origin` / `referer`: the edge refuses a browser key without an Origin on the key's allowed origins (403 origin_not_allowed),
10
+ // so the tunnel passes through the visitor's own Origin: add your site's origin to the key's allowed origins.
11
+ const FORWARD = ['content-type', 'content-encoding', 'user-agent', 'origin', 'referer', 'x-wt-sdk', 'x-wt-mask'];
12
+ /** 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, plus the visitor's `Origin`/`Referer` (the edge checks the Origin against the key's allowed origins); cookies and other headers are not. */
11
13
  function tunnelHandler(o) {
12
14
  const base = (o.basePath ?? '/api/wt').replace(/\/+$/, '');
13
15
  const max = o.maxBodyBytes ?? 1024 * 1024;
14
16
  const edge = o.endpoint.replace(/\/+$/, '');
17
+ const allow = o.allowKey === undefined ? [] : [].concat(o.allowKey);
15
18
  const send = o.fetch ?? fetch;
16
19
  const handle = async (req) => {
17
20
  const url = new URL(req.url);
@@ -24,10 +27,18 @@ function tunnelHandler(o) {
24
27
  if (v)
25
28
  headers[h] = v;
26
29
  }
30
+ if (!headers.origin && headers.referer) { // same-origin GETs carry no Origin: use the Referer's
31
+ try {
32
+ headers.origin = new URL(headers.referer).origin;
33
+ }
34
+ catch { /* not a URL: forward as is */ }
35
+ }
27
36
  const bearer = /^Bearer (wtp_\S+)$/.exec(req.headers.get('authorization') ?? '');
28
37
  if (bearer)
29
38
  headers.authorization = `Bearer ${bearer[1]}`;
30
39
  const k = url.searchParams.get('k');
40
+ if (allow.length && ![k, bearer?.[1]].some((x) => x && allow.includes(x)))
41
+ return new Response('forbidden', { status: 403 });
31
42
  let body;
32
43
  if (req.method === 'POST') {
33
44
  if (Number(req.headers.get('content-length') ?? 0) > max)
@@ -9,4 +9,6 @@ export { querySummary };
9
9
  * failure. Works for ESM and CJS; returns an unsubscribe function (a no-op when this Node has no
10
10
  * tracing channels).
11
11
  */
12
+ /** Major version of the app's installed `postgres`, or undefined when absent or unreadable. */
13
+ export declare function postgresMajor(from?: string): number | undefined;
12
14
  export declare function instrumentPostgres(opts?: DbOptions): () => void;