@watchtowerobservability/node 0.7.9 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/README.md +31 -9
  3. package/dist/cjs/buffer.d.ts +0 -3
  4. package/dist/cjs/diagnostics.d.ts +37 -0
  5. package/dist/cjs/diagnostics.js +92 -0
  6. package/dist/cjs/filter.d.ts +0 -1
  7. package/dist/cjs/index.d.ts +1 -4
  8. package/dist/cjs/index.js +44 -9
  9. package/dist/cjs/integrations/db.js +4 -2
  10. package/dist/cjs/integrations/next-build.d.ts +3 -1
  11. package/dist/cjs/integrations/next-build.js +5 -2
  12. package/dist/cjs/integrations/next-edge.d.ts +13 -0
  13. package/dist/cjs/integrations/next-edge.js +14 -0
  14. package/dist/cjs/integrations/next.d.ts +11 -4
  15. package/dist/cjs/integrations/next.js +12 -6
  16. package/dist/cjs/late.d.ts +7 -0
  17. package/dist/cjs/late.js +28 -0
  18. package/dist/cjs/load.d.ts +6 -1
  19. package/dist/cjs/load.js +12 -2
  20. package/dist/cjs/metrics.d.ts +1 -3
  21. package/dist/cjs/metrics.js +3 -1
  22. package/dist/cjs/next-filter.d.ts +0 -1
  23. package/dist/cjs/origin.d.ts +0 -1
  24. package/dist/cjs/redact.d.ts +0 -1
  25. package/dist/cjs/register.js +2 -0
  26. package/dist/cjs/sampling.d.ts +0 -1
  27. package/dist/cjs/scrub.d.ts +0 -1
  28. package/dist/cjs/version.d.ts +1 -1
  29. package/dist/cjs/version.js +1 -1
  30. package/dist/esm/buffer.d.ts +0 -3
  31. package/dist/esm/diagnostics.d.ts +37 -0
  32. package/dist/esm/diagnostics.js +79 -0
  33. package/dist/esm/filter.d.ts +0 -1
  34. package/dist/esm/index.d.ts +1 -4
  35. package/dist/esm/index.js +45 -10
  36. package/dist/esm/integrations/db.js +5 -3
  37. package/dist/esm/integrations/next-build.d.ts +3 -1
  38. package/dist/esm/integrations/next-build.js +5 -2
  39. package/dist/esm/integrations/next-edge.d.ts +13 -0
  40. package/dist/esm/integrations/next-edge.js +8 -0
  41. package/dist/esm/integrations/next.d.ts +11 -4
  42. package/dist/esm/integrations/next.js +12 -4
  43. package/dist/esm/late.d.ts +7 -0
  44. package/dist/esm/late.js +22 -0
  45. package/dist/esm/load.d.ts +6 -1
  46. package/dist/esm/load.js +11 -2
  47. package/dist/esm/metrics.d.ts +1 -3
  48. package/dist/esm/metrics.js +3 -1
  49. package/dist/esm/next-filter.d.ts +0 -1
  50. package/dist/esm/origin.d.ts +0 -1
  51. package/dist/esm/redact.d.ts +0 -1
  52. package/dist/esm/register.js +2 -0
  53. package/dist/esm/sampling.d.ts +0 -1
  54. package/dist/esm/scrub.d.ts +0 -1
  55. package/dist/esm/version.d.ts +1 -1
  56. package/dist/esm/version.js +1 -1
  57. package/package.json +21 -49
@@ -0,0 +1,28 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.LATE_HINT = exports.lateModules = void 0;
4
+ exports.warnLate = warnLate;
5
+ exports.checkLate = checkLate;
6
+ // "Loaded too late" detector. Import this FIRST in the entry modules (register.ts, index.ts): ES imports evaluate in order, so
7
+ // the snapshot below is taken before the SDK's own dependencies load anything. Under `node --import .../register` nothing
8
+ // but Node's bootstrap has run yet, so http/https are absent from process.moduleLoadList (checked on Node 26).
9
+ /** Which of http/https are in `list` (default: this process's loaded builtins). */
10
+ const lateModules = (list = process.moduleLoadList ?? []) => ['http', 'https'].filter((m) => list.includes(`NativeModule ${m}`));
11
+ exports.lateModules = lateModules;
12
+ const early = (0, exports.lateModules)();
13
+ const KEY = Symbol.for('watchtower.node.late-warned');
14
+ exports.LATE_HINT = 'Start node with --import @watchtowerobservability/node/register';
15
+ /** Prints once per process (global flag, so the CJS and ESM copies share it). */
16
+ function warnLate(mods, out = (m) => console.warn(m)) {
17
+ const g = globalThis;
18
+ if (!mods.length || g[KEY])
19
+ return;
20
+ g[KEY] = true;
21
+ out(`[watchtower] loaded too late: ${mods[0]} was already imported, so its requests are not traced. ${exports.LATE_HINT}`);
22
+ }
23
+ /** The entry points call this: silent under Next (it loads http before instrumentation runs) and in test runners. */
24
+ function checkLate() {
25
+ if (process.env.NEXT_RUNTIME || process.env.NODE_ENV === 'test' || process.env.VITEST)
26
+ return;
27
+ warnLate(early);
28
+ }
@@ -2,8 +2,13 @@
2
2
  export declare function searchPaths(): string[];
3
3
  export declare function load(id: string): unknown;
4
4
  export declare const SDK_PEERS: string[];
5
- /** Load an OpenTelemetry SDK package (an optional peer); a missing one throws an error naming what to install. */
5
+ /** Load an OpenTelemetry SDK package (a dependency, loaded lazily); a missing one throws an error naming what to install. */
6
6
  export declare function need<T>(id: string): T;
7
7
  export declare const STANDALONE_HINT = "use withWatchtower() from @watchtowerobservability/next (node SDK 0.7.9 or later) in next.config";
8
8
  /** Required OpenTelemetry peers that cannot be loaded from the SDK's location or the app root. */
9
9
  export declare function missingPeers(): string[];
10
+ /**
11
+ * Never called. Literal names so file tracers (Next's standalone nft) copy the SDK packages together with their pnpm
12
+ * links, which outputFileTracingIncludes cannot do. Safe for bundlers: these are dependencies, so always installed.
13
+ */
14
+ export declare const tracedPackages: () => Promise<unknown>[];
package/dist/cjs/load.js CHANGED
@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.STANDALONE_HINT = exports.SDK_PEERS = void 0;
6
+ exports.tracedPackages = exports.STANDALONE_HINT = exports.SDK_PEERS = void 0;
7
7
  exports.searchPaths = searchPaths;
8
8
  exports.load = load;
9
9
  exports.need = need;
@@ -42,7 +42,7 @@ exports.SDK_PEERS = [
42
42
  '@opentelemetry/exporter-metrics-otlp-http', '@opentelemetry/exporter-trace-otlp-http', '@opentelemetry/otlp-transformer',
43
43
  '@opentelemetry/resources', '@opentelemetry/sdk-logs', '@opentelemetry/sdk-metrics', '@opentelemetry/sdk-trace',
44
44
  ];
45
- /** Load an OpenTelemetry SDK package (an optional peer); a missing one throws an error naming what to install. */
45
+ /** Load an OpenTelemetry SDK package (a dependency, loaded lazily); a missing one throws an error naming what to install. */
46
46
  function need(id) {
47
47
  try {
48
48
  return load(id);
@@ -67,3 +67,13 @@ function missingPeers() {
67
67
  }
68
68
  });
69
69
  }
70
+ /**
71
+ * Never called. Literal names so file tracers (Next's standalone nft) copy the SDK packages together with their pnpm
72
+ * links, which outputFileTracingIncludes cannot do. Safe for bundlers: these are dependencies, so always installed.
73
+ */
74
+ const tracedPackages = () => [
75
+ import('@opentelemetry/context-async-hooks'), import('@opentelemetry/core'), import('@opentelemetry/exporter-logs-otlp-http'),
76
+ import('@opentelemetry/exporter-metrics-otlp-http'), import('@opentelemetry/exporter-trace-otlp-http'), import('@opentelemetry/otlp-transformer'),
77
+ import('@opentelemetry/resources'), import('@opentelemetry/sdk-logs'), import('@opentelemetry/sdk-metrics'), import('@opentelemetry/sdk-trace'),
78
+ ];
79
+ exports.tracedPackages = tracedPackages;
@@ -1,6 +1,4 @@
1
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
2
1
  import type { Resource } from '@opentelemetry/resources';
3
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
4
2
  import type { MeterProvider, PushMetricExporter } from '@opentelemetry/sdk-metrics';
5
3
  /** Explicit flag, else `WATCHTOWER_LOGS` / `WATCHTOWER_METRICS` (default on); `OTEL_*_EXPORTER=none` turns it off. */
6
4
  export declare function switchOn(name: string, otelExporterEnv: string, flag?: boolean): boolean;
@@ -8,4 +6,4 @@ export interface Metrics {
8
6
  provider: MeterProvider;
9
7
  stop(): void;
10
8
  }
11
- export declare function startMetrics(endpoint: string, headers: Record<string, string>, resource: Resource, bufferDir: string | undefined, fetch: typeof globalThis.fetch, exporter?: PushMetricExporter): Metrics;
9
+ export declare function startMetrics(endpoint: string, headers: Record<string, string>, resource: Resource, bufferDir: string | undefined, fetch: typeof globalThis.fetch, exporter?: PushMetricExporter, wrap?: (e: PushMetricExporter) => PushMetricExporter): Metrics;
@@ -51,7 +51,7 @@ function switchOn(name, otelExporterEnv, flag) {
51
51
  return false;
52
52
  return !['off', 'false', '0', 'no'].includes((env[name] || 'on').trim().toLowerCase());
53
53
  }
54
- function startMetrics(endpoint, headers, resource, bufferDir, fetch, exporter) {
54
+ function startMetrics(endpoint, headers, resource, bufferDir, fetch, exporter, wrap) {
55
55
  const sdk = (0, load_js_1.need)('@opentelemetry/sdk-metrics');
56
56
  const url = `${endpoint}/v1/metrics`;
57
57
  let exp = exporter;
@@ -62,6 +62,8 @@ function startMetrics(endpoint, headers, resource, bufferDir, fetch, exporter) {
62
62
  exp = new OTLPMetricExporter({ url, headers, ...delta });
63
63
  if (bufferDir)
64
64
  exp = new buffer_js_1.MetricSpool(exp, nodePath.join(bufferDir, 'metrics'), url, headers, fetch);
65
+ if (wrap)
66
+ exp = wrap(exp);
65
67
  }
66
68
  const interval = Number(process.env.OTEL_METRIC_EXPORT_INTERVAL) || 60000;
67
69
  const reader = new sdk.PeriodicExportingMetricReader({
@@ -1,4 +1,3 @@
1
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
2
1
  import type { ReadableSpan } from '@opentelemetry/sdk-trace';
3
2
  /** Whether `span` is one of Next's internal spans (not a request, route handler, render, server action or fetch). */
4
3
  export declare function isNextInternal(span: ReadableSpan): boolean;
@@ -1,4 +1,3 @@
1
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
2
1
  import type { SpanProcessor } from '@opentelemetry/sdk-trace';
3
2
  export interface Frame {
4
3
  file: string;
@@ -1,4 +1,3 @@
1
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
2
1
  import type { SpanProcessor } from '@opentelemetry/sdk-trace';
3
2
  export type RedactHook = (key: string, value: unknown) => unknown;
4
3
  /** Hook keys for the non-attribute fields. Event attributes (incl. exception.message / exception.stacktrace) use their own keys. */
@@ -3,10 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  // Preload entry: `node --import @watchtowerobservability/node/register app.mjs` (ESM) or `node -r @watchtowerobservability/node/register app.js` (CommonJS).
4
4
  // Starts the SDK from WT_*/OTEL_* env before the app loads, so http, fetch, pg and ioredis are patched in time.
5
5
  // Without WT_INGEST_KEY it starts nothing and says so.
6
+ const late_js_1 = require("./late.js"); // first: snapshots which builtins were loaded before the SDK
6
7
  const node_url_1 = require("node:url");
7
8
  const node_module_1 = require("node:module");
8
9
  const index_js_1 = require("./index.js");
9
10
  const load_js_1 = require("./load.js");
11
+ (0, late_js_1.checkLate)();
10
12
  if (process.env.WT_INGEST_KEY || process.env.OTEL_EXPORTER_OTLP_HEADERS) {
11
13
  try {
12
14
  // ESM modules (node:http imported from an ES module) are only patched through OpenTelemetry's loader hook
@@ -1,5 +1,4 @@
1
1
  import type { Attributes, Context, Link, SpanKind } from '@opentelemetry/api';
2
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
3
2
  import type { Sampler, SamplingResult } from '@opentelemetry/sdk-trace';
4
3
  export interface SamplingRule {
5
4
  name?: string;
@@ -1,4 +1,3 @@
1
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
2
1
  import type { SpanProcessor } from '@opentelemetry/sdk-trace';
3
2
  /**
4
3
  * A path segment that looks like a secret: UUID, hex run >= 16, JWT, digit run >= 16, or an opaque token (>= 16 chars of
@@ -1,2 +1,2 @@
1
1
  /** This package's version (test/distro.test.ts checks it against package.json); sent as `telemetry.distro.version`. */
2
- export declare const VERSION = "0.7.9";
2
+ export declare const VERSION = "0.8.1";
@@ -2,4 +2,4 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.VERSION = void 0;
4
4
  /** This package's version (test/distro.test.ts checks it against package.json); sent as `telemetry.distro.version`. */
5
- exports.VERSION = '0.7.9';
5
+ exports.VERSION = '0.8.1';
@@ -1,8 +1,5 @@
1
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
2
1
  import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace';
3
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
4
2
  import type { LogRecordExporter, ReadableLogRecord } from '@opentelemetry/sdk-logs';
5
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
6
3
  import type { AggregationTemporality, InstrumentType, PushMetricExporter, ResourceMetrics } from '@opentelemetry/sdk-metrics';
7
4
  type Done = Parameters<SpanExporter['export']>[1];
8
5
  /** What the spool wraps: a span, log record or metric exporter; `B` is one export batch. */
@@ -0,0 +1,37 @@
1
+ import type { SpanExporter } from '@opentelemetry/sdk-trace';
2
+ import type { LogRecordExporter } from '@opentelemetry/sdk-logs';
3
+ import type { PushMetricExporter } from '@opentelemetry/sdk-metrics';
4
+ export type Signal = 'traces' | 'logs' | 'metrics';
5
+ type Result = {
6
+ code: number;
7
+ error?: Error;
8
+ };
9
+ export declare const debugOn: () => boolean;
10
+ /** First 8 characters only. */
11
+ export declare const keyHint: (k: string) => string;
12
+ export declare const debug: (m: string) => void;
13
+ /** HTTP status or error text of a failed export (the OTLP exporters put the status in `code` or the message). */
14
+ export declare function failure(e: (Error & {
15
+ code?: unknown;
16
+ }) | undefined): string;
17
+ export declare class StatusLine {
18
+ private readonly o;
19
+ private readonly out;
20
+ private st;
21
+ private printed;
22
+ constructor(o: {
23
+ service: string;
24
+ endpoint: string;
25
+ release?: string;
26
+ off?: Signal[];
27
+ }, out?: (m: string) => void);
28
+ /** One result for `signal`: the first failure and the last pending signal turning ok both print the line. */
29
+ record(signal: Signal, items: number, r: Result): void;
30
+ print(): void;
31
+ }
32
+ export declare const watchSpans: (e: SpanExporter, l: StatusLine) => SpanExporter;
33
+ export declare const watchLogs: (e: LogRecordExporter, l: StatusLine) => LogRecordExporter;
34
+ export declare const watchMetrics: (e: PushMetricExporter, l: StatusLine) => PushMetricExporter;
35
+ export declare function noteDrop(kind: string): void;
36
+ export declare function flushDrops(): void;
37
+ export {};
@@ -0,0 +1,79 @@
1
+ export const debugOn = () => ['1', 'true', 'on', 'yes'].includes((process.env.WT_DEBUG ?? process.env.WATCHTOWER_DEBUG ?? '').trim().toLowerCase());
2
+ /** First 8 characters only. */
3
+ export const keyHint = (k) => `${k.slice(0, 8)}…`;
4
+ export const debug = (m) => { if (debugOn())
5
+ console.info(`[watchtower:debug] ${m}`); };
6
+ /** HTTP status or error text of a failed export (the OTLP exporters put the status in `code` or the message). */
7
+ export function failure(e) {
8
+ const m = /\bstatus(?: code)?:? (\d{3})\b/i.exec(e?.message ?? '');
9
+ return String((typeof e?.code === 'number' ? e.code : undefined) ?? m?.[1] ?? e?.message ?? 'error').split('\n')[0].slice(0, 80);
10
+ }
11
+ const quiet = () => process.env.NODE_ENV === 'test' && !debugOn();
12
+ export class StatusLine {
13
+ o;
14
+ out;
15
+ st;
16
+ printed = false;
17
+ constructor(o, out = (m) => { if (!quiet())
18
+ console.info(m); }) {
19
+ this.o = o;
20
+ this.out = out;
21
+ this.st = { traces: 'pending', logs: 'pending', metrics: 'pending' };
22
+ for (const s of o.off ?? [])
23
+ this.st[s] = 'off';
24
+ // a signal that never fires (no logs yet, metrics every 60 s) must not hide the line forever
25
+ const t = setTimeout(() => this.print(), 90_000);
26
+ t.unref?.();
27
+ }
28
+ /** One result for `signal`: the first failure and the last pending signal turning ok both print the line. */
29
+ record(signal, items, r) {
30
+ const fail = r.code !== 0;
31
+ const why = fail ? failure(r.error) : '';
32
+ debug(`export ${signal} items=${items} ${fail ? `fail(${why})` : 'ok'}`);
33
+ if (fail) {
34
+ if (this.st[signal] !== 'ok')
35
+ this.st[signal] = `fail(${why})`;
36
+ this.print();
37
+ return;
38
+ }
39
+ this.st[signal] = 'ok';
40
+ if (Object.values(this.st).every((s) => s !== 'pending'))
41
+ this.print();
42
+ }
43
+ print() {
44
+ if (this.printed)
45
+ return;
46
+ this.printed = true;
47
+ let host = this.o.endpoint;
48
+ try {
49
+ host = new URL(this.o.endpoint).host;
50
+ }
51
+ catch { /* keep as given */ }
52
+ const s = this.st;
53
+ this.out(`[watchtower] ${this.o.service} → ${host} traces:${s.traces} logs:${s.logs} metrics:${s.metrics} release=${this.o.release ?? 'none'}`);
54
+ }
55
+ }
56
+ const countMetrics = (m) => (m?.scopeMetrics ?? []).reduce((n, s) => n + s.metrics.length, 0);
57
+ function watch(inner, signal, line, count) {
58
+ const wrapped = Object.create(inner); // keeps every other exporter method (selectAggregation etc.)
59
+ wrapped.export = (items, done) => inner.export(items, (r) => { line.record(signal, count(items), r); done(r); });
60
+ return wrapped;
61
+ }
62
+ export const watchSpans = (e, l) => watch(e, 'traces', l, (i) => i.length);
63
+ export const watchLogs = (e, l) => watch(e, 'logs', l, (i) => i.length);
64
+ export const watchMetrics = (e, l) => watch(e, 'metrics', l, countMetrics);
65
+ // Drop counters: Next-internal spans (sampling) and DB queries without a parent span. Summarised per minute under WT_DEBUG.
66
+ const drops = new Map();
67
+ let timer;
68
+ export function noteDrop(kind) {
69
+ drops.set(kind, (drops.get(kind) ?? 0) + 1);
70
+ if (!timer && debugOn()) {
71
+ timer = setInterval(flushDrops, 60_000);
72
+ timer.unref?.();
73
+ }
74
+ }
75
+ export function flushDrops() {
76
+ if (drops.size)
77
+ debug(`dropped in the last minute: ${[...drops].map(([k, n]) => `${n} ${k}`).join(', ')}`);
78
+ drops.clear();
79
+ }
@@ -1,4 +1,3 @@
1
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
2
1
  import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace';
3
2
  export declare function filterExporter(inner: SpanExporter, keep: (s: ReadableSpan) => boolean): SpanExporter;
4
3
  /**
@@ -1,13 +1,9 @@
1
1
  import { inspect } from 'node:util';
2
2
  import { metrics, trace } from '@opentelemetry/api';
3
3
  import type { Tracer } from '@opentelemetry/api';
4
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
5
4
  import type { Resource } from '@opentelemetry/resources';
6
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
7
5
  import type { ReadableSpan, TracerProvider } from '@opentelemetry/sdk-trace';
8
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
9
6
  import type { LoggerProvider } from '@opentelemetry/sdk-logs';
10
- // @ts-ignore optional peer: absent -> any (keeps skipLibCheck:false consumers compiling)
11
7
  import type { MeterProvider } from '@opentelemetry/sdk-metrics';
12
8
  import type { RedactHook } from './redact.js';
13
9
  import type { RedactPreset } from './redact-presets.js';
@@ -208,6 +204,7 @@ export declare class Client implements InitStatus {
208
204
  observe<A extends unknown[], R>(name: string, fn: (...a: A) => R): (...a: A) => R;
209
205
  shutdown(): Promise<void>;
210
206
  }
207
+ /** Never throws: when a peer is missing, the key is absent or startup fails, it warns once, leaves telemetry off and returns a no-op client. */
211
208
  export declare function init(opts: InitOptions): Client;
212
209
  /** Why telemetry is off (set by the preload when it cannot start); shown on the first dropped helper call. */
213
210
  export declare const setOffReason: (r: string) => void;
package/dist/esm/index.js CHANGED
@@ -1,10 +1,11 @@
1
1
  // Thin Watchtower layer over the OpenTelemetry Node SDK: key header, endpoint default,
2
2
  // offline buffer, wt.*-safe resource attributes, redaction hook, getPrompt/score/evaluate/observe.
3
+ import { checkLate } from './late.js'; // first: snapshots which builtins were loaded before the SDK
3
4
  import { inspect } from 'node:util';
4
5
  import { context, diag, metrics, propagation, trace } from '@opentelemetry/api';
5
6
  import { missingPeers, need as needPeer, STANDALONE_HINT } from './load.js';
6
7
  import { defaultResourceDetectors, otelEnv, resolveRelease } from './env.js';
7
- import { dbRequireParent, setHttpServerActive } from './integrations/db.js';
8
+ import { setHttpServerActive } from './integrations/db.js';
8
9
  import { instrumentAll } from './instrument.js';
9
10
  import { LOG_BODY_KEY, redactor } from './redact.js';
10
11
  import { resolveRedact } from './redact-presets.js';
@@ -12,6 +13,7 @@ import { foreignProvider, attachProcessors } from './attach.js';
12
13
  import { scrubUrl, urlScrubber } from './scrub.js';
13
14
  import { filterExporter, isNoisySpan, quotaWarnExporter } from './filter.js';
14
15
  import { nextInternalsFilter } from './next-filter.js';
16
+ import { debug, keyHint, noteDrop, StatusLine, watchLogs, watchMetrics, watchSpans } from './diagnostics.js';
15
17
  import { checkin as runCheckin } from './checkin.js';
16
18
  import { checkIn as checkInFor, withMonitor as withMonitorFor } from './cron/monitor.js';
17
19
  import { installSignalFlush } from './shutdown.js';
@@ -107,6 +109,11 @@ export class Client {
107
109
  this.redact = red.hook;
108
110
  this.scrubUrls = o.urlScrubbing ?? red.preset !== 'off';
109
111
  this.logCaller = o.logCaller ?? env.WATCHTOWER_LOG_CALLER === '1';
112
+ const logsOn = switchOn('WATCHTOWER_LOGS', 'OTEL_LOGS_EXPORTER', o.logs ?? (o.logExporter ? true : undefined));
113
+ const metricsOn = switchOn('WATCHTOWER_METRICS', 'OTEL_METRICS_EXPORTER', o.metrics ?? (o.metricExporter ? true : undefined));
114
+ // one status line per process, fed by the default OTLP exporters (explicit test exporters are left alone)
115
+ const line = new StatusLine({ service: String(resource.attributes['service.name']), endpoint: this.endpoint, release, off: [...(logsOn ? [] : ['logs']), ...(metricsOn ? [] : ['metrics'])] });
116
+ debug(`exporters: ${this.endpoint}/v1/traces, /v1/logs, /v1/metrics key=${keyHint(apiKey)}`);
110
117
  let exporter = o.exporter;
111
118
  if (!exporter) {
112
119
  const url = `${this.endpoint}/v1/traces`;
@@ -115,6 +122,7 @@ export class Client {
115
122
  // spans and log records spool to their own subdirectories
116
123
  if (o.bufferDir)
117
124
  exporter = new SpoolExporter(exporter, nodePath.join(o.bufferDir, 'traces'), url, this.headers, this.fetch);
125
+ exporter = watchSpans(exporter, line);
118
126
  }
119
127
  const keepNoisy = o.noisySpans ?? env.WT_NOISY_SPANS === '1';
120
128
  const user = o.spanFilter;
@@ -152,7 +160,6 @@ export class Client {
152
160
  }
153
161
  this.tracer = this.provider.getTracer('watchtower');
154
162
  // an explicit exporter never switches the other signals off: only `logs` / `metrics` / the env switches do
155
- const logsOn = switchOn('WATCHTOWER_LOGS', 'OTEL_LOGS_EXPORTER', o.logs ?? (o.logExporter ? true : undefined));
156
163
  this.logs = logsOn ? 'ok' : 'disabled';
157
164
  let logExporter = logsOn ? o.logExporter : undefined;
158
165
  if (logsOn && !logExporter) {
@@ -161,6 +168,7 @@ export class Client {
161
168
  logExporter = new OTLPLogExporter({ url, headers: this.headers });
162
169
  if (o.bufferDir)
163
170
  logExporter = spoolLogs(logExporter, nodePath.join(o.bufferDir, 'logs'), url, this.headers, this.fetch);
171
+ logExporter = watchLogs(logExporter, line);
164
172
  }
165
173
  const { LoggerProvider: LP, BatchLogRecordProcessor } = needPeer('@opentelemetry/sdk-logs');
166
174
  this.loggerProvider = new LP({
@@ -168,8 +176,8 @@ export class Client {
168
176
  processors: !logExporter ? [] : [new BatchLogRecordProcessor({ exporter: logExporter })],
169
177
  });
170
178
  this.logger = this.loggerProvider.getLogger('watchtower');
171
- if (switchOn('WATCHTOWER_METRICS', 'OTEL_METRICS_EXPORTER', o.metrics ?? (o.metricExporter ? true : undefined))) {
172
- const m = startMetrics(this.endpoint, this.headers, resource, o.bufferDir, this.fetch, o.metricExporter);
179
+ if (metricsOn) {
180
+ const m = startMetrics(this.endpoint, this.headers, resource, o.bufferDir, this.fetch, o.metricExporter, (e) => watchMetrics(e, line));
173
181
  this.meterProvider = m.provider;
174
182
  this.stopRuntime = m.stop;
175
183
  }
@@ -356,14 +364,44 @@ function registerGlobals(c) {
356
364
  diag.warn(w);
357
365
  }
358
366
  }
367
+ /** A Client-shaped stand-in for when telemetry cannot start: every method does nothing, observe/checkin pass the function through. */
368
+ function offClient() {
369
+ const fns = {
370
+ observe: (_n, f) => f,
371
+ checkin: (_s, f) => Promise.resolve().then(f),
372
+ log: () => undefined,
373
+ toJSON: () => ({}),
374
+ evaluate: () => Promise.resolve([]),
375
+ evaluateResume: () => Promise.resolve([]),
376
+ };
377
+ const plain = { traces: 'disabled', metrics: 'disabled', logs: 'disabled', blocked: [], warnings: [], attached: false };
378
+ return new Proxy({}, { get: (_t, k) => (typeof k === 'symbol' || k === 'then' ? undefined : k in plain ? plain[k] : fns[k] ?? (() => Promise.resolve(undefined))) });
379
+ }
380
+ /** Never throws: when a peer is missing, the key is absent or startup fails, it warns once, leaves telemetry off and returns a no-op client. */
359
381
  export function init(opts) {
360
- defaultResourceDetectors(); // before any NodeSDK reads OTEL_NODE_RESOURCE_DETECTORS
361
382
  const missing = missingPeers();
362
383
  if (missing.length)
363
- console.warn(`[watchtower] missing OpenTelemetry package(s): ${missing.join(', ')}. Next.js standalone: ${STANDALONE_HINT}. Otherwise: npm install ${missing.join(' ')}`);
384
+ return turnOff(`missing OpenTelemetry package(s): ${missing.join(', ')}. Next.js standalone: ${STANDALONE_HINT}. Otherwise: npm install ${missing.join(' ')}`);
385
+ try {
386
+ return start(opts);
387
+ }
388
+ catch (e) {
389
+ return turnOff(e?.message ?? String(e));
390
+ }
391
+ }
392
+ function turnOff(why) {
393
+ state.current = undefined;
394
+ setOffReason(why);
395
+ console.warn(`[watchtower] telemetry is OFF: ${why}`);
396
+ return offClient();
397
+ }
398
+ function start(opts) {
399
+ checkLate();
400
+ defaultResourceDetectors(); // before any NodeSDK reads OTEL_NODE_RESOURCE_DETECTORS
364
401
  const nextMode = opts?.nextInternals ?? (process.env.NEXT_RUNTIME ? 'sample' : undefined);
365
402
  if (nextMode) {
366
- const own = nextInternalsFilter(nextMode, opts?.nextInternalsRate);
403
+ const base = nextInternalsFilter(nextMode, opts?.nextInternalsRate);
404
+ const own = (s) => base(s) || (noteDrop('Next.js internal spans (nextInternals sampling)'), false);
367
405
  const user = opts.spanFilter;
368
406
  opts = { ...opts, nextInternals: undefined, spanFilter: user ? (s) => own(s) && user(s) : own }; // cleared: a second init() never stacks the filter
369
407
  }
@@ -382,9 +420,6 @@ export function init(opts) {
382
420
  if (mode === 'auto' && logOn) {
383
421
  console.info(`[watchtower] instrumented: ${names.map((n) => n.replace('@opentelemetry/instrumentation-', '')).join(', ') || 'nothing (no supported package found)'}`);
384
422
  }
385
- if (logOn && dbRequireParent(undefined)) {
386
- console.info('watchtower: requireParent on; queries outside a span are not recorded (WATCHTOWER_DB_REQUIRE_PARENT=0 to keep them)');
387
- }
388
423
  }
389
424
  if (process.env.WT_PROFILING === '1') {
390
425
  const attrs = c.resource.attributes;
@@ -2,7 +2,8 @@
2
2
  // statement hash and N+1 hint, connection-pool metrics and embedded-store gauges.
3
3
  import * as fs from 'node:fs';
4
4
  import * as nodePath from 'node:path';
5
- import { context, createContextKey, diag, INVALID_SPAN_CONTEXT, metrics, trace, SpanKind, SpanStatusCode } from '@opentelemetry/api';
5
+ import { context, createContextKey, INVALID_SPAN_CONTEXT, metrics, trace, SpanKind, SpanStatusCode } from '@opentelemetry/api';
6
+ import { noteDrop } from '../diagnostics.js';
6
7
  import { isPgDialect, normalizeAndHash, querySummary } from '../sql.js';
7
8
  /** Set inside an instrumented call so a wrapper the library calls internally adds no second span. */
8
9
  const INSIDE = createContextKey('watchtower.db.inside');
@@ -43,10 +44,11 @@ let droppedSpans = 0;
43
44
  let droppedCounter;
44
45
  /** Datastore spans dropped so far because `requireParent` found no active parent span. */
45
46
  export const droppedDbSpans = () => droppedSpans;
46
- /** Count a dropped span: the `wt.sdk.db.dropped_spans` counter (exported with the SDK's metrics) and one diag warning. */
47
+ /** Count a dropped span: the `wt.sdk.db.dropped_spans` counter (exported with the SDK's metrics) and one console line (the first drop). */
47
48
  function dropped() {
48
49
  if (droppedSpans++ === 0)
49
- 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');
50
+ console.info('[watchtower] dropped a DB query outside any span (requireParent on; WATCHTOWER_DB_REQUIRE_PARENT=0 to keep them)');
51
+ noteDrop('DB queries outside any span');
50
52
  droppedCounter ??= metrics.getMeter('watchtower').createCounter('wt.sdk.db.dropped_spans', { description: 'Datastore spans dropped for lack of a parent span (requireParent)' });
51
53
  droppedCounter.add(1);
52
54
  return trace.wrapSpanContext(INVALID_SPAN_CONTEXT);
@@ -51,16 +51,18 @@ export declare function tracingIncludes(ids: string[], cwd?: string): string[];
51
51
  * the SDK starts whichever entry instrumentation imports. Sets `NEXT_PUBLIC_WT_RELEASE`. With `sourcemaps` it turns on
52
52
  * `productionBrowserSourceMaps` (webpack and Turbopack); `{ upload: true }` uploads and deletes them after the webpack
53
53
  * client build, otherwise run `wt-next-sourcemaps` after `next build` (`"build": "next build && wt-next-sourcemaps"`).
54
+ * @deprecated use `withWatchtower` from `@watchtowerobservability/next`
54
55
  */
55
56
  export declare function withWatchtower(config?: ConfigOrFn, opts?: WatchtowerNextOptions): ConfigOrFn;
56
57
  /** A ustar archive of `[name, bytes]` (names up to 100 bytes). */
57
58
  export declare function makeTar(files: [string, Buffer][]): Buffer;
58
59
  /**
59
- * Upload every `.map` under `dir` as `_next/static/<path>` for the release: one `POST /artifacts/bundle` per ~120 MB
60
+ * Upload every `.map` under `dir` as `_next/static/<path>` for the release: one `POST /artifacts/bundle` per ~32 MB
60
61
  * batch (tar.gz plus manifest), falling back to single uploads (8 at a time) when the server has no bundle route.
61
62
  * 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
62
63
  * `{uploaded, skipped, failed}`: `skipped` = the server already had those exact bytes (HTTP 200). Bodies are sent
63
64
  * gzipped (`Content-Encoding: gzip`).
65
+ * @deprecated use `@watchtowerobservability/next`
64
66
  */
65
67
  export declare function uploadSourcemaps(o?: SourcemapOptions): Promise<{
66
68
  uploaded: number;
@@ -1,3 +1,4 @@
1
+ // Deprecated entry (`@watchtowerobservability/node/next-build`): use `@watchtowerobservability/next`. Still works unchanged.
1
2
  // Build-time helpers for Next.js: `withWatchtower` (next.config) and `uploadSourcemaps` (after `next build`).
2
3
  import * as fs from 'node:fs';
3
4
  import * as nodePath from 'node:path';
@@ -82,6 +83,7 @@ const SHA_ENV = ['WT_RELEASE', 'GITHUB_SHA', 'CI_COMMIT_SHA', 'VERCEL_GIT_COMMIT
82
83
  * the SDK starts whichever entry instrumentation imports. Sets `NEXT_PUBLIC_WT_RELEASE`. With `sourcemaps` it turns on
83
84
  * `productionBrowserSourceMaps` (webpack and Turbopack); `{ upload: true }` uploads and deletes them after the webpack
84
85
  * client build, otherwise run `wt-next-sourcemaps` after `next build` (`"build": "next build && wt-next-sourcemaps"`).
86
+ * @deprecated use `withWatchtower` from `@watchtowerobservability/next`
85
87
  */
86
88
  export function withWatchtower(config = {}, opts = {}) {
87
89
  const sm = opts.sourcemaps === true ? {} : opts.sourcemaps || undefined;
@@ -177,11 +179,12 @@ function chunkFor(mapFile, name) {
177
179
  return undefined;
178
180
  }
179
181
  /**
180
- * Upload every `.map` under `dir` as `_next/static/<path>` for the release: one `POST /artifacts/bundle` per ~120 MB
182
+ * Upload every `.map` under `dir` as `_next/static/<path>` for the release: one `POST /artifacts/bundle` per ~32 MB
181
183
  * batch (tar.gz plus manifest), falling back to single uploads (8 at a time) when the server has no bundle route.
182
184
  * 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
183
185
  * `{uploaded, skipped, failed}`: `skipped` = the server already had those exact bytes (HTTP 200). Bodies are sent
184
186
  * gzipped (`Content-Encoding: gzip`).
187
+ * @deprecated use `@watchtowerobservability/next`
185
188
  */
186
189
  export async function uploadSourcemaps(o = {}) {
187
190
  const env = process.env;
@@ -265,7 +268,7 @@ export async function uploadSourcemaps(o = {}) {
265
268
  };
266
269
  // One request per batch (tar.gz + manifest). A server without the bundle route (or a request that
267
270
  // never got through) falls back to concurrent single uploads for that batch.
268
- const BATCH_BYTES = 120 * 1024 * 1024;
271
+ const BATCH_BYTES = 32 * 1024 * 1024; // smaller requests keep the API's upload memory low
269
272
  const batches = [];
270
273
  let cur = [], curBytes = 0;
271
274
  for (const e of entries) {
@@ -0,0 +1,13 @@
1
+ type Opts = Record<string, unknown>;
2
+ export type NextOptions = Opts;
3
+ export type SourcemapOptions = Opts;
4
+ export type TunnelOptions = Opts;
5
+ /** @deprecated use `@watchtowerobservability/next` */
6
+ export declare const makeRegister: (_options?: NextOptions) => (() => Promise<void>);
7
+ /** @deprecated use `@watchtowerobservability/next` */
8
+ export declare const register: () => Promise<void>;
9
+ /** @deprecated use `@watchtowerobservability/next` */
10
+ export declare function onRequestError(_err?: unknown, _request?: unknown, _context?: unknown): Promise<void>;
11
+ /** @deprecated use `@watchtowerobservability/next` */
12
+ export declare const withWatchtower: <T>(config: T, _opts?: Opts) => T;
13
+ export {};
@@ -0,0 +1,8 @@
1
+ /** @deprecated use `@watchtowerobservability/next` */
2
+ export const makeRegister = (_options = {}) => async () => { };
3
+ /** @deprecated use `@watchtowerobservability/next` */
4
+ export const register = makeRegister();
5
+ /** @deprecated use `@watchtowerobservability/next` */
6
+ export async function onRequestError(_err, _request, _context) { }
7
+ /** @deprecated use `@watchtowerobservability/next` */
8
+ export const withWatchtower = (config, _opts) => config;
@@ -1,15 +1,22 @@
1
1
  import * as wt from '../index.js';
2
- export { withWatchtower, uploadSourcemaps } from './next-build.js';
2
+ import * as build from './next-build.js';
3
+ /** @deprecated use `withWatchtower` from `@watchtowerobservability/next` */
4
+ export declare const withWatchtower: typeof build.withWatchtower;
5
+ /** @deprecated use `uploadSourcemaps` from `@watchtowerobservability/next` */
6
+ export declare const uploadSourcemaps: typeof build.uploadSourcemaps;
3
7
  export type { SourcemapOptions } from './next-build.js';
4
8
  export { isNextInternal, nextInternalsFilter } from '../next-filter.js';
5
9
  export { tunnelHandler } from './next-tunnel.js';
6
10
  export type { TunnelOptions } from './next-tunnel.js';
7
11
  export type NextOptions = wt.InitOptions;
8
- /** Build a Next.js instrumentation `register` that passes `options` to `init`; no-op off the Node.js runtime or without a key. */
12
+ /** @deprecated use `register` from `@watchtowerobservability/next`.
13
+ * Build a Next.js instrumentation `register` that passes `options` to `init`; no-op off the Node.js runtime or without a key. */
9
14
  export declare function makeRegister(options?: NextOptions): () => Promise<void>;
10
- /** Next.js instrumentation hook: init from WT_* env on the Node.js runtime; no-op without WT_INGEST_KEY. */
15
+ /** @deprecated use `register` from `@watchtowerobservability/next`.
16
+ * Next.js instrumentation hook: init from WT_* env on the Node.js runtime; no-op without WT_INGEST_KEY. */
11
17
  export declare const register: () => Promise<void>;
12
- /** Next.js onRequestError: server render, route handler and server action errors. */
18
+ /** @deprecated use `onRequestError` from `@watchtowerobservability/next`.
19
+ * Next.js onRequestError: server render, route handler and server action errors. */
13
20
  export declare function onRequestError(err: unknown, request?: {
14
21
  path?: string;
15
22
  method?: string;
@@ -1,10 +1,16 @@
1
+ // Deprecated entry: use `@watchtowerobservability/next` (register, onRequestError, withWatchtower). Still works unchanged.
1
2
  // instrumentation.js: module.exports = require('@watchtowerobservability/node/next');
2
3
  // or, with options: export const register = makeRegister({ redact }); export { onRequestError } from '@watchtowerobservability/node/next';
3
4
  import * as wt from '../index.js';
4
- export { withWatchtower, uploadSourcemaps } from './next-build.js';
5
+ import * as build from './next-build.js';
6
+ /** @deprecated use `withWatchtower` from `@watchtowerobservability/next` */
7
+ export const withWatchtower = build.withWatchtower;
8
+ /** @deprecated use `uploadSourcemaps` from `@watchtowerobservability/next` */
9
+ export const uploadSourcemaps = build.uploadSourcemaps;
5
10
  export { isNextInternal, nextInternalsFilter } from '../next-filter.js';
6
11
  export { tunnelHandler } from './next-tunnel.js';
7
- /** Build a Next.js instrumentation `register` that passes `options` to `init`; no-op off the Node.js runtime or without a key. */
12
+ /** @deprecated use `register` from `@watchtowerobservability/next`.
13
+ * Build a Next.js instrumentation `register` that passes `options` to `init`; no-op off the Node.js runtime or without a key. */
8
14
  export function makeRegister(options = {}) {
9
15
  return async function register() {
10
16
  const rt = process.env.NEXT_RUNTIME;
@@ -13,9 +19,11 @@ export function makeRegister(options = {}) {
13
19
  wt.init({ ...options, nextInternals: options.nextInternals ?? 'sample' }); // init() applies the filter (once)
14
20
  };
15
21
  }
16
- /** Next.js instrumentation hook: init from WT_* env on the Node.js runtime; no-op without WT_INGEST_KEY. */
22
+ /** @deprecated use `register` from `@watchtowerobservability/next`.
23
+ * Next.js instrumentation hook: init from WT_* env on the Node.js runtime; no-op without WT_INGEST_KEY. */
17
24
  export const register = makeRegister();
18
- /** Next.js onRequestError: server render, route handler and server action errors. */
25
+ /** @deprecated use `onRequestError` from `@watchtowerobservability/next`.
26
+ * Next.js onRequestError: server render, route handler and server action errors. */
19
27
  export async function onRequestError(err, request, context) {
20
28
  const c = context || {};
21
29
  wt.captureException(err, {
@@ -0,0 +1,7 @@
1
+ /** Which of http/https are in `list` (default: this process's loaded builtins). */
2
+ export declare const lateModules: (list?: readonly string[]) => string[];
3
+ export declare const LATE_HINT = "Start node with --import @watchtowerobservability/node/register";
4
+ /** Prints once per process (global flag, so the CJS and ESM copies share it). */
5
+ export declare function warnLate(mods: string[], out?: (m: string) => void): void;
6
+ /** The entry points call this: silent under Next (it loads http before instrumentation runs) and in test runners. */
7
+ export declare function checkLate(): void;