@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,46 @@
1
+ import { cacheCounters, observeEmbedded, patch } from './db.js';
2
+ /** Count hits and misses of `get`-like methods: `undefined` is a miss; arrays and objects count per key. */
3
+ function count(c, keys, v) {
4
+ if (Array.isArray(keys)) {
5
+ const found = Array.isArray(v) ? v.filter((x) => x !== undefined).length
6
+ : v && typeof v === 'object' ? Object.keys(v).length : 0;
7
+ c.hit(found);
8
+ c.miss(keys.length - found);
9
+ }
10
+ else if (v === undefined) {
11
+ c.miss();
12
+ }
13
+ else {
14
+ c.hit();
15
+ }
16
+ }
17
+ function wrapGets(cache, system, name, methods) {
18
+ const c = cacheCounters(system, name);
19
+ for (const m of methods) {
20
+ patch(cache, m, (orig) => function (key, ...a) {
21
+ const v = orig.call(this, key, ...a);
22
+ if (v && typeof v.then === 'function') {
23
+ v.then((x) => count(c, key, x), () => { });
24
+ }
25
+ else {
26
+ count(c, key, v);
27
+ }
28
+ return v;
29
+ });
30
+ }
31
+ }
32
+ /** Hit/miss counters and entry count for a node-cache instance (`get`, `mget`). Returns `stop()`. */
33
+ export function instrumentNodeCache(cache, name = 'default') {
34
+ wrapGets(cache, 'node-cache', name, ['get', 'mget']);
35
+ return observeEmbedded('node-cache', name, ['cache.entries'], () => ({ 'cache.entries': cache.getStats?.().keys }));
36
+ }
37
+ /** Hit/miss counters and entry count for an lru-cache instance (`get`). Returns `stop()`.
38
+ * shortcut: `fetch()` (the async loader) is not counted. */
39
+ export function instrumentLruCache(cache, name = 'default') {
40
+ wrapGets(cache, 'lru-cache', name, ['get']);
41
+ return observeEmbedded('lru-cache', name, ['cache.entries'], () => ({ 'cache.entries': cache.size }));
42
+ }
43
+ /** Hit/miss counters for a Keyv instance (`get` with one key or an array; also `getMany`). */
44
+ export function instrumentKeyv(keyv, name = 'default') {
45
+ wrapGets(keyv, 'keyv', name, ['get', 'getMany']);
46
+ }
@@ -0,0 +1,62 @@
1
+ import type { Attributes, Context, Span, TimeInput } from '@opentelemetry/api';
2
+ export interface DbOptions {
3
+ /** Add the literal-free statement as `db.query.text`. Default: `WATCHTOWER_DB_QUERY_TEXT=1`. */
4
+ queryText?: boolean;
5
+ /** Flag a statement run more than this many times under one parent span. Default:
6
+ * `WATCHTOWER_DB_N_PLUS_ONE` or 5; 0 turns it off. */
7
+ nPlusOne?: number;
8
+ }
9
+ export interface DbOp {
10
+ /** `db.system.name`, e.g. `sqlite`. */
11
+ system: string;
12
+ operation?: string;
13
+ collection?: string;
14
+ namespace?: string;
15
+ /** Statement text: summarised and hashed, never recorded raw. */
16
+ sql?: string | null;
17
+ attributes?: Attributes;
18
+ }
19
+ export declare const inside: (ctx?: Context) => boolean;
20
+ /** `parent` with `span` active; `nested` marks it as inside an instrumented call (no inner spans). */
21
+ export declare const enter: (parent: Context, span: Span, nested?: boolean) => Context;
22
+ /** A CLIENT span for `op` (not made active): summary, hash, N+1 hint. Prefer `traced`. */
23
+ export declare function startDbSpan(op: DbOp, opts: DbOptions | undefined, parent: Context, startTime?: TimeInput): Span;
24
+ /** A finished CLIENT span for a query a library reports after the fact (ORM loggers): it ends now. */
25
+ export declare function recordDbSpan(op: DbOp, opts: DbOptions | undefined, durationMs: number, error?: unknown): void;
26
+ /** Error status with the driver's code; the message is not recorded (it can quote values). */
27
+ export declare function fail(span: Span, e: unknown): void;
28
+ /** Run `fn` and end `span` when it returns, throws or its promise settles. The result is returned as is. */
29
+ export declare function settle<T>(span: Span, fn: () => T): T;
30
+ /** A CLIENT span around `fn` (sync or promise), child of the active span. `nested: false` lets
31
+ * calls made inside `fn` (a transaction callback) get their own spans. */
32
+ export declare function traced<T>(op: DbOp, opts: DbOptions | undefined, fn: () => T, nested?: boolean): T;
33
+ /** `traced` for node-style callback APIs: the last function argument ends the span and runs in the caller's context. */
34
+ export declare function tracedCb<T>(op: DbOp, opts: DbOptions | undefined, args: unknown[], call: (args: unknown[]) => T): T;
35
+ /** Wrap `obj[name]` once; `wrap` gets the original. Missing methods are skipped. */
36
+ export declare function patch<T extends object>(obj: T, name: string, wrap: (orig: (...a: any[]) => any) => (...a: any[]) => any): void;
37
+ export interface PoolState {
38
+ used?: number;
39
+ idle?: number;
40
+ pending?: number;
41
+ max?: number;
42
+ }
43
+ /**
44
+ * Pool gauges per OTel db semconv, read at each export: `db.client.connection.count{state}`,
45
+ * `.max`, `.pending_requests`, with `db.client.connection.pool.name` and `db.system.name`.
46
+ * Returns the recorders for wait/use time and timeouts, and `stop()`.
47
+ */
48
+ export declare function observePool(system: string, pool: string, read: () => PoolState): {
49
+ wait: (seconds: number) => void;
50
+ use: (seconds: number) => void;
51
+ timeout: () => void;
52
+ stop: () => void;
53
+ };
54
+ /** `wt.embedded.<key>` gauges for an embedded store, read at each export. Returns `stop()`. */
55
+ export declare function observeEmbedded(system: string, namespace: string | undefined, keys: string[], read: () => Partial<Record<string, number>>): () => void;
56
+ /** Hit/miss counters (`wt.embedded.cache.hits` / `.misses`) for an in-memory cache. */
57
+ export declare function cacheCounters(system: string, name: string): {
58
+ hit: (n?: number) => void;
59
+ miss: (n?: number) => void;
60
+ };
61
+ /** Size in bytes of a file, or of the files directly in a directory; 0 when missing. */
62
+ export declare function sizeOf(path: string): number;
@@ -0,0 +1,239 @@
1
+ // Shared core for the datastore and queue integrations: CLIENT spans with OTel db semconv, the
2
+ // statement hash and N+1 hint, connection-pool metrics and embedded-store gauges.
3
+ import * as fs from 'node:fs';
4
+ import * as nodePath from 'node:path';
5
+ import { context, createContextKey, metrics, trace, SpanKind, SpanStatusCode } from '@opentelemetry/api';
6
+ import { isPgDialect, normalizeAndHash, querySummary } from '../sql.js';
7
+ /** Set inside an instrumented call so a wrapper the library calls internally adds no second span. */
8
+ const INSIDE = createContextKey('watchtower.db.inside');
9
+ export const inside = (ctx = context.active()) => ctx.getValue(INSIDE) === true;
10
+ /** `parent` with `span` active; `nested` marks it as inside an instrumented call (no inner spans). */
11
+ export const enter = (parent, span, nested = true) => nested ? trace.setSpan(parent, span).setValue(INSIDE, true) : trace.setSpan(parent, span).deleteValue(INSIDE);
12
+ const on = (v) => ['1', 'true', 'on', 'yes'].includes((v || '').trim().toLowerCase());
13
+ const threshold = (o) => o?.nPlusOne ?? (Number(process.env.WATCHTOWER_DB_N_PLUS_ONE) || 5);
14
+ // parent span id -> statement key -> count.
15
+ // shortcut: keeps the 1000 most recently seen parents; raise it if very wide fan-out traces miss hints.
16
+ const seen = new Map();
17
+ function repeats(parent, key) {
18
+ let m = seen.get(parent);
19
+ if (!m) {
20
+ if (seen.size >= 1000)
21
+ seen.delete(seen.keys().next().value);
22
+ seen.set(parent, (m = new Map()));
23
+ }
24
+ const n = (m.get(key) ?? 0) + 1;
25
+ m.set(key, n);
26
+ return n;
27
+ }
28
+ /** A CLIENT span for `op` (not made active): summary, hash, N+1 hint. Prefer `traced`. */
29
+ export function startDbSpan(op, opts, parent, startTime) {
30
+ const attrs = { 'db.system.name': op.system, ...op.attributes };
31
+ let { operation, collection } = op;
32
+ let name = [operation, collection].filter(Boolean).join(' ') || op.system;
33
+ let key = name;
34
+ if (op.sql) {
35
+ const [norm, hash] = normalizeAndHash(op.sql, isPgDialect(op.system));
36
+ const s = querySummary(norm, op.system);
37
+ operation ??= s.operation;
38
+ collection ??= s.target;
39
+ name = s.summary;
40
+ key = hash;
41
+ attrs['db.query.summary'] = s.summary;
42
+ attrs['db.query.hash'] = hash;
43
+ if (opts?.queryText ?? on(process.env.WATCHTOWER_DB_QUERY_TEXT))
44
+ attrs['db.query.text'] = norm;
45
+ }
46
+ if (operation)
47
+ attrs['db.operation.name'] = operation;
48
+ if (collection)
49
+ attrs['db.collection.name'] = collection;
50
+ if (op.namespace)
51
+ attrs['db.namespace'] = op.namespace;
52
+ const p = trace.getSpan(parent)?.spanContext();
53
+ const max = threshold(opts);
54
+ if (p && max > 0) {
55
+ const n = repeats(p.spanId, key);
56
+ if (n > max) {
57
+ attrs['db.query.repeat_count'] = n;
58
+ attrs['db.n_plus_one'] = true;
59
+ }
60
+ }
61
+ return trace.getTracer('watchtower').startSpan(name, { kind: SpanKind.CLIENT, attributes: attrs, startTime }, parent);
62
+ }
63
+ /** A finished CLIENT span for a query a library reports after the fact (ORM loggers): it ends now. */
64
+ export function recordDbSpan(op, opts, durationMs, error) {
65
+ const end = Date.now();
66
+ const span = startDbSpan(op, opts, context.active(), end - Math.max(0, durationMs || 0));
67
+ if (error)
68
+ fail(span, error);
69
+ span.end(end);
70
+ }
71
+ /** Error status with the driver's code; the message is not recorded (it can quote values). */
72
+ export function fail(span, e) {
73
+ const code = e?.code;
74
+ if (typeof code === 'string' || typeof code === 'number') {
75
+ span.setAttribute('db.response.status_code', String(code));
76
+ span.setAttribute('error.type', String(code));
77
+ }
78
+ else {
79
+ span.setAttribute('error.type', e?.name || 'Error');
80
+ }
81
+ span.setStatus({ code: SpanStatusCode.ERROR });
82
+ }
83
+ const isThenable = (v) => !!v && (typeof v === 'object' || typeof v === 'function') && typeof v.then === 'function';
84
+ /** Run `fn` and end `span` when it returns, throws or its promise settles. The result is returned as is. */
85
+ export function settle(span, fn) {
86
+ let r;
87
+ try {
88
+ r = fn();
89
+ }
90
+ catch (e) {
91
+ fail(span, e);
92
+ span.end();
93
+ throw e;
94
+ }
95
+ if (isThenable(r)) {
96
+ r.then(() => span.end(), (e) => { fail(span, e); span.end(); });
97
+ }
98
+ else {
99
+ span.end();
100
+ }
101
+ return r;
102
+ }
103
+ /** A CLIENT span around `fn` (sync or promise), child of the active span. `nested: false` lets
104
+ * calls made inside `fn` (a transaction callback) get their own spans. */
105
+ export function traced(op, opts, fn, nested = true) {
106
+ const parent = context.active();
107
+ if (inside(parent))
108
+ return fn();
109
+ const span = startDbSpan(op, opts, parent);
110
+ return settle(span, () => context.with(enter(parent, span, nested), fn));
111
+ }
112
+ /** `traced` for node-style callback APIs: the last function argument ends the span and runs in the caller's context. */
113
+ export function tracedCb(op, opts, args, call) {
114
+ const last = args.length - 1;
115
+ const cb = args[last];
116
+ const parent = context.active();
117
+ if (typeof cb !== 'function')
118
+ return traced(op, opts, () => call(args));
119
+ if (inside(parent))
120
+ return call(args);
121
+ const span = startDbSpan(op, opts, parent);
122
+ const copy = args.slice();
123
+ copy[last] = context.bind(parent, function (err, ...rest) {
124
+ if (err)
125
+ fail(span, err);
126
+ span.end();
127
+ return cb.apply(this, [err, ...rest]);
128
+ });
129
+ try {
130
+ return context.with(enter(parent, span), () => call(copy));
131
+ }
132
+ catch (e) {
133
+ fail(span, e);
134
+ span.end();
135
+ throw e;
136
+ }
137
+ }
138
+ /** Wrap `obj[name]` once; `wrap` gets the original. Missing methods are skipped. */
139
+ export function patch(obj, name, wrap) {
140
+ const o = obj;
141
+ const orig = o[name];
142
+ if (typeof orig !== 'function' || orig[WRAPPED])
143
+ return;
144
+ const w = wrap(orig);
145
+ w[WRAPPED] = true;
146
+ o[name] = w;
147
+ }
148
+ const WRAPPED = Symbol.for('watchtower.wrapped');
149
+ // ---- metrics (instruments come from the global meter: call the observe* helpers after init) ----
150
+ const meter = () => metrics.getMeter('watchtower');
151
+ let cached;
152
+ function inst() {
153
+ const m = meter();
154
+ if (cached?.m !== m) {
155
+ cached = {
156
+ m,
157
+ wait: m.createHistogram('db.client.connection.wait_time', { unit: 's' }),
158
+ use: m.createHistogram('db.client.connection.use_time', { unit: 's' }),
159
+ timeouts: m.createCounter('db.client.connection.timeouts'),
160
+ hits: m.createCounter('wt.embedded.cache.hits'),
161
+ misses: m.createCounter('wt.embedded.cache.misses'),
162
+ };
163
+ }
164
+ return cached;
165
+ }
166
+ /**
167
+ * Pool gauges per OTel db semconv, read at each export: `db.client.connection.count{state}`,
168
+ * `.max`, `.pending_requests`, with `db.client.connection.pool.name` and `db.system.name`.
169
+ * Returns the recorders for wait/use time and timeouts, and `stop()`.
170
+ */
171
+ export function observePool(system, pool, read) {
172
+ const attrs = { 'db.system.name': system, 'db.client.connection.pool.name': pool };
173
+ const m = meter();
174
+ const count = m.createObservableGauge('db.client.connection.count');
175
+ const max = m.createObservableGauge('db.client.connection.max');
176
+ const pending = m.createObservableGauge('db.client.connection.pending_requests');
177
+ const cb = (r) => {
178
+ const s = read();
179
+ if (s.used !== undefined)
180
+ r.observe(count, s.used, { ...attrs, 'db.client.connection.state': 'used' });
181
+ if (s.idle !== undefined)
182
+ r.observe(count, s.idle, { ...attrs, 'db.client.connection.state': 'idle' });
183
+ if (s.max !== undefined)
184
+ r.observe(max, s.max, attrs);
185
+ if (s.pending !== undefined)
186
+ r.observe(pending, s.pending, attrs);
187
+ };
188
+ m.addBatchObservableCallback(cb, [count, max, pending]);
189
+ return {
190
+ wait: (seconds) => inst().wait.record(seconds, attrs),
191
+ use: (seconds) => inst().use.record(seconds, attrs),
192
+ timeout: () => inst().timeouts.add(1, attrs),
193
+ stop: () => m.removeBatchObservableCallback(cb, [count, max, pending]),
194
+ };
195
+ }
196
+ /** `wt.embedded.<key>` gauges for an embedded store, read at each export. Returns `stop()`. */
197
+ export function observeEmbedded(system, namespace, keys, read) {
198
+ const attrs = { 'db.system.name': system, ...(namespace ? { 'db.namespace': namespace } : {}) };
199
+ const m = meter();
200
+ const gauges = keys.map((k) => [k, m.createObservableGauge(`wt.embedded.${k}`)]);
201
+ const cb = (r) => {
202
+ let v;
203
+ try {
204
+ v = read();
205
+ }
206
+ catch {
207
+ return;
208
+ }
209
+ for (const [k, g] of gauges)
210
+ if (typeof v[k] === 'number')
211
+ r.observe(g, v[k], attrs);
212
+ };
213
+ m.addBatchObservableCallback(cb, gauges.map(([, g]) => g));
214
+ return () => m.removeBatchObservableCallback(cb, gauges.map(([, g]) => g));
215
+ }
216
+ /** Hit/miss counters (`wt.embedded.cache.hits` / `.misses`) for an in-memory cache. */
217
+ export function cacheCounters(system, name) {
218
+ const attrs = { 'db.system.name': system, 'db.namespace': name };
219
+ return { hit: (n = 1) => inst().hits.add(n, attrs), miss: (n = 1) => inst().misses.add(n, attrs) };
220
+ }
221
+ /** Size in bytes of a file, or of the files directly in a directory; 0 when missing. */
222
+ export function sizeOf(path) {
223
+ try {
224
+ const st = fs.statSync(path);
225
+ if (!st.isDirectory())
226
+ return st.size;
227
+ return fs.readdirSync(path).reduce((n, f) => {
228
+ try {
229
+ return n + fs.statSync(nodePath.join(path, f)).size;
230
+ }
231
+ catch {
232
+ return n;
233
+ }
234
+ }, 0);
235
+ }
236
+ catch {
237
+ return 0;
238
+ }
239
+ }
@@ -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,29 @@
1
+ import * as nodePath from 'node:path';
2
+ import { observeEmbedded, patch, sizeOf, traced } from './db.js';
3
+ import { patchCallbackDb } from './sqlite.js';
4
+ const NEO = ['run', 'runAndRead', 'runAndReadAll', 'runAndReadUntil', 'stream', 'streamAndRead', 'streamAndReadAll',
5
+ 'streamAndReadUntil'];
6
+ /**
7
+ * `import * as duckdb from '@duckdb/node-api'` (or the classic `duckdb` package);
8
+ * `instrumentDuckDB(duckdb)`: a span per statement run on a `DuckDBConnection` (or a classic
9
+ * `Database`/`Connection`), `db.system.name=duckdb`. Returns false when neither API is found.
10
+ * shortcut: prepared statements (`connection.prepare`) are not traced.
11
+ */
12
+ export function instrumentDuckDB(duckdb, opts) {
13
+ const neo = duckdb.DuckDBConnection?.prototype;
14
+ if (neo) {
15
+ for (const m of NEO) {
16
+ patch(neo, m, (orig) => function (sql, ...a) {
17
+ return traced({ system: 'duckdb', sql: typeof sql === 'string' ? sql : undefined }, opts, () => orig.call(this, sql, ...a));
18
+ });
19
+ }
20
+ return true;
21
+ }
22
+ const protos = [duckdb.Database?.prototype, duckdb.Connection?.prototype].filter((p) => !!p);
23
+ patchCallbackDb(protos, 'duckdb', opts);
24
+ return protos.length > 0;
25
+ }
26
+ /** `wt.embedded.file.size` and `wt.embedded.wal.size` (the `.wal` file) of a DuckDB database file. Returns `stop()`. */
27
+ export function observeDuckDBFile(path) {
28
+ return observeEmbedded('duckdb', nodePath.basename(path), ['file.size', 'wal.size'], () => ({ 'file.size': sizeOf(path), 'wal.size': sizeOf(`${path}.wal`) }));
29
+ }
@@ -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,46 @@
1
+ import { trace } from '@opentelemetry/api';
2
+ import { patch } from './db.js';
3
+ import { consume, injectData, produce, takeContext } from './messaging.js';
4
+ const attrs = (task, type, op) => ({
5
+ 'messaging.system': 'graphile-worker',
6
+ 'messaging.destination.name': task,
7
+ 'messaging.operation.type': type,
8
+ 'messaging.operation.name': op,
9
+ });
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 function instrumentAddJob(utilsOrRunner) {
16
+ patch(utilsOrRunner, 'addJob', (orig) => function (identifier, payload, ...rest) {
17
+ return produce(`send ${identifier}`, attrs(identifier, 'send', 'addJob'), () => {
18
+ const span = trace.getActiveSpan();
19
+ return orig.call(this, identifier, injectData(payload ?? {}), ...rest).then((job) => {
20
+ if (job?.id !== undefined)
21
+ span?.setAttribute('messaging.message.id', String(job.id));
22
+ return job;
23
+ });
24
+ });
25
+ });
26
+ }
27
+ /**
28
+ * `run({ taskList: wrapTaskList({ send_email: async (payload, helpers) => ... }) })`: each task runs
29
+ * in a CONSUMER span, child of and linked to the `addJob` that queued it; `_wt` is removed from the
30
+ * payload first, and `helpers.addJob` is instrumented so follow-up jobs stay in the trace.
31
+ */
32
+ export function wrapTaskList(tasks) {
33
+ return Object.fromEntries(Object.entries(tasks).map(([name, fn]) => [name, (payload, helpers) => {
34
+ const carrier = takeContext(payload);
35
+ const a = attrs(name, 'process', 'task');
36
+ if (helpers?.job?.id !== undefined)
37
+ a['messaging.message.id'] = String(helpers.job.id);
38
+ if (helpers?.job?.attempts !== undefined)
39
+ a['messaging.graphile_worker.job.attempt'] = helpers.job.attempts;
40
+ if (helpers?.job?.queue_name)
41
+ a['messaging.consumer.group.name'] = helpers.job.queue_name;
42
+ if (helpers)
43
+ instrumentAddJob(helpers);
44
+ return consume(`process ${name}`, a, [carrier], () => fn(payload, helpers));
45
+ }]));
46
+ }
@@ -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,35 @@
1
+ import * as nodePath from 'node:path';
2
+ import { observeEmbedded, patch, sizeOf, tracedCb } from './db.js';
3
+ const OPS = ['get', 'getMany', 'put', 'del', 'batch', 'clear'];
4
+ /**
5
+ * `instrumentLevel(new ClassicLevel(dir))`, or `instrumentLevel(rocksdb(dir), { system: 'rocksdb' })`:
6
+ * a span per `get`/`getMany`/`put`/`del`/`batch`/`clear` (promise or callback form; keys and values
7
+ * are never recorded), on the db and on its sublevels (`db.collection.name`). With `metrics` (default
8
+ * on) and a `location`, `wt.embedded.file.size` reports the size of the store's directory.
9
+ * Returns `stop()` for the gauge.
10
+ * shortcut: iterators and the chained `batch()` builder are not traced.
11
+ */
12
+ export function instrumentLevel(db, opts) {
13
+ const system = opts?.system ?? 'leveldb';
14
+ const namespace = db.location ? nodePath.basename(db.location) : undefined;
15
+ const wrap = (d, collection) => {
16
+ for (const m of OPS) {
17
+ patch(d, m, (orig) => function (...a) {
18
+ if (m === 'batch' && a.length === 0)
19
+ return orig.call(this); // chained builder
20
+ return tracedCb({ system, operation: m, collection, namespace }, opts, a, (args) => orig.apply(this, args));
21
+ });
22
+ }
23
+ patch(d, 'sublevel', (orig) => function (...a) {
24
+ const sub = orig.apply(this, a);
25
+ if (sub)
26
+ wrap(sub, typeof a[0] === 'string' ? a[0] : undefined);
27
+ return sub;
28
+ });
29
+ };
30
+ wrap(db);
31
+ const dir = db.location;
32
+ if (opts?.metrics === false || !dir)
33
+ return () => { };
34
+ return observeEmbedded(system, namespace, ['file.size'], () => ({ 'file.size': sizeOf(dir) }));
35
+ }
@@ -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,42 @@
1
+ import * as nodePath from 'node:path';
2
+ import { observeEmbedded, patch, sizeOf, traced } from './db.js';
3
+ const WRITES = ['put', 'remove', 'ifVersion', 'ifNoExists', 'clearAsync', 'drop', 'getMany', 'prefetch'];
4
+ /**
5
+ * `instrumentLmdb(open({ path }))` (lmdb-js): spans for async writes (`put`, `remove`, `ifVersion`,
6
+ * `ifNoExists`, `clearAsync`, `drop`), `getMany` and `transaction` (calls inside a transaction get
7
+ * child spans), on the root and on every `openDB` sub-database (`db.collection.name`). Sync reads
8
+ * (`get`) are memory-mapped and take microseconds, so they get no span. With `metrics` (default on)
9
+ * it also reports `wt.embedded.map.size`, `.map.used`, `.entries`, `.readers` and `.file.size`.
10
+ * Returns `stop()` for the gauges.
11
+ */
12
+ export function instrumentLmdb(db, opts) {
13
+ const namespace = db.path ? nodePath.basename(db.path) : undefined;
14
+ const wrap = (d, collection) => {
15
+ for (const m of WRITES) {
16
+ patch(d, m, (orig) => function (...a) {
17
+ return traced({ system: 'lmdb', operation: m, collection, namespace }, opts, () => orig.apply(this, a));
18
+ });
19
+ }
20
+ patch(d, 'transaction', (orig) => function (...a) {
21
+ return traced({ system: 'lmdb', operation: 'transaction', collection, namespace }, opts, () => orig.apply(this, a), false);
22
+ });
23
+ patch(d, 'openDB', (orig) => function (...a) {
24
+ const sub = orig.apply(this, a);
25
+ const name = typeof a[0] === 'string' ? a[0] : a[0]?.name;
26
+ if (sub)
27
+ wrap(sub, name ?? sub.name);
28
+ return sub;
29
+ });
30
+ };
31
+ wrap(db);
32
+ if (opts?.metrics === false || typeof db.getStats !== 'function')
33
+ return () => { };
34
+ return observeEmbedded('lmdb', namespace, ['map.size', 'map.used', 'entries', 'readers', 'file.size'], () => {
35
+ const s = db.getStats();
36
+ const used = s.pageSize !== undefined && s.lastPageNumber !== undefined ? (s.lastPageNumber + 1) * s.pageSize : undefined;
37
+ return {
38
+ 'map.size': s.mapSize, 'map.used': used, entries: s.entryCount, readers: s.numReaders,
39
+ 'file.size': db.path ? sizeOf(db.path) : undefined,
40
+ };
41
+ });
42
+ }
@@ -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;