@watchtowerobservability/node 0.2.0 → 0.4.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 (94) hide show
  1. package/README.md +186 -3
  2. package/dist/cjs/appsec.d.ts +95 -0
  3. package/dist/cjs/appsec.js +206 -0
  4. package/dist/cjs/iast.d.ts +27 -0
  5. package/dist/cjs/iast.js +138 -0
  6. package/dist/cjs/index.d.ts +3 -0
  7. package/dist/cjs/index.js +14 -1
  8. package/dist/cjs/integrations/amqp.d.ts +13 -0
  9. package/dist/cjs/integrations/amqp.js +96 -0
  10. package/dist/cjs/integrations/bullmq.d.ts +19 -0
  11. package/dist/cjs/integrations/bullmq.js +83 -0
  12. package/dist/cjs/integrations/cache.d.ts +13 -0
  13. package/dist/cjs/integrations/cache.js +51 -0
  14. package/dist/cjs/integrations/db.d.ts +62 -0
  15. package/dist/cjs/integrations/db.js +288 -0
  16. package/dist/cjs/integrations/duckdb.d.ts +22 -0
  17. package/dist/cjs/integrations/duckdb.js +66 -0
  18. package/dist/cjs/integrations/graphile-worker.d.ts +22 -0
  19. package/dist/cjs/integrations/graphile-worker.js +50 -0
  20. package/dist/cjs/integrations/level.d.ts +18 -0
  21. package/dist/cjs/integrations/level.js +71 -0
  22. package/dist/cjs/integrations/lmdb.d.ts +26 -0
  23. package/dist/cjs/integrations/lmdb.js +78 -0
  24. package/dist/cjs/integrations/messaging.d.ts +17 -0
  25. package/dist/cjs/integrations/messaging.js +73 -0
  26. package/dist/cjs/integrations/mqtt.d.ts +7 -0
  27. package/dist/cjs/integrations/mqtt.js +41 -0
  28. package/dist/cjs/integrations/nats.d.ts +17 -0
  29. package/dist/cjs/integrations/nats.js +73 -0
  30. package/dist/cjs/integrations/orm.d.ts +47 -0
  31. package/dist/cjs/integrations/orm.js +93 -0
  32. package/dist/cjs/integrations/pg-boss.d.ts +8 -0
  33. package/dist/cjs/integrations/pg-boss.js +63 -0
  34. package/dist/cjs/integrations/pools.d.ts +41 -0
  35. package/dist/cjs/integrations/pools.js +94 -0
  36. package/dist/cjs/integrations/postgres.d.ts +12 -0
  37. package/dist/cjs/integrations/postgres.js +92 -0
  38. package/dist/cjs/integrations/sqlite.d.ts +36 -0
  39. package/dist/cjs/integrations/sqlite.js +125 -0
  40. package/dist/cjs/pprof.d.ts +6 -0
  41. package/dist/cjs/pprof.js +88 -0
  42. package/dist/cjs/profiling.d.ts +4 -1
  43. package/dist/cjs/profiling.js +18 -8
  44. package/dist/cjs/sql.d.ts +19 -0
  45. package/dist/cjs/sql.js +332 -0
  46. package/dist/cjs/test-plan.d.ts +10 -1
  47. package/dist/cjs/test-plan.js +91 -1
  48. package/dist/esm/appsec.d.ts +95 -0
  49. package/dist/esm/appsec.js +193 -0
  50. package/dist/esm/iast.d.ts +27 -0
  51. package/dist/esm/iast.js +130 -0
  52. package/dist/esm/index.d.ts +3 -0
  53. package/dist/esm/index.js +14 -1
  54. package/dist/esm/integrations/amqp.d.ts +13 -0
  55. package/dist/esm/integrations/amqp.js +92 -0
  56. package/dist/esm/integrations/bullmq.d.ts +19 -0
  57. package/dist/esm/integrations/bullmq.js +79 -0
  58. package/dist/esm/integrations/cache.d.ts +13 -0
  59. package/dist/esm/integrations/cache.js +46 -0
  60. package/dist/esm/integrations/db.d.ts +62 -0
  61. package/dist/esm/integrations/db.js +239 -0
  62. package/dist/esm/integrations/duckdb.d.ts +22 -0
  63. package/dist/esm/integrations/duckdb.js +29 -0
  64. package/dist/esm/integrations/graphile-worker.d.ts +22 -0
  65. package/dist/esm/integrations/graphile-worker.js +46 -0
  66. package/dist/esm/integrations/level.d.ts +18 -0
  67. package/dist/esm/integrations/level.js +35 -0
  68. package/dist/esm/integrations/lmdb.d.ts +26 -0
  69. package/dist/esm/integrations/lmdb.js +42 -0
  70. package/dist/esm/integrations/messaging.d.ts +17 -0
  71. package/dist/esm/integrations/messaging.js +64 -0
  72. package/dist/esm/integrations/mqtt.d.ts +7 -0
  73. package/dist/esm/integrations/mqtt.js +38 -0
  74. package/dist/esm/integrations/nats.d.ts +17 -0
  75. package/dist/esm/integrations/nats.js +70 -0
  76. package/dist/esm/integrations/orm.d.ts +47 -0
  77. package/dist/esm/integrations/orm.js +86 -0
  78. package/dist/esm/integrations/pg-boss.d.ts +8 -0
  79. package/dist/esm/integrations/pg-boss.js +60 -0
  80. package/dist/esm/integrations/pools.d.ts +41 -0
  81. package/dist/esm/integrations/pools.js +89 -0
  82. package/dist/esm/integrations/postgres.d.ts +12 -0
  83. package/dist/esm/integrations/postgres.js +55 -0
  84. package/dist/esm/integrations/sqlite.d.ts +36 -0
  85. package/dist/esm/integrations/sqlite.js +84 -0
  86. package/dist/esm/pprof.d.ts +6 -0
  87. package/dist/esm/pprof.js +85 -0
  88. package/dist/esm/profiling.d.ts +4 -1
  89. package/dist/esm/profiling.js +17 -8
  90. package/dist/esm/sql.d.ts +19 -0
  91. package/dist/esm/sql.js +324 -0
  92. package/dist/esm/test-plan.d.ts +10 -1
  93. package/dist/esm/test-plan.js +89 -1
  94. package/package.json +171 -1
@@ -0,0 +1,288 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.enter = exports.inside = void 0;
37
+ exports.startDbSpan = startDbSpan;
38
+ exports.recordDbSpan = recordDbSpan;
39
+ exports.fail = fail;
40
+ exports.settle = settle;
41
+ exports.traced = traced;
42
+ exports.tracedCb = tracedCb;
43
+ exports.patch = patch;
44
+ exports.observePool = observePool;
45
+ exports.observeEmbedded = observeEmbedded;
46
+ exports.cacheCounters = cacheCounters;
47
+ exports.sizeOf = sizeOf;
48
+ // Shared core for the datastore and queue integrations: CLIENT spans with OTel db semconv, the
49
+ // statement hash and N+1 hint, connection-pool metrics and embedded-store gauges.
50
+ const fs = __importStar(require("node:fs"));
51
+ const nodePath = __importStar(require("node:path"));
52
+ const api_1 = require("@opentelemetry/api");
53
+ const sql_js_1 = require("../sql.js");
54
+ /** Set inside an instrumented call so a wrapper the library calls internally adds no second span. */
55
+ const INSIDE = (0, api_1.createContextKey)('watchtower.db.inside');
56
+ const inside = (ctx = api_1.context.active()) => ctx.getValue(INSIDE) === true;
57
+ exports.inside = inside;
58
+ /** `parent` with `span` active; `nested` marks it as inside an instrumented call (no inner spans). */
59
+ const enter = (parent, span, nested = true) => nested ? api_1.trace.setSpan(parent, span).setValue(INSIDE, true) : api_1.trace.setSpan(parent, span).deleteValue(INSIDE);
60
+ exports.enter = enter;
61
+ const on = (v) => ['1', 'true', 'on', 'yes'].includes((v || '').trim().toLowerCase());
62
+ const threshold = (o) => o?.nPlusOne ?? (Number(process.env.WATCHTOWER_DB_N_PLUS_ONE) || 5);
63
+ // parent span id -> statement key -> count.
64
+ // shortcut: keeps the 1000 most recently seen parents; raise it if very wide fan-out traces miss hints.
65
+ const seen = new Map();
66
+ function repeats(parent, key) {
67
+ let m = seen.get(parent);
68
+ if (!m) {
69
+ if (seen.size >= 1000)
70
+ seen.delete(seen.keys().next().value);
71
+ seen.set(parent, (m = new Map()));
72
+ }
73
+ const n = (m.get(key) ?? 0) + 1;
74
+ m.set(key, n);
75
+ return n;
76
+ }
77
+ /** A CLIENT span for `op` (not made active): summary, hash, N+1 hint. Prefer `traced`. */
78
+ function startDbSpan(op, opts, parent, startTime) {
79
+ const attrs = { 'db.system.name': op.system, ...op.attributes };
80
+ let { operation, collection } = op;
81
+ let name = [operation, collection].filter(Boolean).join(' ') || op.system;
82
+ let key = name;
83
+ if (op.sql) {
84
+ const [norm, hash] = (0, sql_js_1.normalizeAndHash)(op.sql, (0, sql_js_1.isPgDialect)(op.system));
85
+ const s = (0, sql_js_1.querySummary)(norm, op.system);
86
+ operation ??= s.operation;
87
+ collection ??= s.target;
88
+ name = s.summary;
89
+ key = hash;
90
+ attrs['db.query.summary'] = s.summary;
91
+ attrs['db.query.hash'] = hash;
92
+ if (opts?.queryText ?? on(process.env.WATCHTOWER_DB_QUERY_TEXT))
93
+ attrs['db.query.text'] = norm;
94
+ }
95
+ if (operation)
96
+ attrs['db.operation.name'] = operation;
97
+ if (collection)
98
+ attrs['db.collection.name'] = collection;
99
+ if (op.namespace)
100
+ attrs['db.namespace'] = op.namespace;
101
+ const p = api_1.trace.getSpan(parent)?.spanContext();
102
+ const max = threshold(opts);
103
+ if (p && max > 0) {
104
+ const n = repeats(p.spanId, key);
105
+ if (n > max) {
106
+ attrs['db.query.repeat_count'] = n;
107
+ attrs['db.n_plus_one'] = true;
108
+ }
109
+ }
110
+ return api_1.trace.getTracer('watchtower').startSpan(name, { kind: api_1.SpanKind.CLIENT, attributes: attrs, startTime }, parent);
111
+ }
112
+ /** A finished CLIENT span for a query a library reports after the fact (ORM loggers): it ends now. */
113
+ function recordDbSpan(op, opts, durationMs, error) {
114
+ const end = Date.now();
115
+ const span = startDbSpan(op, opts, api_1.context.active(), end - Math.max(0, durationMs || 0));
116
+ if (error)
117
+ fail(span, error);
118
+ span.end(end);
119
+ }
120
+ /** Error status with the driver's code; the message is not recorded (it can quote values). */
121
+ function fail(span, e) {
122
+ const code = e?.code;
123
+ if (typeof code === 'string' || typeof code === 'number') {
124
+ span.setAttribute('db.response.status_code', String(code));
125
+ span.setAttribute('error.type', String(code));
126
+ }
127
+ else {
128
+ span.setAttribute('error.type', e?.name || 'Error');
129
+ }
130
+ span.setStatus({ code: api_1.SpanStatusCode.ERROR });
131
+ }
132
+ const isThenable = (v) => !!v && (typeof v === 'object' || typeof v === 'function') && typeof v.then === 'function';
133
+ /** Run `fn` and end `span` when it returns, throws or its promise settles. The result is returned as is. */
134
+ function settle(span, fn) {
135
+ let r;
136
+ try {
137
+ r = fn();
138
+ }
139
+ catch (e) {
140
+ fail(span, e);
141
+ span.end();
142
+ throw e;
143
+ }
144
+ if (isThenable(r)) {
145
+ r.then(() => span.end(), (e) => { fail(span, e); span.end(); });
146
+ }
147
+ else {
148
+ span.end();
149
+ }
150
+ return r;
151
+ }
152
+ /** A CLIENT span around `fn` (sync or promise), child of the active span. `nested: false` lets
153
+ * calls made inside `fn` (a transaction callback) get their own spans. */
154
+ function traced(op, opts, fn, nested = true) {
155
+ const parent = api_1.context.active();
156
+ if ((0, exports.inside)(parent))
157
+ return fn();
158
+ const span = startDbSpan(op, opts, parent);
159
+ return settle(span, () => api_1.context.with((0, exports.enter)(parent, span, nested), fn));
160
+ }
161
+ /** `traced` for node-style callback APIs: the last function argument ends the span and runs in the caller's context. */
162
+ function tracedCb(op, opts, args, call) {
163
+ const last = args.length - 1;
164
+ const cb = args[last];
165
+ const parent = api_1.context.active();
166
+ if (typeof cb !== 'function')
167
+ return traced(op, opts, () => call(args));
168
+ if ((0, exports.inside)(parent))
169
+ return call(args);
170
+ const span = startDbSpan(op, opts, parent);
171
+ const copy = args.slice();
172
+ copy[last] = api_1.context.bind(parent, function (err, ...rest) {
173
+ if (err)
174
+ fail(span, err);
175
+ span.end();
176
+ return cb.apply(this, [err, ...rest]);
177
+ });
178
+ try {
179
+ return api_1.context.with((0, exports.enter)(parent, span), () => call(copy));
180
+ }
181
+ catch (e) {
182
+ fail(span, e);
183
+ span.end();
184
+ throw e;
185
+ }
186
+ }
187
+ /** Wrap `obj[name]` once; `wrap` gets the original. Missing methods are skipped. */
188
+ function patch(obj, name, wrap) {
189
+ const o = obj;
190
+ const orig = o[name];
191
+ if (typeof orig !== 'function' || orig[WRAPPED])
192
+ return;
193
+ const w = wrap(orig);
194
+ w[WRAPPED] = true;
195
+ o[name] = w;
196
+ }
197
+ const WRAPPED = Symbol.for('watchtower.wrapped');
198
+ // ---- metrics (instruments come from the global meter: call the observe* helpers after init) ----
199
+ const meter = () => api_1.metrics.getMeter('watchtower');
200
+ let cached;
201
+ function inst() {
202
+ const m = meter();
203
+ if (cached?.m !== m) {
204
+ cached = {
205
+ m,
206
+ wait: m.createHistogram('db.client.connection.wait_time', { unit: 's' }),
207
+ use: m.createHistogram('db.client.connection.use_time', { unit: 's' }),
208
+ timeouts: m.createCounter('db.client.connection.timeouts'),
209
+ hits: m.createCounter('wt.embedded.cache.hits'),
210
+ misses: m.createCounter('wt.embedded.cache.misses'),
211
+ };
212
+ }
213
+ return cached;
214
+ }
215
+ /**
216
+ * Pool gauges per OTel db semconv, read at each export: `db.client.connection.count{state}`,
217
+ * `.max`, `.pending_requests`, with `db.client.connection.pool.name` and `db.system.name`.
218
+ * Returns the recorders for wait/use time and timeouts, and `stop()`.
219
+ */
220
+ function observePool(system, pool, read) {
221
+ const attrs = { 'db.system.name': system, 'db.client.connection.pool.name': pool };
222
+ const m = meter();
223
+ const count = m.createObservableGauge('db.client.connection.count');
224
+ const max = m.createObservableGauge('db.client.connection.max');
225
+ const pending = m.createObservableGauge('db.client.connection.pending_requests');
226
+ const cb = (r) => {
227
+ const s = read();
228
+ if (s.used !== undefined)
229
+ r.observe(count, s.used, { ...attrs, 'db.client.connection.state': 'used' });
230
+ if (s.idle !== undefined)
231
+ r.observe(count, s.idle, { ...attrs, 'db.client.connection.state': 'idle' });
232
+ if (s.max !== undefined)
233
+ r.observe(max, s.max, attrs);
234
+ if (s.pending !== undefined)
235
+ r.observe(pending, s.pending, attrs);
236
+ };
237
+ m.addBatchObservableCallback(cb, [count, max, pending]);
238
+ return {
239
+ wait: (seconds) => inst().wait.record(seconds, attrs),
240
+ use: (seconds) => inst().use.record(seconds, attrs),
241
+ timeout: () => inst().timeouts.add(1, attrs),
242
+ stop: () => m.removeBatchObservableCallback(cb, [count, max, pending]),
243
+ };
244
+ }
245
+ /** `wt.embedded.<key>` gauges for an embedded store, read at each export. Returns `stop()`. */
246
+ function observeEmbedded(system, namespace, keys, read) {
247
+ const attrs = { 'db.system.name': system, ...(namespace ? { 'db.namespace': namespace } : {}) };
248
+ const m = meter();
249
+ const gauges = keys.map((k) => [k, m.createObservableGauge(`wt.embedded.${k}`)]);
250
+ const cb = (r) => {
251
+ let v;
252
+ try {
253
+ v = read();
254
+ }
255
+ catch {
256
+ return;
257
+ }
258
+ for (const [k, g] of gauges)
259
+ if (typeof v[k] === 'number')
260
+ r.observe(g, v[k], attrs);
261
+ };
262
+ m.addBatchObservableCallback(cb, gauges.map(([, g]) => g));
263
+ return () => m.removeBatchObservableCallback(cb, gauges.map(([, g]) => g));
264
+ }
265
+ /** Hit/miss counters (`wt.embedded.cache.hits` / `.misses`) for an in-memory cache. */
266
+ function cacheCounters(system, name) {
267
+ const attrs = { 'db.system.name': system, 'db.namespace': name };
268
+ return { hit: (n = 1) => inst().hits.add(n, attrs), miss: (n = 1) => inst().misses.add(n, attrs) };
269
+ }
270
+ /** Size in bytes of a file, or of the files directly in a directory; 0 when missing. */
271
+ function sizeOf(path) {
272
+ try {
273
+ const st = fs.statSync(path);
274
+ if (!st.isDirectory())
275
+ return st.size;
276
+ return fs.readdirSync(path).reduce((n, f) => {
277
+ try {
278
+ return n + fs.statSync(nodePath.join(path, f)).size;
279
+ }
280
+ catch {
281
+ return n;
282
+ }
283
+ }, 0);
284
+ }
285
+ catch {
286
+ return 0;
287
+ }
288
+ }
@@ -0,0 +1,22 @@
1
+ import type { DbOptions } from './db.js';
2
+ type Proto = Record<string, any>;
3
+ /**
4
+ * `import * as duckdb from '@duckdb/node-api'` (or the classic `duckdb` package);
5
+ * `instrumentDuckDB(duckdb)`: a span per statement run on a `DuckDBConnection` (or a classic
6
+ * `Database`/`Connection`), `db.system.name=duckdb`. Returns false when neither API is found.
7
+ * shortcut: prepared statements (`connection.prepare`) are not traced.
8
+ */
9
+ export declare function instrumentDuckDB(duckdb: {
10
+ DuckDBConnection?: {
11
+ prototype: Proto;
12
+ };
13
+ Database?: {
14
+ prototype: Proto;
15
+ };
16
+ Connection?: {
17
+ prototype: Proto;
18
+ };
19
+ }, opts?: DbOptions): boolean;
20
+ /** `wt.embedded.file.size` and `wt.embedded.wal.size` (the `.wal` file) of a DuckDB database file. Returns `stop()`. */
21
+ export declare function observeDuckDBFile(path: string): () => void;
22
+ export {};
@@ -0,0 +1,66 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.instrumentDuckDB = instrumentDuckDB;
37
+ exports.observeDuckDBFile = observeDuckDBFile;
38
+ const nodePath = __importStar(require("node:path"));
39
+ const db_js_1 = require("./db.js");
40
+ const sqlite_js_1 = require("./sqlite.js");
41
+ const NEO = ['run', 'runAndRead', 'runAndReadAll', 'runAndReadUntil', 'stream', 'streamAndRead', 'streamAndReadAll',
42
+ 'streamAndReadUntil'];
43
+ /**
44
+ * `import * as duckdb from '@duckdb/node-api'` (or the classic `duckdb` package);
45
+ * `instrumentDuckDB(duckdb)`: a span per statement run on a `DuckDBConnection` (or a classic
46
+ * `Database`/`Connection`), `db.system.name=duckdb`. Returns false when neither API is found.
47
+ * shortcut: prepared statements (`connection.prepare`) are not traced.
48
+ */
49
+ function instrumentDuckDB(duckdb, opts) {
50
+ const neo = duckdb.DuckDBConnection?.prototype;
51
+ if (neo) {
52
+ for (const m of NEO) {
53
+ (0, db_js_1.patch)(neo, m, (orig) => function (sql, ...a) {
54
+ return (0, db_js_1.traced)({ system: 'duckdb', sql: typeof sql === 'string' ? sql : undefined }, opts, () => orig.call(this, sql, ...a));
55
+ });
56
+ }
57
+ return true;
58
+ }
59
+ const protos = [duckdb.Database?.prototype, duckdb.Connection?.prototype].filter((p) => !!p);
60
+ (0, sqlite_js_1.patchCallbackDb)(protos, 'duckdb', opts);
61
+ return protos.length > 0;
62
+ }
63
+ /** `wt.embedded.file.size` and `wt.embedded.wal.size` (the `.wal` file) of a DuckDB database file. Returns `stop()`. */
64
+ function observeDuckDBFile(path) {
65
+ return (0, db_js_1.observeEmbedded)('duckdb', nodePath.basename(path), ['file.size', 'wal.size'], () => ({ 'file.size': (0, db_js_1.sizeOf)(path), 'wal.size': (0, db_js_1.sizeOf)(`${path}.wal`) }));
66
+ }
@@ -0,0 +1,22 @@
1
+ interface Helpers {
2
+ job?: {
3
+ id?: string | number;
4
+ attempts?: number;
5
+ queue_name?: string | null;
6
+ };
7
+ addJob?: unknown;
8
+ }
9
+ type Task = (payload: unknown, helpers: Helpers) => unknown;
10
+ /**
11
+ * `instrumentAddJob(utils)` (from `makeWorkerUtils`, or the runner from `run`): a PRODUCER span on
12
+ * `addJob` with the trace context in the payload under `_wt` (object payloads only).
13
+ * shortcut: the module-level `quickAddJob` cannot be patched under ESM; use `utils.addJob`.
14
+ */
15
+ export declare function instrumentAddJob(utilsOrRunner: object): void;
16
+ /**
17
+ * `run({ taskList: wrapTaskList({ send_email: async (payload, helpers) => ... }) })`: each task runs
18
+ * in a CONSUMER span, child of and linked to the `addJob` that queued it; `_wt` is removed from the
19
+ * payload first, and `helpers.addJob` is instrumented so follow-up jobs stay in the trace.
20
+ */
21
+ export declare function wrapTaskList<T extends Record<string, Task>>(tasks: T): T;
22
+ export {};
@@ -0,0 +1,50 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.instrumentAddJob = instrumentAddJob;
4
+ exports.wrapTaskList = wrapTaskList;
5
+ const api_1 = require("@opentelemetry/api");
6
+ const db_js_1 = require("./db.js");
7
+ const messaging_js_1 = require("./messaging.js");
8
+ const attrs = (task, type, op) => ({
9
+ 'messaging.system': 'graphile-worker',
10
+ 'messaging.destination.name': task,
11
+ 'messaging.operation.type': type,
12
+ 'messaging.operation.name': op,
13
+ });
14
+ /**
15
+ * `instrumentAddJob(utils)` (from `makeWorkerUtils`, or the runner from `run`): a PRODUCER span on
16
+ * `addJob` with the trace context in the payload under `_wt` (object payloads only).
17
+ * shortcut: the module-level `quickAddJob` cannot be patched under ESM; use `utils.addJob`.
18
+ */
19
+ function instrumentAddJob(utilsOrRunner) {
20
+ (0, db_js_1.patch)(utilsOrRunner, 'addJob', (orig) => function (identifier, payload, ...rest) {
21
+ return (0, messaging_js_1.produce)(`send ${identifier}`, attrs(identifier, 'send', 'addJob'), () => {
22
+ const span = api_1.trace.getActiveSpan();
23
+ return orig.call(this, identifier, (0, messaging_js_1.injectData)(payload ?? {}), ...rest).then((job) => {
24
+ if (job?.id !== undefined)
25
+ span?.setAttribute('messaging.message.id', String(job.id));
26
+ return job;
27
+ });
28
+ });
29
+ });
30
+ }
31
+ /**
32
+ * `run({ taskList: wrapTaskList({ send_email: async (payload, helpers) => ... }) })`: each task runs
33
+ * in a CONSUMER span, child of and linked to the `addJob` that queued it; `_wt` is removed from the
34
+ * payload first, and `helpers.addJob` is instrumented so follow-up jobs stay in the trace.
35
+ */
36
+ function wrapTaskList(tasks) {
37
+ return Object.fromEntries(Object.entries(tasks).map(([name, fn]) => [name, (payload, helpers) => {
38
+ const carrier = (0, messaging_js_1.takeContext)(payload);
39
+ const a = attrs(name, 'process', 'task');
40
+ if (helpers?.job?.id !== undefined)
41
+ a['messaging.message.id'] = String(helpers.job.id);
42
+ if (helpers?.job?.attempts !== undefined)
43
+ a['messaging.graphile_worker.job.attempt'] = helpers.job.attempts;
44
+ if (helpers?.job?.queue_name)
45
+ a['messaging.consumer.group.name'] = helpers.job.queue_name;
46
+ if (helpers)
47
+ instrumentAddJob(helpers);
48
+ return (0, messaging_js_1.consume)(`process ${name}`, a, [carrier], () => fn(payload, helpers));
49
+ }]));
50
+ }
@@ -0,0 +1,18 @@
1
+ import type { DbOptions } from './db.js';
2
+ interface LevelDb {
3
+ location?: string;
4
+ sublevel?(...a: unknown[]): object;
5
+ }
6
+ /**
7
+ * `instrumentLevel(new ClassicLevel(dir))`, or `instrumentLevel(rocksdb(dir), { system: 'rocksdb' })`:
8
+ * a span per `get`/`getMany`/`put`/`del`/`batch`/`clear` (promise or callback form; keys and values
9
+ * are never recorded), on the db and on its sublevels (`db.collection.name`). With `metrics` (default
10
+ * on) and a `location`, `wt.embedded.file.size` reports the size of the store's directory.
11
+ * Returns `stop()` for the gauge.
12
+ * shortcut: iterators and the chained `batch()` builder are not traced.
13
+ */
14
+ export declare function instrumentLevel(db: LevelDb, opts?: DbOptions & {
15
+ system?: 'leveldb' | 'rocksdb';
16
+ metrics?: boolean;
17
+ }): () => void;
18
+ export {};
@@ -0,0 +1,71 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.instrumentLevel = instrumentLevel;
37
+ const nodePath = __importStar(require("node:path"));
38
+ const db_js_1 = require("./db.js");
39
+ const OPS = ['get', 'getMany', 'put', 'del', 'batch', 'clear'];
40
+ /**
41
+ * `instrumentLevel(new ClassicLevel(dir))`, or `instrumentLevel(rocksdb(dir), { system: 'rocksdb' })`:
42
+ * a span per `get`/`getMany`/`put`/`del`/`batch`/`clear` (promise or callback form; keys and values
43
+ * are never recorded), on the db and on its sublevels (`db.collection.name`). With `metrics` (default
44
+ * on) and a `location`, `wt.embedded.file.size` reports the size of the store's directory.
45
+ * Returns `stop()` for the gauge.
46
+ * shortcut: iterators and the chained `batch()` builder are not traced.
47
+ */
48
+ function instrumentLevel(db, opts) {
49
+ const system = opts?.system ?? 'leveldb';
50
+ const namespace = db.location ? nodePath.basename(db.location) : undefined;
51
+ const wrap = (d, collection) => {
52
+ for (const m of OPS) {
53
+ (0, db_js_1.patch)(d, m, (orig) => function (...a) {
54
+ if (m === 'batch' && a.length === 0)
55
+ return orig.call(this); // chained builder
56
+ return (0, db_js_1.tracedCb)({ system, operation: m, collection, namespace }, opts, a, (args) => orig.apply(this, args));
57
+ });
58
+ }
59
+ (0, db_js_1.patch)(d, 'sublevel', (orig) => function (...a) {
60
+ const sub = orig.apply(this, a);
61
+ if (sub)
62
+ wrap(sub, typeof a[0] === 'string' ? a[0] : undefined);
63
+ return sub;
64
+ });
65
+ };
66
+ wrap(db);
67
+ const dir = db.location;
68
+ if (opts?.metrics === false || !dir)
69
+ return () => { };
70
+ return (0, db_js_1.observeEmbedded)(system, namespace, ['file.size'], () => ({ 'file.size': (0, db_js_1.sizeOf)(dir) }));
71
+ }
@@ -0,0 +1,26 @@
1
+ import type { DbOptions } from './db.js';
2
+ interface LmdbStats {
3
+ pageSize?: number;
4
+ mapSize?: number;
5
+ lastPageNumber?: number;
6
+ entryCount?: number;
7
+ numReaders?: number;
8
+ }
9
+ interface LmdbDb {
10
+ path?: string;
11
+ name?: string;
12
+ getStats?(): LmdbStats;
13
+ openDB?(...a: unknown[]): object;
14
+ }
15
+ /**
16
+ * `instrumentLmdb(open({ path }))` (lmdb-js): spans for async writes (`put`, `remove`, `ifVersion`,
17
+ * `ifNoExists`, `clearAsync`, `drop`), `getMany` and `transaction` (calls inside a transaction get
18
+ * child spans), on the root and on every `openDB` sub-database (`db.collection.name`). Sync reads
19
+ * (`get`) are memory-mapped and take microseconds, so they get no span. With `metrics` (default on)
20
+ * it also reports `wt.embedded.map.size`, `.map.used`, `.entries`, `.readers` and `.file.size`.
21
+ * Returns `stop()` for the gauges.
22
+ */
23
+ export declare function instrumentLmdb(db: LmdbDb, opts?: DbOptions & {
24
+ metrics?: boolean;
25
+ }): () => void;
26
+ export {};
@@ -0,0 +1,78 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.instrumentLmdb = instrumentLmdb;
37
+ const nodePath = __importStar(require("node:path"));
38
+ const db_js_1 = require("./db.js");
39
+ const WRITES = ['put', 'remove', 'ifVersion', 'ifNoExists', 'clearAsync', 'drop', 'getMany', 'prefetch'];
40
+ /**
41
+ * `instrumentLmdb(open({ path }))` (lmdb-js): spans for async writes (`put`, `remove`, `ifVersion`,
42
+ * `ifNoExists`, `clearAsync`, `drop`), `getMany` and `transaction` (calls inside a transaction get
43
+ * child spans), on the root and on every `openDB` sub-database (`db.collection.name`). Sync reads
44
+ * (`get`) are memory-mapped and take microseconds, so they get no span. With `metrics` (default on)
45
+ * it also reports `wt.embedded.map.size`, `.map.used`, `.entries`, `.readers` and `.file.size`.
46
+ * Returns `stop()` for the gauges.
47
+ */
48
+ function instrumentLmdb(db, opts) {
49
+ const namespace = db.path ? nodePath.basename(db.path) : undefined;
50
+ const wrap = (d, collection) => {
51
+ for (const m of WRITES) {
52
+ (0, db_js_1.patch)(d, m, (orig) => function (...a) {
53
+ return (0, db_js_1.traced)({ system: 'lmdb', operation: m, collection, namespace }, opts, () => orig.apply(this, a));
54
+ });
55
+ }
56
+ (0, db_js_1.patch)(d, 'transaction', (orig) => function (...a) {
57
+ return (0, db_js_1.traced)({ system: 'lmdb', operation: 'transaction', collection, namespace }, opts, () => orig.apply(this, a), false);
58
+ });
59
+ (0, db_js_1.patch)(d, 'openDB', (orig) => function (...a) {
60
+ const sub = orig.apply(this, a);
61
+ const name = typeof a[0] === 'string' ? a[0] : a[0]?.name;
62
+ if (sub)
63
+ wrap(sub, name ?? sub.name);
64
+ return sub;
65
+ });
66
+ };
67
+ wrap(db);
68
+ if (opts?.metrics === false || typeof db.getStats !== 'function')
69
+ return () => { };
70
+ return (0, db_js_1.observeEmbedded)('lmdb', namespace, ['map.size', 'map.used', 'entries', 'readers', 'file.size'], () => {
71
+ const s = db.getStats();
72
+ const used = s.pageSize !== undefined && s.lastPageNumber !== undefined ? (s.lastPageNumber + 1) * s.pageSize : undefined;
73
+ return {
74
+ 'map.size': s.mapSize, 'map.used': used, entries: s.entryCount, readers: s.numReaders,
75
+ 'file.size': db.path ? (0, db_js_1.sizeOf)(db.path) : undefined,
76
+ };
77
+ });
78
+ }
@@ -0,0 +1,17 @@
1
+ import type { Attributes } from '@opentelemetry/api';
2
+ /** Key in job data that carries the producer's trace context (W3C `traceparent`/`tracestate`). */
3
+ export declare const CONTEXT_KEY = "_wt";
4
+ export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
5
+ /** The active context as W3C headers. */
6
+ export declare function headers(): Record<string, string>;
7
+ /** Copy of `data` carrying the active context under `_wt`; non-object data is returned unchanged. */
8
+ export declare function injectData(data: unknown): unknown;
9
+ /** Remove and return the `_wt` carrier from object job data. */
10
+ export declare function takeContext(data: unknown): Record<string, unknown> | undefined;
11
+ /** A PRODUCER span around `fn`, which gets the headers to send (the producer span's context). */
12
+ export declare function produce<T>(name: string, attributes: Attributes, fn: (h: Record<string, string>) => T): T;
13
+ /**
14
+ * A CONSUMER span around `fn`, linked to the producer context of each carrier (header maps whose
15
+ * values may be strings or Buffers). With exactly one carrier the producer span is also the parent.
16
+ */
17
+ export declare function consume<T>(name: string, attributes: Attributes, carriers: Array<Record<string, unknown> | undefined>, fn: () => T): T;