@watchtowerobservability/node 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (181) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +304 -2
  3. package/dist/cjs/appsec.d.ts +95 -0
  4. package/dist/cjs/appsec.js +206 -0
  5. package/dist/cjs/buffer.d.ts +49 -0
  6. package/dist/cjs/buffer.js +134 -0
  7. package/dist/cjs/errors.d.ts +17 -0
  8. package/dist/cjs/errors.js +55 -0
  9. package/dist/cjs/index.d.ts +123 -0
  10. package/dist/cjs/index.js +315 -0
  11. package/dist/cjs/integrations/amqp.d.ts +13 -0
  12. package/dist/cjs/integrations/amqp.js +96 -0
  13. package/dist/cjs/integrations/azure-functions.d.ts +18 -0
  14. package/dist/cjs/integrations/azure-functions.js +97 -0
  15. package/dist/cjs/integrations/bullmq.d.ts +19 -0
  16. package/dist/cjs/integrations/bullmq.js +83 -0
  17. package/dist/cjs/integrations/cache.d.ts +13 -0
  18. package/dist/cjs/integrations/cache.js +51 -0
  19. package/dist/cjs/integrations/db.d.ts +62 -0
  20. package/dist/cjs/integrations/db.js +288 -0
  21. package/dist/cjs/integrations/duckdb.d.ts +22 -0
  22. package/dist/cjs/integrations/duckdb.js +66 -0
  23. package/dist/cjs/integrations/express.d.ts +25 -0
  24. package/dist/cjs/integrations/express.js +58 -0
  25. package/dist/cjs/integrations/fastify.d.ts +6 -0
  26. package/dist/cjs/integrations/fastify.js +44 -0
  27. package/dist/cjs/integrations/genai-agents.d.ts +36 -0
  28. package/dist/cjs/integrations/genai-agents.js +124 -0
  29. package/dist/cjs/integrations/genai-stream.d.ts +19 -0
  30. package/dist/cjs/integrations/genai-stream.js +135 -0
  31. package/dist/cjs/integrations/genai.d.ts +18 -0
  32. package/dist/cjs/integrations/genai.js +150 -0
  33. package/dist/cjs/integrations/graphile-worker.d.ts +22 -0
  34. package/dist/cjs/integrations/graphile-worker.js +50 -0
  35. package/dist/cjs/integrations/koa.d.ts +19 -0
  36. package/dist/cjs/integrations/koa.js +34 -0
  37. package/dist/cjs/integrations/lambda.d.ts +11 -0
  38. package/dist/cjs/integrations/lambda.js +68 -0
  39. package/dist/cjs/integrations/level.d.ts +18 -0
  40. package/dist/cjs/integrations/level.js +71 -0
  41. package/dist/cjs/integrations/lmdb.d.ts +26 -0
  42. package/dist/cjs/integrations/lmdb.js +78 -0
  43. package/dist/cjs/integrations/logs.d.ts +10 -0
  44. package/dist/cjs/integrations/logs.js +77 -0
  45. package/dist/cjs/integrations/messaging.d.ts +17 -0
  46. package/dist/cjs/integrations/messaging.js +73 -0
  47. package/dist/cjs/integrations/mqtt.d.ts +7 -0
  48. package/dist/cjs/integrations/mqtt.js +41 -0
  49. package/dist/cjs/integrations/nats.d.ts +17 -0
  50. package/dist/cjs/integrations/nats.js +73 -0
  51. package/dist/cjs/integrations/nestjs.d.ts +16 -0
  52. package/dist/cjs/integrations/nestjs.js +30 -0
  53. package/dist/cjs/integrations/next.d.ts +11 -0
  54. package/dist/cjs/integrations/next.js +59 -0
  55. package/dist/cjs/integrations/orm.d.ts +47 -0
  56. package/dist/cjs/integrations/orm.js +93 -0
  57. package/dist/cjs/integrations/pg-boss.d.ts +8 -0
  58. package/dist/cjs/integrations/pg-boss.js +63 -0
  59. package/dist/cjs/integrations/pools.d.ts +41 -0
  60. package/dist/cjs/integrations/pools.js +94 -0
  61. package/dist/cjs/integrations/postgres.d.ts +12 -0
  62. package/dist/cjs/integrations/postgres.js +92 -0
  63. package/dist/cjs/integrations/prisma.d.ts +3 -0
  64. package/dist/cjs/integrations/prisma.js +33 -0
  65. package/dist/cjs/integrations/sqlite.d.ts +36 -0
  66. package/dist/cjs/integrations/sqlite.js +125 -0
  67. package/dist/cjs/integrations/util.d.ts +9 -0
  68. package/dist/cjs/integrations/util.js +37 -0
  69. package/dist/cjs/jest.d.ts +21 -0
  70. package/dist/cjs/jest.js +45 -0
  71. package/dist/cjs/load.d.ts +1 -0
  72. package/dist/cjs/load.js +11 -0
  73. package/dist/cjs/metrics.d.ts +10 -0
  74. package/dist/cjs/metrics.js +81 -0
  75. package/dist/cjs/package.json +1 -0
  76. package/dist/cjs/payload.d.ts +42 -0
  77. package/dist/cjs/payload.js +145 -0
  78. package/dist/cjs/pprof.d.ts +6 -0
  79. package/dist/cjs/pprof.js +88 -0
  80. package/dist/cjs/probes.d.ts +97 -0
  81. package/dist/cjs/probes.js +422 -0
  82. package/dist/cjs/profiling.d.ts +84 -0
  83. package/dist/cjs/profiling.js +263 -0
  84. package/dist/cjs/reporter-core.d.ts +32 -0
  85. package/dist/cjs/reporter-core.js +102 -0
  86. package/dist/cjs/sql.d.ts +19 -0
  87. package/dist/cjs/sql.js +332 -0
  88. package/dist/cjs/test-plan.d.ts +102 -0
  89. package/dist/cjs/test-plan.js +352 -0
  90. package/dist/cjs/vitest.d.ts +27 -0
  91. package/dist/cjs/vitest.js +52 -0
  92. package/dist/esm/appsec.d.ts +95 -0
  93. package/dist/esm/appsec.js +193 -0
  94. package/dist/esm/buffer.d.ts +49 -0
  95. package/dist/esm/buffer.js +92 -0
  96. package/dist/esm/errors.d.ts +17 -0
  97. package/dist/esm/errors.js +50 -0
  98. package/dist/esm/index.d.ts +123 -0
  99. package/dist/esm/index.js +264 -0
  100. package/dist/esm/integrations/amqp.d.ts +13 -0
  101. package/dist/esm/integrations/amqp.js +92 -0
  102. package/dist/esm/integrations/azure-functions.d.ts +18 -0
  103. package/dist/esm/integrations/azure-functions.js +60 -0
  104. package/dist/esm/integrations/bullmq.d.ts +19 -0
  105. package/dist/esm/integrations/bullmq.js +79 -0
  106. package/dist/esm/integrations/cache.d.ts +13 -0
  107. package/dist/esm/integrations/cache.js +46 -0
  108. package/dist/esm/integrations/db.d.ts +62 -0
  109. package/dist/esm/integrations/db.js +239 -0
  110. package/dist/esm/integrations/duckdb.d.ts +22 -0
  111. package/dist/esm/integrations/duckdb.js +29 -0
  112. package/dist/esm/integrations/express.d.ts +25 -0
  113. package/dist/esm/integrations/express.js +54 -0
  114. package/dist/esm/integrations/fastify.d.ts +6 -0
  115. package/dist/esm/integrations/fastify.js +41 -0
  116. package/dist/esm/integrations/genai-agents.d.ts +36 -0
  117. package/dist/esm/integrations/genai-agents.js +118 -0
  118. package/dist/esm/integrations/genai-stream.d.ts +19 -0
  119. package/dist/esm/integrations/genai-stream.js +130 -0
  120. package/dist/esm/integrations/genai.d.ts +18 -0
  121. package/dist/esm/integrations/genai.js +138 -0
  122. package/dist/esm/integrations/graphile-worker.d.ts +22 -0
  123. package/dist/esm/integrations/graphile-worker.js +46 -0
  124. package/dist/esm/integrations/koa.d.ts +19 -0
  125. package/dist/esm/integrations/koa.js +31 -0
  126. package/dist/esm/integrations/lambda.d.ts +11 -0
  127. package/dist/esm/integrations/lambda.js +32 -0
  128. package/dist/esm/integrations/level.d.ts +18 -0
  129. package/dist/esm/integrations/level.js +35 -0
  130. package/dist/esm/integrations/lmdb.d.ts +26 -0
  131. package/dist/esm/integrations/lmdb.js +42 -0
  132. package/dist/esm/integrations/logs.d.ts +10 -0
  133. package/dist/esm/integrations/logs.js +40 -0
  134. package/dist/esm/integrations/messaging.d.ts +17 -0
  135. package/dist/esm/integrations/messaging.js +64 -0
  136. package/dist/esm/integrations/mqtt.d.ts +7 -0
  137. package/dist/esm/integrations/mqtt.js +38 -0
  138. package/dist/esm/integrations/nats.d.ts +17 -0
  139. package/dist/esm/integrations/nats.js +70 -0
  140. package/dist/esm/integrations/nestjs.d.ts +16 -0
  141. package/dist/esm/integrations/nestjs.js +26 -0
  142. package/dist/esm/integrations/next.d.ts +11 -0
  143. package/dist/esm/integrations/next.js +22 -0
  144. package/dist/esm/integrations/orm.d.ts +47 -0
  145. package/dist/esm/integrations/orm.js +86 -0
  146. package/dist/esm/integrations/pg-boss.d.ts +8 -0
  147. package/dist/esm/integrations/pg-boss.js +60 -0
  148. package/dist/esm/integrations/pools.d.ts +41 -0
  149. package/dist/esm/integrations/pools.js +89 -0
  150. package/dist/esm/integrations/postgres.d.ts +12 -0
  151. package/dist/esm/integrations/postgres.js +55 -0
  152. package/dist/esm/integrations/prisma.d.ts +3 -0
  153. package/dist/esm/integrations/prisma.js +30 -0
  154. package/dist/esm/integrations/sqlite.d.ts +36 -0
  155. package/dist/esm/integrations/sqlite.js +84 -0
  156. package/dist/esm/integrations/util.d.ts +9 -0
  157. package/dist/esm/integrations/util.js +32 -0
  158. package/dist/esm/jest.d.ts +21 -0
  159. package/dist/esm/jest.js +41 -0
  160. package/dist/esm/load.d.ts +1 -0
  161. package/dist/esm/load.js +5 -0
  162. package/dist/esm/metrics.d.ts +10 -0
  163. package/dist/esm/metrics.js +44 -0
  164. package/dist/esm/package.json +1 -0
  165. package/dist/esm/payload.d.ts +42 -0
  166. package/dist/esm/payload.js +131 -0
  167. package/dist/esm/pprof.d.ts +6 -0
  168. package/dist/esm/pprof.js +85 -0
  169. package/dist/esm/probes.d.ts +97 -0
  170. package/dist/esm/probes.js +412 -0
  171. package/dist/esm/profiling.d.ts +84 -0
  172. package/dist/esm/profiling.js +251 -0
  173. package/dist/esm/reporter-core.d.ts +32 -0
  174. package/dist/esm/reporter-core.js +63 -0
  175. package/dist/esm/sql.d.ts +19 -0
  176. package/dist/esm/sql.js +324 -0
  177. package/dist/esm/test-plan.d.ts +102 -0
  178. package/dist/esm/test-plan.js +336 -0
  179. package/dist/esm/vitest.d.ts +27 -0
  180. package/dist/esm/vitest.js +48 -0
  181. package/package.json +379 -4
@@ -0,0 +1,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,25 @@
1
+ /** The slice of an Express request this integration reads. */
2
+ export interface ExpressRequest {
3
+ method: string;
4
+ originalUrl?: string;
5
+ url?: string;
6
+ baseUrl?: string;
7
+ route?: {
8
+ path: string;
9
+ };
10
+ /** Parsed by a body parser before this handler's span ends (payload capture). */
11
+ body?: unknown;
12
+ headers?: Record<string, string | string[] | undefined>;
13
+ }
14
+ /** The slice of an Express response this integration reads. */
15
+ export interface ExpressResponse {
16
+ statusCode: number;
17
+ on(event: string, listener: () => void): unknown;
18
+ write?: (...a: unknown[]) => boolean;
19
+ end?: (...a: unknown[]) => unknown;
20
+ getHeader?: (name: string) => unknown;
21
+ }
22
+ /** app.use(requestHandler()) first: a server span per request, named by the matched route. */
23
+ export declare function requestHandler(): (req: ExpressRequest, res: ExpressResponse, next: (err?: unknown) => void) => void;
24
+ /** app.use(errorHandler()) after all routes: captures 5xx errors, then passes them on. */
25
+ export declare function errorHandler(): (err: unknown, req: ExpressRequest, res: ExpressResponse, next: (err?: unknown) => void) => void;
@@ -0,0 +1,54 @@
1
+ import { context } from '@opentelemetry/api';
2
+ import { captureException } from '../errors.js';
3
+ import { capturePayload, captureActive, HARD_MAX } from '../payload.js';
4
+ import { serverSpan, statusOf } from './util.js';
5
+ /** Keep the first HARD_MAX * 2 response bytes for payload capture; the response itself is untouched. */
6
+ function tapBody(res) {
7
+ const chunks = [];
8
+ let size = 0;
9
+ const keep = (c) => {
10
+ if (size >= HARD_MAX * 2 || (typeof c !== 'string' && !Buffer.isBuffer(c)))
11
+ return;
12
+ const b = Buffer.isBuffer(c) ? c : Buffer.from(c);
13
+ chunks.push(b);
14
+ size += b.length;
15
+ };
16
+ const { write, end } = res;
17
+ if (write)
18
+ res.write = (...a) => { keep(a[0]); return write.apply(res, a); };
19
+ if (end)
20
+ res.end = (...a) => { if (typeof a[0] !== 'function')
21
+ keep(a[0]); return end.apply(res, a); };
22
+ return () => Buffer.concat(chunks).toString('utf8');
23
+ }
24
+ /** app.use(requestHandler()) first: a server span per request, named by the matched route. */
25
+ export function requestHandler() {
26
+ return (req, res, next) => {
27
+ const s = serverSpan(req.method, req.originalUrl || req.url);
28
+ let body = captureActive() ? tapBody(res) : undefined;
29
+ const end = () => {
30
+ const route = req.route ? `${req.baseUrl || ''}${req.route.path}` : undefined;
31
+ if (body) {
32
+ const h = req.headers || {};
33
+ capturePayload(s.span, {
34
+ route: route || String(req.originalUrl || req.url || '').split('?')[0],
35
+ reqType: String(h['content-type'] || ''), reqBody: req.body,
36
+ resType: String((res.getHeader && res.getHeader('content-type')) || ''), resBody: body(),
37
+ });
38
+ body = undefined; // 'finish' and 'close' both fire; capture once
39
+ }
40
+ s.finish(res.statusCode, route);
41
+ };
42
+ res.on('finish', end);
43
+ res.on('close', end);
44
+ context.with(s.ctx, next);
45
+ };
46
+ }
47
+ /** app.use(errorHandler()) after all routes: captures 5xx errors, then passes them on. */
48
+ export function errorHandler() {
49
+ return (err, req, _res, next) => {
50
+ if (statusOf(err) >= 500)
51
+ captureException(err, { attributes: { 'http.route': req.route && req.route.path } });
52
+ next(err);
53
+ };
54
+ }
@@ -0,0 +1,6 @@
1
+ /** The slice of a Fastify instance this plugin uses. `any` args: Fastify types each hook's handler separately. */
2
+ export interface FastifyLike {
3
+ addHook(name: string, fn: (...args: any[]) => void): unknown;
4
+ }
5
+ /** await app.register(plugin): server span per request plus 5xx error capture. */
6
+ export declare function plugin(fastify: FastifyLike, _opts: unknown, done: (err?: Error) => void): void;
@@ -0,0 +1,41 @@
1
+ import { context } from '@opentelemetry/api';
2
+ import { captureException } from '../errors.js';
3
+ import { capturePayload, captureActive } from '../payload.js';
4
+ import { serverSpan, statusOf } from './util.js';
5
+ const KEY = Symbol('wt.span');
6
+ const SENT = Symbol('wt.sent');
7
+ /** await app.register(plugin): server span per request plus 5xx error capture. */
8
+ export function plugin(fastify, _opts, done) {
9
+ fastify.addHook('onRequest', (req, _reply, next) => {
10
+ const s = serverSpan(req.method, req.url);
11
+ req[KEY] = s;
12
+ context.with(s.ctx, next);
13
+ });
14
+ fastify.addHook('onError', (_req, _reply, err, next) => {
15
+ if (statusOf(err) >= 500)
16
+ captureException(err);
17
+ next();
18
+ });
19
+ // the serialized response body (string, Buffer or stream); passed on unchanged
20
+ fastify.addHook('onSend', (req, _reply, payload, next) => {
21
+ if (captureActive())
22
+ req[SENT] = payload;
23
+ next(null, payload);
24
+ });
25
+ fastify.addHook('onResponse', (req, reply, next) => {
26
+ const route = (req.routeOptions && req.routeOptions.url) || req.routerPath;
27
+ const s = req[KEY];
28
+ if (s && captureActive()) {
29
+ capturePayload(s.span, {
30
+ route: route || req.url.split('?')[0],
31
+ reqType: String((req.headers && req.headers['content-type']) || ''), reqBody: req.body,
32
+ resType: String((reply.getHeader && reply.getHeader('content-type')) || ''), resBody: req[SENT],
33
+ });
34
+ }
35
+ if (s)
36
+ s.finish(reply.statusCode, route);
37
+ next();
38
+ });
39
+ done();
40
+ }
41
+ plugin[Symbol.for('skip-override')] = true; // what fastify-plugin sets: hooks apply app-wide
@@ -0,0 +1,36 @@
1
+ import type { Span } from '@opentelemetry/api';
2
+ type Obj = Record<string, unknown>;
3
+ /** The part of LlamaIndex.TS `Settings.callbackManager` used here. */
4
+ export interface CallbackManagerLike {
5
+ on(event: string, handler: (e: {
6
+ detail?: unknown;
7
+ }) => void): unknown;
8
+ }
9
+ /** instrumentLlamaIndex(Settings) (from `llamaindex`): llm-start/stream/end and tool call events as spans. */
10
+ export declare function instrumentLlamaIndex(settings: {
11
+ callbackManager: CallbackManagerLike;
12
+ }): {
13
+ open: Map<string, Span>;
14
+ };
15
+ /** An OpenAI Agents SDK span as the trace processor sees it. */
16
+ interface AgentSpan {
17
+ spanId?: string;
18
+ parentId?: string | null;
19
+ spanData?: Obj;
20
+ error?: {
21
+ message?: string;
22
+ } | null;
23
+ }
24
+ /** The processor `addTraceProcessor` takes (`@openai/agents`). */
25
+ export declare class AgentsProcessor {
26
+ readonly open: Map<string, Span>;
27
+ onTraceStart(): Promise<void>;
28
+ onTraceEnd(): Promise<void>;
29
+ onSpanStart(sp: AgentSpan): Promise<void>;
30
+ onSpanEnd(sp: AgentSpan): Promise<void>;
31
+ shutdown(): Promise<void>;
32
+ forceFlush(): Promise<void>;
33
+ }
34
+ /** instrumentOpenAIAgents(addTraceProcessor) with `addTraceProcessor` from `@openai/agents`; the SDK's own tracing keeps running. */
35
+ export declare function instrumentOpenAIAgents(addTraceProcessor: (p: AgentsProcessor) => void): AgentsProcessor;
36
+ export {};
@@ -0,0 +1,118 @@
1
+ // GenAI spans for frameworks with their own hooks: LlamaIndex.TS (callback manager events) and the OpenAI Agents
2
+ // SDK (trace processors). Agent runs become `invoke_agent` spans, model calls `chat` spans with usage, tool runs
3
+ // `execute_tool` spans with the tool name, nested as the framework nests them. No message, completion or tool
4
+ // argument text is recorded. Both take the framework's own object, so neither package is a dependency.
5
+ import { context, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
6
+ import { applyExtract, extract } from './genai-stream.js';
7
+ const obj = (v) => (v && typeof v === 'object' ? v : {});
8
+ const s = (v) => (typeof v === 'string' ? v : '');
9
+ function start(name, attrs, parent) {
10
+ const ctx = parent ? trace.setSpan(context.active(), parent) : context.active();
11
+ const clean = Object.fromEntries(Object.entries(attrs).filter(([, v]) => v !== undefined && v !== ''));
12
+ return trace.getTracer('watchtower').startSpan(name, { kind: SpanKind.INTERNAL, attributes: clean }, ctx);
13
+ }
14
+ /** instrumentLlamaIndex(Settings) (from `llamaindex`): llm-start/stream/end and tool call events as spans. */
15
+ export function instrumentLlamaIndex(settings) {
16
+ const open = new Map(), t0 = new Map();
17
+ const cm = settings.callbackManager;
18
+ cm.on('llm-start', (e) => {
19
+ const id = s(obj(e.detail).id);
20
+ open.set(id, start('chat', { 'gen_ai.operation.name': 'chat', 'gen_ai.system': 'llama_index' }));
21
+ t0.set(id, Date.now());
22
+ });
23
+ cm.on('llm-stream', (e) => {
24
+ const id = s(obj(e.detail).id), at = t0.get(id);
25
+ if (at !== undefined) {
26
+ t0.delete(id);
27
+ open.get(id)?.setAttribute('gen_ai.response.time_to_first_chunk', (Date.now() - at) / 1000);
28
+ }
29
+ });
30
+ cm.on('llm-end', (e) => {
31
+ const d = obj(e.detail), id = s(d.id), span = open.get(id);
32
+ if (!span)
33
+ return;
34
+ open.delete(id);
35
+ t0.delete(id);
36
+ const res = obj(d.response);
37
+ const x = extract(res.raw);
38
+ const msg = obj(res.message), opts = obj(msg.options);
39
+ for (const tc of Array.isArray(opts.toolCall) ? opts.toolCall : []) {
40
+ const name = s(obj(tc).name);
41
+ if (name)
42
+ x.tools.push([name, s(obj(tc).id) || undefined]);
43
+ }
44
+ if (x.model)
45
+ span.updateName(`chat ${x.model}`);
46
+ applyExtract(span, x);
47
+ span.end();
48
+ });
49
+ cm.on('llm-tool-call', (e) => {
50
+ const name = s(obj(obj(e.detail).toolCall).name);
51
+ start(`execute_tool ${name}`.trim(), { 'gen_ai.operation.name': 'execute_tool', 'gen_ai.tool.name': name }).end();
52
+ });
53
+ return { open };
54
+ }
55
+ /** The processor `addTraceProcessor` takes (`@openai/agents`). */
56
+ export class AgentsProcessor {
57
+ open = new Map();
58
+ async onTraceStart() { }
59
+ async onTraceEnd() { }
60
+ async onSpanStart(sp) {
61
+ const d = obj(sp.spanData), type = s(d.type), parent = sp.parentId ? this.open.get(sp.parentId) : undefined;
62
+ let name = type || 'agents';
63
+ let attrs = {};
64
+ if (type === 'agent') {
65
+ name = `invoke_agent ${s(d.name)}`.trim();
66
+ attrs = { 'gen_ai.operation.name': 'invoke_agent', 'gen_ai.agent.name': s(d.name), 'gen_ai.system': 'openai' };
67
+ }
68
+ else if (type === 'generation' || type === 'response') {
69
+ name = `chat ${s(d.model)}`.trim();
70
+ attrs = { 'gen_ai.operation.name': 'chat', 'gen_ai.system': 'openai', 'gen_ai.request.model': s(d.model) };
71
+ }
72
+ else if (type === 'function') {
73
+ name = `execute_tool ${s(d.name)}`.trim();
74
+ attrs = { 'gen_ai.operation.name': 'execute_tool', 'gen_ai.tool.name': s(d.name) };
75
+ }
76
+ else if (type === 'handoff') {
77
+ attrs = { 'gen_ai.operation.name': 'handoff', 'gen_ai.handoff.from_agent': s(d.from_agent), 'gen_ai.handoff.to_agent': s(d.to_agent) };
78
+ }
79
+ else if (type === 'guardrail') {
80
+ name = `guardrail ${s(d.name)}`.trim();
81
+ attrs = { 'gen_ai.guardrail.name': s(d.name) };
82
+ }
83
+ if (sp.spanId)
84
+ this.open.set(sp.spanId, start(name, attrs, parent));
85
+ }
86
+ async onSpanEnd(sp) {
87
+ const span = sp.spanId ? this.open.get(sp.spanId) : undefined;
88
+ if (!span || !sp.spanId)
89
+ return;
90
+ this.open.delete(sp.spanId);
91
+ const d = obj(sp.spanData);
92
+ if (d.type === 'generation') {
93
+ const u = obj(d.usage);
94
+ applyExtract(span, { model: s(d.model) || undefined, input: u.input_tokens, output: u.output_tokens, reasons: [], tools: [] });
95
+ }
96
+ else if (d.type === 'response') {
97
+ applyExtract(span, extract(d._response ?? d.response));
98
+ }
99
+ else if (d.type === 'guardrail') {
100
+ span.setAttribute('gen_ai.guardrail.triggered', Boolean(d.triggered));
101
+ }
102
+ if (sp.error)
103
+ span.setStatus({ code: SpanStatusCode.ERROR, message: sp.error.message });
104
+ span.end();
105
+ }
106
+ async shutdown() {
107
+ for (const span of this.open.values())
108
+ span.end();
109
+ this.open.clear();
110
+ }
111
+ async forceFlush() { }
112
+ }
113
+ /** instrumentOpenAIAgents(addTraceProcessor) with `addTraceProcessor` from `@openai/agents`; the SDK's own tracing keeps running. */
114
+ export function instrumentOpenAIAgents(addTraceProcessor) {
115
+ const p = new AgentsProcessor();
116
+ addTraceProcessor(p);
117
+ return p;
118
+ }
@@ -0,0 +1,19 @@
1
+ import type { Span } from '@opentelemetry/api';
2
+ export interface Extract {
3
+ id?: string;
4
+ model?: string;
5
+ input?: number;
6
+ output?: number;
7
+ reasons: string[];
8
+ tools: [string, string | undefined][];
9
+ }
10
+ /** Reads a full response, a stream chunk or a stream event (`{ data }` for Mistral, typed events for Anthropic). */
11
+ export declare function extract(raw: unknown): Extract;
12
+ /** Sets what `x` holds; `seen` keeps a stream's tool calls from repeating. */
13
+ export declare function applyExtract(span: Span, x: Extract, seen?: Set<string>): void;
14
+ /**
15
+ * Hooks the async iterator of a stream object in place (the caller keeps the SDK's own object): the span records
16
+ * time to first chunk, usage, finish reasons and tool calls, and ends when the stream ends, fails or is closed.
17
+ * False when `res` is not async iterable.
18
+ */
19
+ export declare function tapStream(span: Span, res: unknown, startedMs: number): boolean;