@watchtowerobservability/node 0.2.0 → 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 (90) 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/index.d.ts +3 -0
  5. package/dist/cjs/index.js +14 -1
  6. package/dist/cjs/integrations/amqp.d.ts +13 -0
  7. package/dist/cjs/integrations/amqp.js +96 -0
  8. package/dist/cjs/integrations/bullmq.d.ts +19 -0
  9. package/dist/cjs/integrations/bullmq.js +83 -0
  10. package/dist/cjs/integrations/cache.d.ts +13 -0
  11. package/dist/cjs/integrations/cache.js +51 -0
  12. package/dist/cjs/integrations/db.d.ts +62 -0
  13. package/dist/cjs/integrations/db.js +288 -0
  14. package/dist/cjs/integrations/duckdb.d.ts +22 -0
  15. package/dist/cjs/integrations/duckdb.js +66 -0
  16. package/dist/cjs/integrations/graphile-worker.d.ts +22 -0
  17. package/dist/cjs/integrations/graphile-worker.js +50 -0
  18. package/dist/cjs/integrations/level.d.ts +18 -0
  19. package/dist/cjs/integrations/level.js +71 -0
  20. package/dist/cjs/integrations/lmdb.d.ts +26 -0
  21. package/dist/cjs/integrations/lmdb.js +78 -0
  22. package/dist/cjs/integrations/messaging.d.ts +17 -0
  23. package/dist/cjs/integrations/messaging.js +73 -0
  24. package/dist/cjs/integrations/mqtt.d.ts +7 -0
  25. package/dist/cjs/integrations/mqtt.js +41 -0
  26. package/dist/cjs/integrations/nats.d.ts +17 -0
  27. package/dist/cjs/integrations/nats.js +73 -0
  28. package/dist/cjs/integrations/orm.d.ts +47 -0
  29. package/dist/cjs/integrations/orm.js +93 -0
  30. package/dist/cjs/integrations/pg-boss.d.ts +8 -0
  31. package/dist/cjs/integrations/pg-boss.js +63 -0
  32. package/dist/cjs/integrations/pools.d.ts +41 -0
  33. package/dist/cjs/integrations/pools.js +94 -0
  34. package/dist/cjs/integrations/postgres.d.ts +12 -0
  35. package/dist/cjs/integrations/postgres.js +92 -0
  36. package/dist/cjs/integrations/sqlite.d.ts +36 -0
  37. package/dist/cjs/integrations/sqlite.js +125 -0
  38. package/dist/cjs/pprof.d.ts +6 -0
  39. package/dist/cjs/pprof.js +88 -0
  40. package/dist/cjs/profiling.d.ts +4 -1
  41. package/dist/cjs/profiling.js +18 -8
  42. package/dist/cjs/sql.d.ts +19 -0
  43. package/dist/cjs/sql.js +332 -0
  44. package/dist/cjs/test-plan.d.ts +10 -1
  45. package/dist/cjs/test-plan.js +91 -1
  46. package/dist/esm/appsec.d.ts +95 -0
  47. package/dist/esm/appsec.js +193 -0
  48. package/dist/esm/index.d.ts +3 -0
  49. package/dist/esm/index.js +14 -1
  50. package/dist/esm/integrations/amqp.d.ts +13 -0
  51. package/dist/esm/integrations/amqp.js +92 -0
  52. package/dist/esm/integrations/bullmq.d.ts +19 -0
  53. package/dist/esm/integrations/bullmq.js +79 -0
  54. package/dist/esm/integrations/cache.d.ts +13 -0
  55. package/dist/esm/integrations/cache.js +46 -0
  56. package/dist/esm/integrations/db.d.ts +62 -0
  57. package/dist/esm/integrations/db.js +239 -0
  58. package/dist/esm/integrations/duckdb.d.ts +22 -0
  59. package/dist/esm/integrations/duckdb.js +29 -0
  60. package/dist/esm/integrations/graphile-worker.d.ts +22 -0
  61. package/dist/esm/integrations/graphile-worker.js +46 -0
  62. package/dist/esm/integrations/level.d.ts +18 -0
  63. package/dist/esm/integrations/level.js +35 -0
  64. package/dist/esm/integrations/lmdb.d.ts +26 -0
  65. package/dist/esm/integrations/lmdb.js +42 -0
  66. package/dist/esm/integrations/messaging.d.ts +17 -0
  67. package/dist/esm/integrations/messaging.js +64 -0
  68. package/dist/esm/integrations/mqtt.d.ts +7 -0
  69. package/dist/esm/integrations/mqtt.js +38 -0
  70. package/dist/esm/integrations/nats.d.ts +17 -0
  71. package/dist/esm/integrations/nats.js +70 -0
  72. package/dist/esm/integrations/orm.d.ts +47 -0
  73. package/dist/esm/integrations/orm.js +86 -0
  74. package/dist/esm/integrations/pg-boss.d.ts +8 -0
  75. package/dist/esm/integrations/pg-boss.js +60 -0
  76. package/dist/esm/integrations/pools.d.ts +41 -0
  77. package/dist/esm/integrations/pools.js +89 -0
  78. package/dist/esm/integrations/postgres.d.ts +12 -0
  79. package/dist/esm/integrations/postgres.js +55 -0
  80. package/dist/esm/integrations/sqlite.d.ts +36 -0
  81. package/dist/esm/integrations/sqlite.js +84 -0
  82. package/dist/esm/pprof.d.ts +6 -0
  83. package/dist/esm/pprof.js +85 -0
  84. package/dist/esm/profiling.d.ts +4 -1
  85. package/dist/esm/profiling.js +17 -8
  86. package/dist/esm/sql.d.ts +19 -0
  87. package/dist/esm/sql.js +324 -0
  88. package/dist/esm/test-plan.d.ts +10 -1
  89. package/dist/esm/test-plan.js +89 -1
  90. package/package.json +161 -1
@@ -0,0 +1,96 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.instrumentAmqplib = instrumentAmqplib;
4
+ exports.instrumentRabbitmqClient = instrumentRabbitmqClient;
5
+ const db_js_1 = require("./db.js");
6
+ const messaging_js_1 = require("./messaging.js");
7
+ const sendAttrs = (dest, routingKey, op, messageId, size) => ({
8
+ 'messaging.system': 'rabbitmq',
9
+ 'messaging.destination.name': dest,
10
+ 'messaging.operation.type': 'send',
11
+ 'messaging.operation.name': op,
12
+ 'messaging.rabbitmq.destination.routing_key': routingKey,
13
+ ...(typeof messageId === 'string' ? { 'messaging.message.id': messageId } : {}),
14
+ ...(typeof size === 'number' ? { 'messaging.message.body.size': size } : {}),
15
+ });
16
+ function processAttrs(queue, m) {
17
+ const a = {
18
+ 'messaging.system': 'rabbitmq',
19
+ 'messaging.destination.name': queue,
20
+ 'messaging.operation.type': 'process',
21
+ 'messaging.operation.name': 'consume',
22
+ };
23
+ if (m.properties?.messageId)
24
+ a['messaging.message.id'] = m.properties.messageId;
25
+ if (typeof m.content?.length === 'number')
26
+ a['messaging.message.body.size'] = m.content.length;
27
+ if (m.fields?.deliveryTag !== undefined)
28
+ a['messaging.rabbitmq.message.delivery_tag'] = m.fields.deliveryTag;
29
+ if (m.fields?.redelivered !== undefined)
30
+ a['messaging.rabbitmq.message.redelivered'] = m.fields.redelivered;
31
+ if (m.fields?.consumerTag)
32
+ a['messaging.consumer.group.name'] = m.fields.consumerTag;
33
+ return a;
34
+ }
35
+ const withHeaders = (o, h) => ({ ...o, headers: { ...o?.headers, ...h } });
36
+ /**
37
+ * `instrumentAmqplib(await conn.createChannel())`: patches that channel's class (every channel of
38
+ * it): PRODUCER spans on `publish`/`sendToQueue` with the trace context in `options.headers`, and a
39
+ * CONSUMER span (child of and linked to the producer) around each `consume` callback.
40
+ * shortcut: a ConfirmChannel is its own class; pass one of those too if you use both kinds.
41
+ */
42
+ function instrumentAmqplib(channel) {
43
+ const proto = Object.getPrototypeOf(channel);
44
+ (0, db_js_1.patch)(proto, 'publish', (orig) => function (exchange, routingKey, content, options, ...rest) {
45
+ const dest = exchange || routingKey;
46
+ return (0, messaging_js_1.produce)(`publish ${dest}`, sendAttrs(dest, routingKey, 'publish', options?.messageId, content?.length), (h) => orig.call(this, exchange, routingKey, content, withHeaders(options, h), ...rest));
47
+ });
48
+ // amqplib's sendToQueue calls publish('', queue): that inner call adds no second span
49
+ (0, db_js_1.patch)(proto, 'sendToQueue', (orig) => function (queue, content, options, ...rest) {
50
+ return (0, messaging_js_1.produce)(`publish ${queue}`, sendAttrs(queue, queue, 'sendToQueue', options?.messageId, content?.length), (h) => orig.call(this, queue, content, withHeaders(options, h), ...rest));
51
+ });
52
+ (0, db_js_1.patch)(proto, 'consume', (orig) => function (queue, onMessage, ...rest) {
53
+ if (typeof onMessage !== 'function')
54
+ return orig.call(this, queue, onMessage, ...rest);
55
+ const wrapped = (m) => (m
56
+ ? (0, messaging_js_1.consume)(`process ${queue}`, processAttrs(queue, m), [m.properties?.headers], () => onMessage(m))
57
+ : onMessage(m)); // null: the server cancelled the consumer
58
+ return orig.call(this, queue, wrapped, ...rest);
59
+ });
60
+ }
61
+ /**
62
+ * `instrumentRabbitmqClient(new Connection(url))` for rabbitmq-client: publishers made by
63
+ * `createPublisher` get PRODUCER spans on `send` (context in the envelope headers); handlers given
64
+ * to `createConsumer` run in a CONSUMER span. Call it before creating publishers and consumers.
65
+ */
66
+ function instrumentRabbitmqClient(connection) {
67
+ (0, db_js_1.patch)(connection, 'createPublisher', (orig) => function (...a) {
68
+ const pub = orig.apply(this, a);
69
+ (0, db_js_1.patch)(pub, 'send', (send) => function (envelope, body, ...rest) {
70
+ const env = typeof envelope === 'string' ? { routingKey: envelope } : { ...envelope };
71
+ const rk = env.routingKey ?? '';
72
+ const dest = env.exchange || rk;
73
+ const size = typeof body === 'string' || body instanceof Uint8Array ? body.length : undefined;
74
+ return (0, messaging_js_1.produce)(`publish ${dest}`, sendAttrs(dest, rk, 'send', env.messageId, size), (h) => send.call(this, { ...env, headers: { ...env.headers, ...h } }, body, ...rest));
75
+ });
76
+ return pub;
77
+ });
78
+ (0, db_js_1.patch)(connection, 'createConsumer', (orig) => function (props, handler, ...rest) {
79
+ if (typeof handler !== 'function')
80
+ return orig.call(this, props, handler, ...rest);
81
+ const queue = (typeof props === 'string' ? props : props?.queue) ?? '';
82
+ const wrapped = function (m, ...more) {
83
+ const a = {
84
+ 'messaging.system': 'rabbitmq',
85
+ 'messaging.destination.name': queue,
86
+ 'messaging.operation.type': 'process',
87
+ 'messaging.operation.name': 'consume',
88
+ ...(m?.messageId ? { 'messaging.message.id': m.messageId } : {}),
89
+ ...(m?.deliveryTag !== undefined ? { 'messaging.rabbitmq.message.delivery_tag': m.deliveryTag } : {}),
90
+ ...(m?.redelivered !== undefined ? { 'messaging.rabbitmq.message.redelivered': m.redelivered } : {}),
91
+ };
92
+ return (0, messaging_js_1.consume)(`process ${queue}`, a, [m?.headers], () => handler.call(this, m, ...more));
93
+ };
94
+ return orig.call(this, props, wrapped, ...rest);
95
+ });
96
+ }
@@ -0,0 +1,19 @@
1
+ import { CONTEXT_KEY } from './messaging.js';
2
+ export { CONTEXT_KEY };
3
+ interface BullMQLike {
4
+ Queue: {
5
+ prototype: Record<string | symbol, unknown>;
6
+ };
7
+ Worker: {
8
+ prototype: Record<string | symbol, unknown>;
9
+ };
10
+ }
11
+ /**
12
+ * `import * as bullmq from 'bullmq'; instrumentBullMQ(bullmq)` (ESM or CJS): PRODUCER spans on
13
+ * `Queue.add`/`addBulk`, CONSUMER spans around each job a `Worker` processes, parented by the
14
+ * producer's context carried in job data under `_wt` (stripped before your processor runs; object
15
+ * data only). Call it once, before creating queues and workers. Returns false when this bullmq
16
+ * has no `Worker.callProcessJob` (consumer spans off; producer spans still on).
17
+ * shortcut: sandboxed (file path) processors run in a child process and get no consumer span.
18
+ */
19
+ export declare function instrumentBullMQ(bullmq: BullMQLike): boolean;
@@ -0,0 +1,83 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.CONTEXT_KEY = void 0;
4
+ exports.instrumentBullMQ = instrumentBullMQ;
5
+ const api_1 = require("@opentelemetry/api");
6
+ const messaging_js_1 = require("./messaging.js");
7
+ Object.defineProperty(exports, "CONTEXT_KEY", { enumerable: true, get: function () { return messaging_js_1.CONTEXT_KEY; } });
8
+ const PATCHED = Symbol.for('watchtower.bullmq');
9
+ const tracer = () => api_1.trace.getTracer('watchtower');
10
+ const base = (queue, op, name) => ({
11
+ 'messaging.system': 'bullmq',
12
+ 'messaging.destination.name': queue,
13
+ 'messaging.operation.type': op,
14
+ 'messaging.operation.name': name,
15
+ });
16
+ async function run(span, fn) {
17
+ try {
18
+ return await fn();
19
+ }
20
+ catch (e) {
21
+ span.recordException(e);
22
+ span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: e?.message });
23
+ throw e;
24
+ }
25
+ finally {
26
+ span.end();
27
+ }
28
+ }
29
+ /**
30
+ * `import * as bullmq from 'bullmq'; instrumentBullMQ(bullmq)` (ESM or CJS): PRODUCER spans on
31
+ * `Queue.add`/`addBulk`, CONSUMER spans around each job a `Worker` processes, parented by the
32
+ * producer's context carried in job data under `_wt` (stripped before your processor runs; object
33
+ * data only). Call it once, before creating queues and workers. Returns false when this bullmq
34
+ * has no `Worker.callProcessJob` (consumer spans off; producer spans still on).
35
+ * shortcut: sandboxed (file path) processors run in a child process and get no consumer span.
36
+ */
37
+ function instrumentBullMQ(bullmq) {
38
+ const q = bullmq.Queue.prototype;
39
+ const w = bullmq.Worker.prototype;
40
+ if (q[PATCHED])
41
+ return typeof w.callProcessJob === 'function';
42
+ q[PATCHED] = true;
43
+ const add = q.add;
44
+ q.add = function (name, data, opts) {
45
+ const attrs = { ...base(this.name, 'send', 'add'), 'messaging.bullmq.job.name': name };
46
+ if (opts?.delay)
47
+ attrs['messaging.bullmq.job.delay_ms'] = opts.delay;
48
+ return tracer().startActiveSpan(`send ${this.name}`, { kind: api_1.SpanKind.PRODUCER, attributes: attrs }, (span) => run(span, async () => {
49
+ const job = (await add.call(this, name, (0, messaging_js_1.injectData)(data), opts));
50
+ if (job?.id)
51
+ span.setAttribute('messaging.message.id', job.id);
52
+ return job;
53
+ }));
54
+ };
55
+ const addBulk = q.addBulk;
56
+ if (addBulk) {
57
+ q.addBulk = function (jobs) {
58
+ const attrs = { ...base(this.name, 'send', 'addBulk'), 'messaging.batch.message_count': jobs.length };
59
+ return tracer().startActiveSpan(`send ${this.name}`, { kind: api_1.SpanKind.PRODUCER, attributes: attrs }, (span) => run(span, () => addBulk.call(this, jobs.map((j) => ({ ...j, data: (0, messaging_js_1.injectData)(j.data) })))));
60
+ };
61
+ }
62
+ const call = w.callProcessJob;
63
+ if (typeof call !== 'function')
64
+ return false;
65
+ w.callProcessJob = function (job, ...rest) {
66
+ let parent = api_1.context.active();
67
+ if ((0, messaging_js_1.isPlainObject)(job.data) && (0, messaging_js_1.isPlainObject)(job.data[messaging_js_1.CONTEXT_KEY])) {
68
+ parent = api_1.propagation.extract(parent, job.data[messaging_js_1.CONTEXT_KEY]);
69
+ delete job.data[messaging_js_1.CONTEXT_KEY];
70
+ }
71
+ const attrs = {
72
+ ...base(this.name, 'process', 'process'),
73
+ 'messaging.bullmq.job.name': job.name,
74
+ 'messaging.bullmq.job.attempt': (job.attemptsMade ?? 0) + 1,
75
+ };
76
+ if (job.id)
77
+ attrs['messaging.message.id'] = job.id;
78
+ if (job.opts?.delay)
79
+ attrs['messaging.bullmq.job.delay_ms'] = job.opts.delay;
80
+ return tracer().startActiveSpan(`process ${this.name}`, { kind: api_1.SpanKind.CONSUMER, attributes: attrs }, parent, (span) => run(span, () => call.call(this, job, ...rest)));
81
+ };
82
+ return true;
83
+ }
@@ -0,0 +1,13 @@
1
+ /** Hit/miss counters and entry count for a node-cache instance (`get`, `mget`). Returns `stop()`. */
2
+ export declare function instrumentNodeCache(cache: {
3
+ getStats?(): {
4
+ keys?: number;
5
+ };
6
+ }, name?: string): () => void;
7
+ /** Hit/miss counters and entry count for an lru-cache instance (`get`). Returns `stop()`.
8
+ * shortcut: `fetch()` (the async loader) is not counted. */
9
+ export declare function instrumentLruCache(cache: {
10
+ size?: number;
11
+ }, name?: string): () => void;
12
+ /** Hit/miss counters for a Keyv instance (`get` with one key or an array; also `getMany`). */
13
+ export declare function instrumentKeyv(keyv: object, name?: string): void;
@@ -0,0 +1,51 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.instrumentNodeCache = instrumentNodeCache;
4
+ exports.instrumentLruCache = instrumentLruCache;
5
+ exports.instrumentKeyv = instrumentKeyv;
6
+ const db_js_1 = require("./db.js");
7
+ /** Count hits and misses of `get`-like methods: `undefined` is a miss; arrays and objects count per key. */
8
+ function count(c, keys, v) {
9
+ if (Array.isArray(keys)) {
10
+ const found = Array.isArray(v) ? v.filter((x) => x !== undefined).length
11
+ : v && typeof v === 'object' ? Object.keys(v).length : 0;
12
+ c.hit(found);
13
+ c.miss(keys.length - found);
14
+ }
15
+ else if (v === undefined) {
16
+ c.miss();
17
+ }
18
+ else {
19
+ c.hit();
20
+ }
21
+ }
22
+ function wrapGets(cache, system, name, methods) {
23
+ const c = (0, db_js_1.cacheCounters)(system, name);
24
+ for (const m of methods) {
25
+ (0, db_js_1.patch)(cache, m, (orig) => function (key, ...a) {
26
+ const v = orig.call(this, key, ...a);
27
+ if (v && typeof v.then === 'function') {
28
+ v.then((x) => count(c, key, x), () => { });
29
+ }
30
+ else {
31
+ count(c, key, v);
32
+ }
33
+ return v;
34
+ });
35
+ }
36
+ }
37
+ /** Hit/miss counters and entry count for a node-cache instance (`get`, `mget`). Returns `stop()`. */
38
+ function instrumentNodeCache(cache, name = 'default') {
39
+ wrapGets(cache, 'node-cache', name, ['get', 'mget']);
40
+ return (0, db_js_1.observeEmbedded)('node-cache', name, ['cache.entries'], () => ({ 'cache.entries': cache.getStats?.().keys }));
41
+ }
42
+ /** Hit/miss counters and entry count for an lru-cache instance (`get`). Returns `stop()`.
43
+ * shortcut: `fetch()` (the async loader) is not counted. */
44
+ function instrumentLruCache(cache, name = 'default') {
45
+ wrapGets(cache, 'lru-cache', name, ['get']);
46
+ return (0, db_js_1.observeEmbedded)('lru-cache', name, ['cache.entries'], () => ({ 'cache.entries': cache.size }));
47
+ }
48
+ /** Hit/miss counters for a Keyv instance (`get` with one key or an array; also `getMany`). */
49
+ function instrumentKeyv(keyv, name = 'default') {
50
+ wrapGets(keyv, 'keyv', name, ['get', 'getMany']);
51
+ }
@@ -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,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 {};