@watchtowerobservability/node 0.0.0-stage → 0.3.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 (181) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +304 -2
  3. package/dist/cjs/appsec.d.ts +95 -0
  4. package/dist/cjs/appsec.js +206 -0
  5. package/dist/cjs/buffer.d.ts +49 -0
  6. package/dist/cjs/buffer.js +134 -0
  7. package/dist/cjs/errors.d.ts +17 -0
  8. package/dist/cjs/errors.js +55 -0
  9. package/dist/cjs/index.d.ts +123 -0
  10. package/dist/cjs/index.js +315 -0
  11. package/dist/cjs/integrations/amqp.d.ts +13 -0
  12. package/dist/cjs/integrations/amqp.js +96 -0
  13. package/dist/cjs/integrations/azure-functions.d.ts +18 -0
  14. package/dist/cjs/integrations/azure-functions.js +97 -0
  15. package/dist/cjs/integrations/bullmq.d.ts +19 -0
  16. package/dist/cjs/integrations/bullmq.js +83 -0
  17. package/dist/cjs/integrations/cache.d.ts +13 -0
  18. package/dist/cjs/integrations/cache.js +51 -0
  19. package/dist/cjs/integrations/db.d.ts +62 -0
  20. package/dist/cjs/integrations/db.js +288 -0
  21. package/dist/cjs/integrations/duckdb.d.ts +22 -0
  22. package/dist/cjs/integrations/duckdb.js +66 -0
  23. package/dist/cjs/integrations/express.d.ts +25 -0
  24. package/dist/cjs/integrations/express.js +58 -0
  25. package/dist/cjs/integrations/fastify.d.ts +6 -0
  26. package/dist/cjs/integrations/fastify.js +44 -0
  27. package/dist/cjs/integrations/genai-agents.d.ts +36 -0
  28. package/dist/cjs/integrations/genai-agents.js +124 -0
  29. package/dist/cjs/integrations/genai-stream.d.ts +19 -0
  30. package/dist/cjs/integrations/genai-stream.js +135 -0
  31. package/dist/cjs/integrations/genai.d.ts +18 -0
  32. package/dist/cjs/integrations/genai.js +150 -0
  33. package/dist/cjs/integrations/graphile-worker.d.ts +22 -0
  34. package/dist/cjs/integrations/graphile-worker.js +50 -0
  35. package/dist/cjs/integrations/koa.d.ts +19 -0
  36. package/dist/cjs/integrations/koa.js +34 -0
  37. package/dist/cjs/integrations/lambda.d.ts +11 -0
  38. package/dist/cjs/integrations/lambda.js +68 -0
  39. package/dist/cjs/integrations/level.d.ts +18 -0
  40. package/dist/cjs/integrations/level.js +71 -0
  41. package/dist/cjs/integrations/lmdb.d.ts +26 -0
  42. package/dist/cjs/integrations/lmdb.js +78 -0
  43. package/dist/cjs/integrations/logs.d.ts +10 -0
  44. package/dist/cjs/integrations/logs.js +77 -0
  45. package/dist/cjs/integrations/messaging.d.ts +17 -0
  46. package/dist/cjs/integrations/messaging.js +73 -0
  47. package/dist/cjs/integrations/mqtt.d.ts +7 -0
  48. package/dist/cjs/integrations/mqtt.js +41 -0
  49. package/dist/cjs/integrations/nats.d.ts +17 -0
  50. package/dist/cjs/integrations/nats.js +73 -0
  51. package/dist/cjs/integrations/nestjs.d.ts +16 -0
  52. package/dist/cjs/integrations/nestjs.js +30 -0
  53. package/dist/cjs/integrations/next.d.ts +11 -0
  54. package/dist/cjs/integrations/next.js +59 -0
  55. package/dist/cjs/integrations/orm.d.ts +47 -0
  56. package/dist/cjs/integrations/orm.js +93 -0
  57. package/dist/cjs/integrations/pg-boss.d.ts +8 -0
  58. package/dist/cjs/integrations/pg-boss.js +63 -0
  59. package/dist/cjs/integrations/pools.d.ts +41 -0
  60. package/dist/cjs/integrations/pools.js +94 -0
  61. package/dist/cjs/integrations/postgres.d.ts +12 -0
  62. package/dist/cjs/integrations/postgres.js +92 -0
  63. package/dist/cjs/integrations/prisma.d.ts +3 -0
  64. package/dist/cjs/integrations/prisma.js +33 -0
  65. package/dist/cjs/integrations/sqlite.d.ts +36 -0
  66. package/dist/cjs/integrations/sqlite.js +125 -0
  67. package/dist/cjs/integrations/util.d.ts +9 -0
  68. package/dist/cjs/integrations/util.js +37 -0
  69. package/dist/cjs/jest.d.ts +21 -0
  70. package/dist/cjs/jest.js +45 -0
  71. package/dist/cjs/load.d.ts +1 -0
  72. package/dist/cjs/load.js +11 -0
  73. package/dist/cjs/metrics.d.ts +10 -0
  74. package/dist/cjs/metrics.js +81 -0
  75. package/dist/cjs/package.json +1 -0
  76. package/dist/cjs/payload.d.ts +42 -0
  77. package/dist/cjs/payload.js +145 -0
  78. package/dist/cjs/pprof.d.ts +6 -0
  79. package/dist/cjs/pprof.js +88 -0
  80. package/dist/cjs/probes.d.ts +97 -0
  81. package/dist/cjs/probes.js +422 -0
  82. package/dist/cjs/profiling.d.ts +84 -0
  83. package/dist/cjs/profiling.js +263 -0
  84. package/dist/cjs/reporter-core.d.ts +32 -0
  85. package/dist/cjs/reporter-core.js +102 -0
  86. package/dist/cjs/sql.d.ts +19 -0
  87. package/dist/cjs/sql.js +332 -0
  88. package/dist/cjs/test-plan.d.ts +102 -0
  89. package/dist/cjs/test-plan.js +352 -0
  90. package/dist/cjs/vitest.d.ts +27 -0
  91. package/dist/cjs/vitest.js +52 -0
  92. package/dist/esm/appsec.d.ts +95 -0
  93. package/dist/esm/appsec.js +193 -0
  94. package/dist/esm/buffer.d.ts +49 -0
  95. package/dist/esm/buffer.js +92 -0
  96. package/dist/esm/errors.d.ts +17 -0
  97. package/dist/esm/errors.js +50 -0
  98. package/dist/esm/index.d.ts +123 -0
  99. package/dist/esm/index.js +264 -0
  100. package/dist/esm/integrations/amqp.d.ts +13 -0
  101. package/dist/esm/integrations/amqp.js +92 -0
  102. package/dist/esm/integrations/azure-functions.d.ts +18 -0
  103. package/dist/esm/integrations/azure-functions.js +60 -0
  104. package/dist/esm/integrations/bullmq.d.ts +19 -0
  105. package/dist/esm/integrations/bullmq.js +79 -0
  106. package/dist/esm/integrations/cache.d.ts +13 -0
  107. package/dist/esm/integrations/cache.js +46 -0
  108. package/dist/esm/integrations/db.d.ts +62 -0
  109. package/dist/esm/integrations/db.js +239 -0
  110. package/dist/esm/integrations/duckdb.d.ts +22 -0
  111. package/dist/esm/integrations/duckdb.js +29 -0
  112. package/dist/esm/integrations/express.d.ts +25 -0
  113. package/dist/esm/integrations/express.js +54 -0
  114. package/dist/esm/integrations/fastify.d.ts +6 -0
  115. package/dist/esm/integrations/fastify.js +41 -0
  116. package/dist/esm/integrations/genai-agents.d.ts +36 -0
  117. package/dist/esm/integrations/genai-agents.js +118 -0
  118. package/dist/esm/integrations/genai-stream.d.ts +19 -0
  119. package/dist/esm/integrations/genai-stream.js +130 -0
  120. package/dist/esm/integrations/genai.d.ts +18 -0
  121. package/dist/esm/integrations/genai.js +138 -0
  122. package/dist/esm/integrations/graphile-worker.d.ts +22 -0
  123. package/dist/esm/integrations/graphile-worker.js +46 -0
  124. package/dist/esm/integrations/koa.d.ts +19 -0
  125. package/dist/esm/integrations/koa.js +31 -0
  126. package/dist/esm/integrations/lambda.d.ts +11 -0
  127. package/dist/esm/integrations/lambda.js +32 -0
  128. package/dist/esm/integrations/level.d.ts +18 -0
  129. package/dist/esm/integrations/level.js +35 -0
  130. package/dist/esm/integrations/lmdb.d.ts +26 -0
  131. package/dist/esm/integrations/lmdb.js +42 -0
  132. package/dist/esm/integrations/logs.d.ts +10 -0
  133. package/dist/esm/integrations/logs.js +40 -0
  134. package/dist/esm/integrations/messaging.d.ts +17 -0
  135. package/dist/esm/integrations/messaging.js +64 -0
  136. package/dist/esm/integrations/mqtt.d.ts +7 -0
  137. package/dist/esm/integrations/mqtt.js +38 -0
  138. package/dist/esm/integrations/nats.d.ts +17 -0
  139. package/dist/esm/integrations/nats.js +70 -0
  140. package/dist/esm/integrations/nestjs.d.ts +16 -0
  141. package/dist/esm/integrations/nestjs.js +26 -0
  142. package/dist/esm/integrations/next.d.ts +11 -0
  143. package/dist/esm/integrations/next.js +22 -0
  144. package/dist/esm/integrations/orm.d.ts +47 -0
  145. package/dist/esm/integrations/orm.js +86 -0
  146. package/dist/esm/integrations/pg-boss.d.ts +8 -0
  147. package/dist/esm/integrations/pg-boss.js +60 -0
  148. package/dist/esm/integrations/pools.d.ts +41 -0
  149. package/dist/esm/integrations/pools.js +89 -0
  150. package/dist/esm/integrations/postgres.d.ts +12 -0
  151. package/dist/esm/integrations/postgres.js +55 -0
  152. package/dist/esm/integrations/prisma.d.ts +3 -0
  153. package/dist/esm/integrations/prisma.js +30 -0
  154. package/dist/esm/integrations/sqlite.d.ts +36 -0
  155. package/dist/esm/integrations/sqlite.js +84 -0
  156. package/dist/esm/integrations/util.d.ts +9 -0
  157. package/dist/esm/integrations/util.js +32 -0
  158. package/dist/esm/jest.d.ts +21 -0
  159. package/dist/esm/jest.js +41 -0
  160. package/dist/esm/load.d.ts +1 -0
  161. package/dist/esm/load.js +5 -0
  162. package/dist/esm/metrics.d.ts +10 -0
  163. package/dist/esm/metrics.js +44 -0
  164. package/dist/esm/package.json +1 -0
  165. package/dist/esm/payload.d.ts +42 -0
  166. package/dist/esm/payload.js +131 -0
  167. package/dist/esm/pprof.d.ts +6 -0
  168. package/dist/esm/pprof.js +85 -0
  169. package/dist/esm/probes.d.ts +97 -0
  170. package/dist/esm/probes.js +412 -0
  171. package/dist/esm/profiling.d.ts +84 -0
  172. package/dist/esm/profiling.js +251 -0
  173. package/dist/esm/reporter-core.d.ts +32 -0
  174. package/dist/esm/reporter-core.js +63 -0
  175. package/dist/esm/sql.d.ts +19 -0
  176. package/dist/esm/sql.js +324 -0
  177. package/dist/esm/test-plan.d.ts +102 -0
  178. package/dist/esm/test-plan.js +336 -0
  179. package/dist/esm/vitest.d.ts +27 -0
  180. package/dist/esm/vitest.js +48 -0
  181. package/package.json +379 -4
@@ -0,0 +1,251 @@
1
+ // Continuous CPU profiler on V8's own sampler (`node:inspector`, no native addon): every
2
+ // `periodMs` the CPU profile is folded into stacks, encoded as pprof and posted to the gateway's
3
+ // `/v1/profiles?format=pprof` with `service` and `version`. Best effort: a failed upload is
4
+ // counted and dropped. `withSpan` labels samples taken while its function runs, joined
5
+ // on V8's sample timestamps, so a trace links to its exact profile.
6
+ import { AsyncLocalStorage } from 'node:async_hooks';
7
+ import { Session } from 'node:inspector';
8
+ import { promiseHooks } from 'node:v8';
9
+ import { trace } from '@opentelemetry/api';
10
+ import { foldedToPprof } from './pprof.js';
11
+ const intervals = [];
12
+ const MAX_INTERVALS = 100_000;
13
+ function nowUs() {
14
+ return Number(process.hrtime.bigint() / 1000n);
15
+ }
16
+ /** The span of the running code, carried across `await` once async labels are on. */
17
+ const spanStore = new AsyncLocalStorage();
18
+ /** Promises created under a span, and that span. */
19
+ const tagged = new WeakMap();
20
+ /** The interval each `before` opened, for its `after`; `null` for an unlabeled continuation. */
21
+ const running = [];
22
+ let asyncSpans = false;
23
+ function open(prefix) {
24
+ if (intervals.length >= MAX_INTERVALS)
25
+ return null;
26
+ const iv = { start: nowUs(), end: Number.MAX_SAFE_INTEGER, prefix };
27
+ intervals.push(iv);
28
+ return iv;
29
+ }
30
+ /**
31
+ * Opt-in (overhead unmeasured): `withSpan` also labels its async function's code after each
32
+ * `await`. The span rides in an AsyncLocalStorage; a promise created under it is tagged, and each
33
+ * run of its continuation (V8 promise hooks `before` to `after`) is one more interval. Plain
34
+ * callbacks it starts (timers, events) are labeled only from their own `await`s on.
35
+ */
36
+ export function enableAsyncSpanLabels() {
37
+ if (asyncSpans)
38
+ return;
39
+ asyncSpans = true;
40
+ promiseHooks.createHook({
41
+ init(promise) {
42
+ const p = spanStore.getStore(); // init runs synchronously, in the creating code's context
43
+ if (p)
44
+ tagged.set(promise, p);
45
+ },
46
+ before(promise) {
47
+ if (running.length >= 1_000)
48
+ running.length = 0; // afters lost to an uncaught exception
49
+ const p = tagged.get(promise);
50
+ running.push(p ? open(p) : null);
51
+ },
52
+ after() {
53
+ const iv = running.pop();
54
+ if (iv)
55
+ iv.end = nowUs();
56
+ },
57
+ });
58
+ }
59
+ /**
60
+ * Labels samples taken while `fn` runs with a span (default: the active OpenTelemetry span). Only
61
+ * `fn`'s synchronous part, unless [[enableAsyncSpanLabels]] (or the profiler's `asyncSpans`) is on.
62
+ */
63
+ export function withSpan(fn, ids) {
64
+ const sc = ids ?? trace.getActiveSpan()?.spanContext();
65
+ if (!sc || intervals.length >= MAX_INTERVALS)
66
+ return fn();
67
+ const prefix = `span_id=${sc.spanId},trace_id=${sc.traceId}\t`;
68
+ const iv = open(prefix);
69
+ try {
70
+ return asyncSpans ? spanStore.run(prefix, fn) : fn();
71
+ }
72
+ finally {
73
+ iv.end = nowUs();
74
+ }
75
+ }
76
+ /** Takes the intervals a profile up to `until` can need; open ones stay for the next profile. */
77
+ export function takeIntervals(until) {
78
+ const out = intervals.slice();
79
+ const keep = out.filter((iv) => iv.end > until);
80
+ intervals.length = 0;
81
+ intervals.push(...keep);
82
+ return out;
83
+ }
84
+ /** The innermost span at `t`; `sorted` is by start. */
85
+ function prefixAt(sorted, t) {
86
+ let lo = 0;
87
+ let hi = sorted.length;
88
+ while (lo < hi) {
89
+ const mid = (lo + hi) >> 1;
90
+ if (sorted[mid].start <= t)
91
+ lo = mid + 1;
92
+ else
93
+ hi = mid;
94
+ }
95
+ for (let i = lo - 1; i >= 0 && i >= lo - 16; i--)
96
+ if (sorted[i].end >= t)
97
+ return sorted[i].prefix;
98
+ return '';
99
+ }
100
+ const MAX_DEPTH = 128;
101
+ function frameName(f) {
102
+ const file = f.url ? f.url.split('/').pop() : '';
103
+ const name = f.functionName || '(anonymous)';
104
+ return (file ? `${name} (${file}:${f.lineNumber + 1})` : name).replace(/;/g, ':');
105
+ }
106
+ /** Root-first folded stacks with their sample counts; V8's synthetic `(root)` is left out. */
107
+ export function foldProfile(p, spans = []) {
108
+ const parent = new Map();
109
+ const byId = new Map();
110
+ for (const n of p.nodes) {
111
+ byId.set(n.id, n);
112
+ for (const c of n.children ?? [])
113
+ parent.set(c, n.id);
114
+ }
115
+ const counts = new Map();
116
+ const sorted = [...spans].sort((a, b) => a.start - b.start);
117
+ let t = p.startTime ?? 0;
118
+ for (const [i, id] of (p.samples ?? []).entries()) {
119
+ t += p.timeDeltas?.[i] ?? 0;
120
+ const names = [];
121
+ for (let cur = id; cur !== undefined && names.length < MAX_DEPTH; cur = parent.get(cur)) {
122
+ const n = byId.get(cur);
123
+ if (!n || n.callFrame.functionName === '(root)')
124
+ break;
125
+ if (n.callFrame.functionName === '(idle)' || n.callFrame.functionName === '(program)') {
126
+ names.length = 0;
127
+ break;
128
+ }
129
+ names.push(frameName(n.callFrame));
130
+ }
131
+ if (names.length === 0)
132
+ continue;
133
+ const key = prefixAt(sorted, t) + names.reverse().join(';');
134
+ counts.set(key, (counts.get(key) ?? 0) + 1);
135
+ }
136
+ return counts;
137
+ }
138
+ export function foldedBody(counts) {
139
+ let out = '';
140
+ for (const [k, n] of counts)
141
+ out += `${k} ${n}\n`;
142
+ return out;
143
+ }
144
+ /** `/v1/profiles?format=pprof&service=…&version=…` on the gateway. */
145
+ export function profilesUrl(endpoint, service, version) {
146
+ const q = new URLSearchParams({ format: 'pprof', service });
147
+ if (version)
148
+ q.set('version', version);
149
+ return `${endpoint.replace(/\/+$/, '')}/v1/profiles?${q}`;
150
+ }
151
+ /** Pyroscope-compatible `/ingest` URL for folded uploads (kept for callers; the Profiler sends pprof). */
152
+ export function ingestUrl(endpoint, service, tags, fromS, untilS, hz) {
153
+ const labels = Object.entries(tags).filter(([, v]) => v).sort(([a], [b]) => a.localeCompare(b))
154
+ .map(([k, v]) => `${k}=${v}`).join(',');
155
+ const q = new URLSearchParams({
156
+ name: `${service}.cpu{${labels}}`, from: String(Math.floor(fromS)), until: String(Math.floor(untilS)),
157
+ format: 'folded', sampleRate: String(hz), spyName: 'watchtower-node', units: 'samples',
158
+ });
159
+ return `${endpoint.replace(/\/+$/, '')}/ingest?${q}`;
160
+ }
161
+ export class Profiler {
162
+ uploaded = 0;
163
+ dropped = 0;
164
+ key;
165
+ endpoint;
166
+ service;
167
+ tags;
168
+ intervalUs;
169
+ periodMs;
170
+ session;
171
+ timer;
172
+ from = 0;
173
+ constructor(o = {}) {
174
+ const key = o.apiKey ?? process.env.WT_INGEST_KEY;
175
+ if (!key)
176
+ throw new Error('apiKey is required');
177
+ this.key = key;
178
+ this.endpoint = o.endpoint ?? process.env.WT_OTLP_ENDPOINT ?? 'http://localhost:4318';
179
+ this.service = o.service ?? process.env.WT_SERVICE ?? 'app';
180
+ this.tags = { env: process.env.WT_ENVIRONMENT, version: process.env.WT_RELEASE, ...o.tags };
181
+ this.intervalUs = Math.min(Math.max(o.intervalUs ?? 10_000, 1_000), 1_000_000);
182
+ this.periodMs = Math.max(o.periodMs ?? 60_000, 1_000);
183
+ if (o.asyncSpans)
184
+ enableAsyncSpanLabels();
185
+ }
186
+ /** Not printable with the key. */
187
+ [Symbol.for('nodejs.util.inspect.custom')]() {
188
+ return `Profiler { service: '${this.service}' }`;
189
+ }
190
+ post(method, params) {
191
+ return new Promise((resolve, reject) => {
192
+ this.session.post(method, params ?? {}, (err, res) => (err ? reject(err) : resolve(res)));
193
+ });
194
+ }
195
+ async start() {
196
+ if (this.session)
197
+ return this;
198
+ this.session = new Session();
199
+ this.session.connect();
200
+ await this.post('Profiler.enable');
201
+ await this.post('Profiler.setSamplingInterval', { interval: this.intervalUs });
202
+ await this.post('Profiler.start');
203
+ this.from = Date.now() / 1000;
204
+ this.timer = setInterval(() => void this.flush(true), this.periodMs);
205
+ this.timer.unref();
206
+ return this;
207
+ }
208
+ /** Stop the current profile, upload it and (when `restart`) start the next one. */
209
+ async flush(restart) {
210
+ if (!this.session)
211
+ return;
212
+ const until = Date.now() / 1000;
213
+ const { profile } = await this.post('Profiler.stop');
214
+ const from = this.from;
215
+ if (restart) {
216
+ await this.post('Profiler.start');
217
+ this.from = until;
218
+ }
219
+ const counts = foldProfile(profile, takeIntervals(nowUs()));
220
+ if (counts.size)
221
+ await this.upload(counts, from, until);
222
+ }
223
+ async upload(counts, fromS, untilS) {
224
+ try {
225
+ const body = foldedToPprof(counts, this.intervalUs * 1000, fromS * 1000, (untilS - fromS) * 1000);
226
+ const r = await fetch(profilesUrl(this.endpoint, this.service, this.tags.version), {
227
+ method: 'POST', body,
228
+ headers: { authorization: `Bearer ${this.key}`, 'content-type': 'application/octet-stream' },
229
+ signal: AbortSignal.timeout(10_000),
230
+ });
231
+ if (r.ok)
232
+ this.uploaded++;
233
+ else
234
+ this.dropped++;
235
+ }
236
+ catch {
237
+ this.dropped++;
238
+ }
239
+ }
240
+ async stop() {
241
+ if (this.timer)
242
+ clearInterval(this.timer);
243
+ await this.flush(false).catch(() => undefined);
244
+ this.session?.disconnect();
245
+ this.session = undefined;
246
+ }
247
+ }
248
+ /** Start a [[Profiler]] with the SDK's environment defaults. */
249
+ export function startProfiling(o = {}) {
250
+ return new Profiler(o).start();
251
+ }
@@ -0,0 +1,32 @@
1
+ import type { Client, InitOptions } from './index.js';
2
+ export interface ReporterOptions {
3
+ client?: Client;
4
+ apiKey?: string;
5
+ serviceName?: string;
6
+ /** Extra options passed to `init` when the reporter creates its own client. */
7
+ init?: InitOptions;
8
+ }
9
+ export type TestOutcome = 'passed' | 'failed' | 'skipped';
10
+ export interface TestRecord {
11
+ name: string;
12
+ outcome: TestOutcome;
13
+ durationMs?: number;
14
+ message?: string;
15
+ endMs?: number;
16
+ /** `suite::file > describe > test` (see test-plan.ts) */
17
+ id?: string;
18
+ /** ticket of a quarantined test; its failure did not fail the run */
19
+ quarantined?: string;
20
+ /** a test the project had never seen (early flake detection) */
21
+ isNew?: boolean;
22
+ /** failed attempts before the final result (retries) */
23
+ attempts?: number;
24
+ }
25
+ /** Client from `opts.client`, else `WT_INGEST_KEY` (+ `WT_PROJECT_ID`); `null` when neither is set. */
26
+ export declare function clientFor(opts?: ReporterOptions): Client | null;
27
+ /**
28
+ * tests: [{ name, outcome: 'passed'|'failed'|'skipped', durationMs, message?, endMs? }]
29
+ * Spans are created after the fact, so start/end times are set explicitly.
30
+ */
31
+ export declare function reportTests(client: Client | null, tests: TestRecord[], framework?: string): Promise<number>;
32
+ export declare const outcome: (s?: string) => TestOutcome;
@@ -0,0 +1,63 @@
1
+ // Shared by the Jest and Vitest reporters: every finished test becomes a span named
2
+ // `test <full name>` with `test.outcome` / `test.duration_ms`, and, with a project, a
3
+ // `test_pass` score (1 passed, 0 failed; skipped tests get no score). Telemetry failures never
4
+ // fail the test run.
5
+ import { SpanStatusCode } from '@opentelemetry/api';
6
+ import * as wt from './index.js';
7
+ /** Client from `opts.client`, else `WT_INGEST_KEY` (+ `WT_PROJECT_ID`); `null` when neither is set. */
8
+ export function clientFor(opts) {
9
+ const o = opts || {};
10
+ if (o.client)
11
+ return o.client;
12
+ const apiKey = o.apiKey || process.env.WT_INGEST_KEY;
13
+ if (!apiKey)
14
+ return null;
15
+ return wt.init({ apiKey, serviceName: o.serviceName || 'tests', ...o.init });
16
+ }
17
+ /**
18
+ * tests: [{ name, outcome: 'passed'|'failed'|'skipped', durationMs, message?, endMs? }]
19
+ * Spans are created after the fact, so start/end times are set explicitly.
20
+ */
21
+ export async function reportTests(client, tests, framework = 'test') {
22
+ if (!client)
23
+ return 0;
24
+ let n = 0;
25
+ for (const t of tests) {
26
+ try {
27
+ const end = t.endMs || Date.now();
28
+ const span = client.tracer.startSpan(`test ${t.name}`, { startTime: end - (t.durationMs || 0) });
29
+ span.setAttribute('test.outcome', t.outcome);
30
+ span.setAttribute('test.duration_ms', t.durationMs || 0);
31
+ // OTel test semconv plus the attributes the pytest plugin sets
32
+ const id = t.id || t.name;
33
+ span.setAttribute('test.framework', framework);
34
+ span.setAttribute('test.suite.name', id.includes('::') ? id.slice(0, id.indexOf('::')) : framework);
35
+ span.setAttribute('test.case.name', id);
36
+ span.setAttribute('test.case.result.status', t.outcome === 'passed' ? 'pass' : t.outcome === 'failed' ? 'fail' : 'skip');
37
+ if (t.quarantined)
38
+ span.setAttribute('test.quarantined', true);
39
+ if (t.isNew) {
40
+ span.setAttribute('test.is_new', true);
41
+ span.setAttribute('test.efd.retries', t.attempts || 0);
42
+ span.setAttribute('test.is_flaky', (t.attempts || 0) > 0 && t.outcome === 'passed');
43
+ }
44
+ if (t.outcome === 'failed') {
45
+ span.setStatus({ code: SpanStatusCode.ERROR, message: String(t.message || 'failed').slice(0, 500) });
46
+ }
47
+ const traceId = span.spanContext().traceId;
48
+ span.end(end);
49
+ n += 1;
50
+ if (client.project && t.outcome !== 'skipped') {
51
+ await client.score(traceId, t.outcome === 'passed' ? 1 : 0, { name: 'test_pass', comment: t.name });
52
+ }
53
+ }
54
+ catch (_e) { /* telemetry down must not fail tests */ }
55
+ }
56
+ try {
57
+ await client.provider.forceFlush();
58
+ }
59
+ catch (_e) { /* same */ }
60
+ return n;
61
+ }
62
+ const OUTCOME = { passed: 'passed', pass: 'passed', failed: 'failed', fail: 'failed' };
63
+ export const outcome = (s) => OUTCOME[s] || 'skipped';
@@ -0,0 +1,19 @@
1
+ /** Longest statement looked at, in UTF-8 bytes; the rest is dropped. */
2
+ export declare const MAX_STATEMENT_BYTES: number;
3
+ /**
4
+ * Literal-free statement text: strings, numbers and `$1` become `?`, comments go, whitespace
5
+ * collapses, `IN (?, ?)` becomes `IN (?+)`. `pg` keeps short `"identifiers"` and the `#` operator.
6
+ */
7
+ export declare function normalizeSql(stmt: string, pg?: boolean): string;
8
+ /** `[normalized text, decimal xxh3_64 of its UTF-8 bytes]`: the `db.query.hash` spans carry. */
9
+ export declare function normalizeAndHash(stmt: string, pg?: boolean): [string, string];
10
+ /** Systems whose dialect keeps `"identifier"` quotes and the `#` operator (as the worker decides). */
11
+ export declare const isPgDialect: (system: string | undefined) => system is "postgresql" | "cockroachdb" | "redshift";
12
+ /** `SELECT users`-style summary: the operation and first table, never values or the statement text. */
13
+ export declare function querySummary(text: string | null | undefined, fallback?: string): {
14
+ operation?: string;
15
+ target?: string;
16
+ summary: string;
17
+ };
18
+ /** XXH3_64bits(input), seed 0. */
19
+ export declare function xxh3(p: Uint8Array): bigint;
@@ -0,0 +1,324 @@
1
+ // Shared SQL normaliser and statement hash. A byte-for-byte port of the worker's
2
+ // services/worker/src/sqlnorm.rs (`normalize_with`, xxh3_64), so `db.query.hash` from the SDK equals
3
+ // the `wt.db.query_hash` the server stamps. Algorithm: docs/product/instrumentation/sql-normalization.md;
4
+ // vectors: testdata/sql_normalize_vectors.json. Change both sides together.
5
+ /** Longest statement looked at, in UTF-8 bytes; the rest is dropped. */
6
+ export const MAX_STATEMENT_BYTES = 8 * 1024;
7
+ const MAX_DOLLAR_TAG = 32;
8
+ const ALNUM = /^[\p{Alphabetic}\p{N}]$/u; // Rust char::is_alphanumeric
9
+ const SPACE = /^\p{White_Space}$/u; // Rust char::is_whitespace
10
+ const isAlnum = (c) => ALNUM.test(c);
11
+ const isWord = (c) => c === '_' || c === '$' || ALNUM.test(c);
12
+ const isDigit = (c) => c !== undefined && c >= '0' && c <= '9';
13
+ /** Code points of the first 8 KiB of UTF-8, cut back to a whole character. */
14
+ function cap(s) {
15
+ const out = [];
16
+ let bytes = 0;
17
+ for (const c of s) {
18
+ const cp = c.codePointAt(0);
19
+ bytes += cp < 0x80 ? 1 : cp < 0x800 ? 2 : cp < 0x10000 ? 3 : 4;
20
+ if (bytes > MAX_STATEMENT_BYTES)
21
+ break;
22
+ out.push(c);
23
+ }
24
+ return out;
25
+ }
26
+ const startsWith = (cs, at, tag) => tag.every((t, k) => cs[at + k] === t);
27
+ function dollarQuoted(cs, i) {
28
+ let tagLen = -1;
29
+ for (let k = 0; k < MAX_DOLLAR_TAG + 1 && i + 1 + k < cs.length; k++) {
30
+ if (cs[i + 1 + k] === '$') {
31
+ tagLen = k;
32
+ break;
33
+ }
34
+ }
35
+ if (tagLen < 0)
36
+ return undefined;
37
+ const tag = cs.slice(i, i + tagLen + 2);
38
+ if (!tag.slice(1, tagLen + 1).every((c) => isAlnum(c) || c === '_') || isDigit(tag[1]))
39
+ return undefined;
40
+ for (let j = i + tag.length; j < cs.length; j++)
41
+ if (startsWith(cs, j, tag))
42
+ return j + tag.length;
43
+ return cs.length;
44
+ }
45
+ function token(cs, i, pg, out) {
46
+ const c = cs[i];
47
+ if (c === "'") {
48
+ i++;
49
+ while (i < cs.length) {
50
+ if (cs[i] === "'") {
51
+ if (cs[i + 1] !== "'")
52
+ break;
53
+ i++;
54
+ }
55
+ i++;
56
+ }
57
+ out.push('?');
58
+ // a quote right after a backslash is ambiguous (MySQL escapes): mask to the end
59
+ return i < cs.length && cs[i - 1] === '\\' ? cs.length : i + 1;
60
+ }
61
+ if (c === '"' || c === '`') {
62
+ let close = cs.indexOf(c, i + 1);
63
+ if (close < 0)
64
+ close = cs.length;
65
+ const body = cs.slice(i + 1, close);
66
+ const ident = c === '"' && pg && close < cs.length && body.length >= 1 && body.length <= 64
67
+ && body.every((b) => isAlnum(b) || b === '_' || b === '$');
68
+ if (ident)
69
+ out.push(...cs.slice(i, close + 1));
70
+ else
71
+ out.push('?');
72
+ return close + 1;
73
+ }
74
+ if (c === '$') {
75
+ if (isDigit(cs[i + 1])) {
76
+ i++;
77
+ while (isDigit(cs[i]))
78
+ i++;
79
+ out.push('?');
80
+ return i;
81
+ }
82
+ const end = dollarQuoted(cs, i);
83
+ if (end !== undefined) {
84
+ out.push('?');
85
+ return end;
86
+ }
87
+ }
88
+ if (isDigit(c)) {
89
+ while (i < cs.length && (isWord(cs[i]) || cs[i] === '.'))
90
+ i++;
91
+ out.push('?');
92
+ }
93
+ else if (isWord(c)) {
94
+ while (i < cs.length && isWord(cs[i]))
95
+ out.push(cs[i++]);
96
+ }
97
+ else {
98
+ out.push(c);
99
+ i++;
100
+ }
101
+ return i;
102
+ }
103
+ const enc = new TextEncoder();
104
+ const dec = new TextDecoder();
105
+ const SP = 0x20;
106
+ /** After `in`: optional spaces, `(`, `?` items split by commas, `)`. Returns [open, end]. */
107
+ function inList(b, i) {
108
+ const skip = () => { while (b[i] === SP)
109
+ i++; };
110
+ skip();
111
+ const open = i;
112
+ if (b[i] !== 0x28)
113
+ return undefined;
114
+ i++;
115
+ for (;;) {
116
+ skip();
117
+ if (b[i] !== 0x3f)
118
+ return undefined;
119
+ i++;
120
+ skip();
121
+ if (b[i] === 0x2c)
122
+ i++;
123
+ else if (b[i] === 0x29)
124
+ return [open, i + 1];
125
+ else
126
+ return undefined;
127
+ }
128
+ }
129
+ /** `in (?, ?, ?)` -> `in (?+)`. On UTF-8 bytes like the Rust: the word check reads the previous byte as Latin-1. */
130
+ function collapseIn(s) {
131
+ const out = [];
132
+ let i = 0;
133
+ while (i < s.length) {
134
+ const atWord = i === 0 || !isWord(String.fromCharCode(s[i - 1]));
135
+ const span = atWord && i + 2 <= s.length && (s[i] | 0x20) === 0x69 && (s[i + 1] | 0x20) === 0x6e
136
+ ? inList(s, i + 2) : undefined;
137
+ if (span) {
138
+ for (let k = i; k < span[0]; k++)
139
+ out.push(s[k]);
140
+ out.push(0x28, 0x3f, 0x2b, 0x29);
141
+ i = span[1];
142
+ }
143
+ else {
144
+ out.push(s[i++]);
145
+ }
146
+ }
147
+ return Uint8Array.from(out);
148
+ }
149
+ function normalizeBytes(stmt, pg) {
150
+ const cs = cap(stmt);
151
+ const out = [];
152
+ let space = false;
153
+ let i = 0;
154
+ while (i < cs.length) {
155
+ const c = cs[i];
156
+ const next = cs[i + 1];
157
+ if (SPACE.test(c)) {
158
+ space = true;
159
+ i++;
160
+ }
161
+ else if (c === '/' && next === '*') {
162
+ let depth = 1;
163
+ i += 2;
164
+ while (i < cs.length && depth > 0) {
165
+ if (cs[i] === '/' && cs[i + 1] === '*') {
166
+ depth++;
167
+ i += 2;
168
+ }
169
+ else if (cs[i] === '*' && cs[i + 1] === '/') {
170
+ depth--;
171
+ i += 2;
172
+ }
173
+ else
174
+ i++;
175
+ }
176
+ space = true;
177
+ }
178
+ else if ((c === '-' && next === '-') || (c === '#' && !pg)) {
179
+ while (i < cs.length && cs[i] !== '\n')
180
+ i++;
181
+ space = true;
182
+ }
183
+ else {
184
+ if (space && out.length)
185
+ out.push(' ');
186
+ space = false;
187
+ i = token(cs, i, pg, out);
188
+ }
189
+ }
190
+ return collapseIn(enc.encode(out.join('')));
191
+ }
192
+ /**
193
+ * Literal-free statement text: strings, numbers and `$1` become `?`, comments go, whitespace
194
+ * collapses, `IN (?, ?)` becomes `IN (?+)`. `pg` keeps short `"identifiers"` and the `#` operator.
195
+ */
196
+ export function normalizeSql(stmt, pg = false) {
197
+ return dec.decode(normalizeBytes(stmt, pg));
198
+ }
199
+ /** `[normalized text, decimal xxh3_64 of its UTF-8 bytes]`: the `db.query.hash` spans carry. */
200
+ export function normalizeAndHash(stmt, pg = false) {
201
+ const b = normalizeBytes(stmt, pg);
202
+ return [dec.decode(b), xxh3(b).toString()];
203
+ }
204
+ /** Systems whose dialect keeps `"identifier"` quotes and the `#` operator (as the worker decides). */
205
+ export const isPgDialect = (system) => system === 'postgresql' || system === 'cockroachdb' || system === 'redshift';
206
+ const OP = /^\s*(?:with\b[\s\S]*?\)\s*)?([a-z]+)/i;
207
+ const TARGET = /\b(?:from|into|update|join|table)\s+((?:"[^"]+"|[\w$]+)(?:\.(?:"[^"]+"|[\w$]+))?)/i;
208
+ /** `SELECT users`-style summary: the operation and first table, never values or the statement text. */
209
+ export function querySummary(text, fallback = 'postgres') {
210
+ const operation = text?.match(OP)?.[1]?.toUpperCase();
211
+ const target = text?.match(TARGET)?.[1]?.replace(/"/g, '');
212
+ return { operation, target, summary: [operation ?? fallback, target].filter(Boolean).join(' ') };
213
+ }
214
+ // ---- XXH3-64, seed 0, default secret (port of the xxHash reference; BigInt is fine at <= 8 KiB) ----
215
+ const M64 = (1n << 64n) - 1n;
216
+ const P32_1 = 0x9e3779b1n, P32_2 = 0x85ebca77n, P32_3 = 0xc2b2ae3dn;
217
+ const P64_1 = 0x9e3779b185ebca87n, P64_2 = 0xc2b2ae3d27d4eb4fn, P64_3 = 0x165667b19e3779f9n;
218
+ const P64_4 = 0x85ebca77c2b2ae63n, P64_5 = 0x27d4eb2f165667c5n;
219
+ const SECRET = Uint8Array.from(Buffer.from('b8fe6c3923a44bbe7c01812cf721ad1cded46de9839097db7240a4a4b7b3671fcb79e64eccc0e578825ad07dccff7221'
220
+ + 'b8084674f743248ee03590e6813a264c3c2852bb91c300cb88d0658b1b532ea371644897a20df94e3819ef46a9deacd8'
221
+ + 'a8fa763fe39c343ff9dcbbc7c70b4f1d8a51e04bcdb45931c89f7ec9d9787364eac5ac8334d3ebc3c581a0fffa1363eb'
222
+ + '170ddd51b7f0da49d316552629d4689e2b16be587d47a1fc8ff8b8d17ad031ce45cb3a8f95160428afd7fbcabb4b407e', 'hex'));
223
+ const r64 = (b, o) => new DataView(b.buffer, b.byteOffset + o, 8).getBigUint64(0, true);
224
+ const r32 = (b, o) => BigInt(new DataView(b.buffer, b.byteOffset + o, 4).getUint32(0, true));
225
+ const mul = (a, b) => (a * b) & M64;
226
+ const add = (a, b) => (a + b) & M64;
227
+ const rotl = (x, r) => ((x << r) | (x >> (64n - r))) & M64;
228
+ const swap64 = (x) => {
229
+ let r = 0n;
230
+ for (let k = 0; k < 8; k++) {
231
+ r = (r << 8n) | (x & 0xffn);
232
+ x >>= 8n;
233
+ }
234
+ return r;
235
+ };
236
+ const fold = (a, b) => { const p = a * b; return (p ^ (p >> 64n)) & M64; };
237
+ const avalanche = (h) => { h ^= h >> 37n; h = mul(h, 0x165667919e3779f9n); return h ^ (h >> 32n); };
238
+ const avalanche64 = (h) => {
239
+ h ^= h >> 33n;
240
+ h = mul(h, P64_2);
241
+ h ^= h >> 29n;
242
+ h = mul(h, P64_3);
243
+ return h ^ (h >> 32n);
244
+ };
245
+ const mix16 = (p, o, s) => fold(r64(p, o) ^ r64(SECRET, s), r64(p, o + 8) ^ r64(SECRET, s + 8));
246
+ function accumulate512(acc, p, o, s) {
247
+ for (let i = 0; i < 8; i++) {
248
+ const v = r64(p, o + 8 * i);
249
+ const k = v ^ r64(SECRET, s + 8 * i);
250
+ acc[i ^ 1] = add(acc[i ^ 1], v);
251
+ acc[i] = add(acc[i], (k & 0xffffffffn) * (k >> 32n));
252
+ }
253
+ }
254
+ function long(p) {
255
+ const len = p.length;
256
+ const acc = [P32_3, P64_1, P64_2, P64_3, P64_4, P32_2, P64_5, P32_1];
257
+ const stripesPerBlock = (SECRET.length - 64) / 8;
258
+ const block = 64 * stripesPerBlock;
259
+ const blocks = Math.floor((len - 1) / block);
260
+ for (let n = 0; n < blocks; n++) {
261
+ for (let s = 0; s < stripesPerBlock; s++)
262
+ accumulate512(acc, p, n * block + s * 64, s * 8);
263
+ for (let i = 0; i < 8; i++) {
264
+ let a = acc[i];
265
+ a ^= a >> 47n;
266
+ a ^= r64(SECRET, SECRET.length - 64 + 8 * i);
267
+ acc[i] = mul(a, P32_1);
268
+ }
269
+ }
270
+ const stripes = Math.floor((len - 1 - block * blocks) / 64);
271
+ for (let s = 0; s < stripes; s++)
272
+ accumulate512(acc, p, blocks * block + s * 64, s * 8);
273
+ accumulate512(acc, p, len - 64, SECRET.length - 64 - 7);
274
+ let r = mul(BigInt(len), P64_1);
275
+ for (let i = 0; i < 4; i++)
276
+ r = add(r, fold(acc[2 * i] ^ r64(SECRET, 11 + 16 * i), acc[2 * i + 1] ^ r64(SECRET, 19 + 16 * i)));
277
+ return avalanche(r);
278
+ }
279
+ /** XXH3_64bits(input), seed 0. */
280
+ export function xxh3(p) {
281
+ const len = p.length;
282
+ const L = BigInt(len);
283
+ if (len === 0)
284
+ return avalanche64(r64(SECRET, 56) ^ r64(SECRET, 64));
285
+ if (len <= 3) {
286
+ const combined = (BigInt(p[0]) << 16n) | (BigInt(p[len >> 1]) << 24n) | BigInt(p[len - 1]) | (L << 8n);
287
+ return avalanche64(combined ^ (r32(SECRET, 0) ^ r32(SECRET, 4)));
288
+ }
289
+ if (len <= 8) {
290
+ const keyed = (r32(p, len - 4) + (r32(p, 0) << 32n)) ^ (r64(SECRET, 8) ^ r64(SECRET, 16));
291
+ let h = keyed ^ rotl(keyed, 49n) ^ rotl(keyed, 24n);
292
+ h = mul(h, 0x9fb21c651e98df25n);
293
+ h ^= add(h >> 35n, L);
294
+ h = mul(h, 0x9fb21c651e98df25n);
295
+ return h ^ (h >> 28n);
296
+ }
297
+ if (len <= 16) {
298
+ const lo = r64(p, 0) ^ (r64(SECRET, 24) ^ r64(SECRET, 32));
299
+ const hi = r64(p, len - 8) ^ (r64(SECRET, 40) ^ r64(SECRET, 48));
300
+ return avalanche(add(add(add(L, swap64(lo)), hi), fold(lo, hi)));
301
+ }
302
+ if (len <= 128) {
303
+ let acc = mul(L, P64_1);
304
+ if (len > 32) {
305
+ if (len > 64) {
306
+ if (len > 96)
307
+ acc = add(add(acc, mix16(p, 48, 96)), mix16(p, len - 64, 112));
308
+ acc = add(add(acc, mix16(p, 32, 64)), mix16(p, len - 48, 80));
309
+ }
310
+ acc = add(add(acc, mix16(p, 16, 32)), mix16(p, len - 32, 48));
311
+ }
312
+ return avalanche(add(add(acc, mix16(p, 0, 0)), mix16(p, len - 16, 16)));
313
+ }
314
+ if (len <= 240) {
315
+ let acc = mul(L, P64_1);
316
+ for (let i = 0; i < 8; i++)
317
+ acc = add(acc, mix16(p, 16 * i, 16 * i));
318
+ acc = avalanche(acc);
319
+ for (let i = 8; i < Math.floor(len / 16); i++)
320
+ acc = add(acc, mix16(p, 16 * i, 16 * (i - 8) + 3));
321
+ return avalanche(add(acc, mix16(p, len - 16, 136 - 17)));
322
+ }
323
+ return long(p);
324
+ }