@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,55 @@
1
+ import * as dc from 'node:diagnostics_channel';
2
+ import { context, SpanStatusCode } from '@opentelemetry/api';
3
+ import { querySummary } from '../sql.js';
4
+ import { startDbSpan } from './db.js';
5
+ export { querySummary };
6
+ /**
7
+ * postgres.js has no OTel instrumentation; since 4.0 it publishes each query on the
8
+ * `postgres:query` diagnostics tracing channel. This turns those into CLIENT spans (child of the
9
+ * active span) with `db.system=postgresql`, the operation, a summary and `db.query.hash` (no
10
+ * statement text or parameters unless `opts.queryText`, then literal-free) and the SQLSTATE on
11
+ * failure. Works for ESM and CJS; returns an unsubscribe function (a no-op when this Node has no
12
+ * tracing channels).
13
+ */
14
+ export function instrumentPostgres(opts) {
15
+ if (typeof dc.tracingChannel !== 'function')
16
+ return () => { };
17
+ const ch = dc.tracingChannel('postgres:query');
18
+ const spans = new WeakMap();
19
+ const handlers = {
20
+ start(c) {
21
+ spans.set(c, startDbSpan({
22
+ system: 'postgresql', sql: c.query, namespace: c.database, attributes: { 'db.system': 'postgresql' },
23
+ }, opts, context.active()));
24
+ },
25
+ end() { },
26
+ asyncStart() { },
27
+ error(c) {
28
+ const span = spans.get(c);
29
+ if (!span)
30
+ return;
31
+ const code = c.error?.code;
32
+ if (typeof code === 'string') {
33
+ span.setAttribute('db.response.status_code', code);
34
+ span.setAttribute('error.type', code);
35
+ }
36
+ // the message can quote values (e.g. a duplicate key), so it is not recorded
37
+ span.setStatus({ code: SpanStatusCode.ERROR, message: typeof code === 'string' ? `SQLSTATE ${code}` : undefined });
38
+ },
39
+ asyncEnd(c) {
40
+ const span = spans.get(c);
41
+ if (!span)
42
+ return;
43
+ spans.delete(c);
44
+ if (c.host)
45
+ span.setAttribute('server.address', c.host);
46
+ if (c.port)
47
+ span.setAttribute('server.port', c.port);
48
+ if (typeof c.count === 'number')
49
+ span.setAttribute('db.response.returned_rows', c.count);
50
+ span.end();
51
+ },
52
+ };
53
+ ch.subscribe(handlers);
54
+ return () => ch.unsubscribe(handlers);
55
+ }
@@ -0,0 +1,3 @@
1
+ /** prisma.$extends(watchtowerExtension()): a CLIENT span per model operation (no query args recorded: they hold data).
2
+ * shortcut: $queryRaw/$executeRaw are not wrapped; add query.$queryRaw hooks if raw SQL spans are needed. */
3
+ export declare function watchtowerExtension(): object;
@@ -0,0 +1,30 @@
1
+ import { SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
2
+ /** prisma.$extends(watchtowerExtension()): a CLIENT span per model operation (no query args recorded: they hold data).
3
+ * shortcut: $queryRaw/$executeRaw are not wrapped; add query.$queryRaw hooks if raw SQL spans are needed. */
4
+ export function watchtowerExtension() {
5
+ return {
6
+ name: 'watchtower',
7
+ query: {
8
+ $allModels: {
9
+ $allOperations({ model, operation, query, args }) {
10
+ return trace.getTracer('watchtower').startActiveSpan(`prisma ${model}.${operation}`, {
11
+ kind: SpanKind.CLIENT,
12
+ attributes: { 'db.system.name': 'prisma', 'db.collection.name': model, 'db.operation.name': operation },
13
+ }, async (span) => {
14
+ try {
15
+ return await query(args);
16
+ }
17
+ catch (e) {
18
+ span.recordException(e);
19
+ span.setStatus({ code: SpanStatusCode.ERROR, message: e.message });
20
+ throw e;
21
+ }
22
+ finally {
23
+ span.end();
24
+ }
25
+ });
26
+ },
27
+ },
28
+ },
29
+ };
30
+ }
@@ -0,0 +1,36 @@
1
+ import type { DbOptions } from './db.js';
2
+ type Proto = Record<string, any>;
3
+ interface Ctor {
4
+ prototype: Proto;
5
+ }
6
+ /** `import * as sqlite from 'node:sqlite'; instrumentNodeSqlite(sqlite)`: spans for `DatabaseSync.exec`
7
+ * and prepared `run`/`get`/`all`. shortcut: `iterate()` is not traced (the span would end before the rows). */
8
+ export declare function instrumentNodeSqlite(sqlite: {
9
+ DatabaseSync: Ctor;
10
+ }, opts?: DbOptions): void;
11
+ /** `import Database from 'better-sqlite3'; instrumentBetterSqlite3(Database)`: spans for `exec` and
12
+ * prepared `run`/`get`/`all`, `db.namespace` = the database file name. */
13
+ export declare function instrumentBetterSqlite3(Database: Ctor, opts?: DbOptions): void;
14
+ /**
15
+ * Callback drivers (`sqlite3`, classic `duckdb`): trace `run`/`get`/`all`/`exec`/`each` on each
16
+ * prototype; the span ends in the callback, which runs in the caller's context.
17
+ * shortcut: a call without a callback ends its span when the call returns (no duration).
18
+ */
19
+ export declare function patchCallbackDb(protos: Proto[], system: string, opts: DbOptions | undefined): void;
20
+ /** `import sqlite3 from 'sqlite3'; instrumentSqlite3(sqlite3)`: spans for `Database` run/get/all/exec/each.
21
+ * shortcut: `Statement` objects from `db.prepare` are not traced. */
22
+ export declare function instrumentSqlite3(sqlite3: {
23
+ Database: Ctor;
24
+ }, opts?: DbOptions): void;
25
+ interface LibsqlClient {
26
+ execute(...a: any[]): Promise<unknown>;
27
+ batch?(...a: any[]): Promise<unknown>;
28
+ executeMultiple?(sql: string): Promise<unknown>;
29
+ transaction?(...a: any[]): Promise<any>;
30
+ }
31
+ /** `instrumentLibsql(createClient({ url }))`: spans for `execute`, `batch`, `executeMultiple` and
32
+ * the same calls on transactions it opens. `db.system.name=sqlite`. Returns the client. */
33
+ export declare function instrumentLibsql<C extends LibsqlClient>(client: C, opts?: DbOptions): C;
34
+ /** `wt.embedded.file.size` and `wt.embedded.wal.size` (the `-wal` file) of a SQLite database file. Returns `stop()`. */
35
+ export declare function observeSqliteFile(path: string): () => void;
36
+ export {};
@@ -0,0 +1,84 @@
1
+ import * as nodePath from 'node:path';
2
+ import { observeEmbedded, patch, sizeOf, traced, tracedCb } from './db.js';
3
+ const STATEMENT = ['run', 'get', 'all'];
4
+ /** Trace `exec(sql)` and the run/get/all of statements `prepare` returns (their prototype is patched once). */
5
+ function patchSync(db, system, opts, sqlOf, nsOf) {
6
+ patch(db, 'exec', (orig) => function (sql, ...a) {
7
+ return traced({ system, sql, namespace: nsOf({ database: this }) }, opts, () => orig.call(this, sql, ...a));
8
+ });
9
+ patch(db, 'prepare', (orig) => function (...a) {
10
+ const stmt = orig.apply(this, a);
11
+ const proto = stmt && Object.getPrototypeOf(stmt);
12
+ if (proto) {
13
+ for (const m of STATEMENT) {
14
+ patch(proto, m, (o) => function (...args) {
15
+ return traced({ system, sql: sqlOf(this), namespace: nsOf(this) }, opts, () => o.apply(this, args));
16
+ });
17
+ }
18
+ }
19
+ return stmt;
20
+ });
21
+ }
22
+ const base = (p) => (typeof p === 'string' && p && p !== ':memory:' ? nodePath.basename(p) : undefined);
23
+ /** `import * as sqlite from 'node:sqlite'; instrumentNodeSqlite(sqlite)`: spans for `DatabaseSync.exec`
24
+ * and prepared `run`/`get`/`all`. shortcut: `iterate()` is not traced (the span would end before the rows). */
25
+ export function instrumentNodeSqlite(sqlite, opts) {
26
+ patchSync(sqlite.DatabaseSync.prototype, 'sqlite', opts, (s) => s.sourceSQL, () => undefined);
27
+ }
28
+ /** `import Database from 'better-sqlite3'; instrumentBetterSqlite3(Database)`: spans for `exec` and
29
+ * prepared `run`/`get`/`all`, `db.namespace` = the database file name. */
30
+ export function instrumentBetterSqlite3(Database, opts) {
31
+ patchSync(Database.prototype, 'sqlite', opts, (s) => s.source, (s) => base(s.database?.name));
32
+ }
33
+ /**
34
+ * Callback drivers (`sqlite3`, classic `duckdb`): trace `run`/`get`/`all`/`exec`/`each` on each
35
+ * prototype; the span ends in the callback, which runs in the caller's context.
36
+ * shortcut: a call without a callback ends its span when the call returns (no duration).
37
+ */
38
+ export function patchCallbackDb(protos, system, opts) {
39
+ for (const proto of protos) {
40
+ for (const m of ['run', 'get', 'all', 'exec', 'each']) {
41
+ patch(proto, m, (orig) => function (...a) {
42
+ const op = { system, sql: typeof a[0] === 'string' ? a[0] : undefined, namespace: base(this.filename) };
43
+ const call = (args) => orig.apply(this, args);
44
+ // each(sql, ..., row, complete): only the completion callback ends the span
45
+ const cb = m !== 'each' || typeof a[a.length - 2] === 'function';
46
+ return cb ? tracedCb(op, opts, a, call) : traced(op, opts, () => call(a));
47
+ });
48
+ }
49
+ }
50
+ }
51
+ /** `import sqlite3 from 'sqlite3'; instrumentSqlite3(sqlite3)`: spans for `Database` run/get/all/exec/each.
52
+ * shortcut: `Statement` objects from `db.prepare` are not traced. */
53
+ export function instrumentSqlite3(sqlite3, opts) {
54
+ patchCallbackDb([sqlite3.Database.prototype], 'sqlite', opts);
55
+ }
56
+ /** `instrumentLibsql(createClient({ url }))`: spans for `execute`, `batch`, `executeMultiple` and
57
+ * the same calls on transactions it opens. `db.system.name=sqlite`. Returns the client. */
58
+ export function instrumentLibsql(client, opts) {
59
+ const sqlOf = (s) => (typeof s === 'string' ? s : s?.sql);
60
+ const wrap = (c) => {
61
+ patch(c, 'execute', (orig) => function (stmt, ...a) {
62
+ return traced({ system: 'sqlite', sql: sqlOf(stmt) }, opts, () => orig.call(this, stmt, ...a));
63
+ });
64
+ patch(c, 'executeMultiple', (orig) => function (sql) {
65
+ return traced({ system: 'sqlite', sql }, opts, () => orig.call(this, sql));
66
+ });
67
+ patch(c, 'batch', (orig) => function (stmts, ...a) {
68
+ return traced({ system: 'sqlite', operation: 'BATCH',
69
+ attributes: { 'db.operation.batch.size': stmts?.length ?? 0 } }, opts, () => orig.call(this, stmts, ...a));
70
+ });
71
+ };
72
+ wrap(client);
73
+ patch(client, 'transaction', (orig) => async function (...a) {
74
+ const tx = await orig.apply(this, a);
75
+ if (tx)
76
+ wrap(tx);
77
+ return tx;
78
+ });
79
+ return client;
80
+ }
81
+ /** `wt.embedded.file.size` and `wt.embedded.wal.size` (the `-wal` file) of a SQLite database file. Returns `stop()`. */
82
+ export function observeSqliteFile(path) {
83
+ return observeEmbedded('sqlite', nodePath.basename(path), ['file.size', 'wal.size'], () => ({ 'file.size': sizeOf(path), 'wal.size': sizeOf(`${path}-wal`) }));
84
+ }
@@ -0,0 +1,9 @@
1
+ import type { Context, Span } from '@opentelemetry/api';
2
+ export interface ServerSpan {
3
+ span: Span;
4
+ ctx: Context;
5
+ finish(status?: number, route?: string): void;
6
+ }
7
+ /** Start a server span; finish(status, route) names it `METHOD route` and ends it once. */
8
+ export declare function serverSpan(method: string, path?: string): ServerSpan;
9
+ export declare const statusOf: (e: unknown) => number;
@@ -0,0 +1,32 @@
1
+ import { context, trace, SpanKind, SpanStatusCode } from '@opentelemetry/api';
2
+ /** Start a server span; finish(status, route) names it `METHOD route` and ends it once. */
3
+ export function serverSpan(method, path) {
4
+ // url.path only: query strings can carry secrets
5
+ const span = trace.getTracer('watchtower').startSpan(method, {
6
+ kind: SpanKind.SERVER,
7
+ attributes: { 'http.request.method': method, 'url.path': String(path || '').split('?')[0] },
8
+ });
9
+ let done = false;
10
+ return {
11
+ span,
12
+ ctx: trace.setSpan(context.active(), span),
13
+ finish(status, route) {
14
+ if (done)
15
+ return;
16
+ done = true;
17
+ if (route) {
18
+ span.updateName(`${method} ${route}`);
19
+ span.setAttribute('http.route', route);
20
+ }
21
+ if (status)
22
+ span.setAttribute('http.response.status_code', status);
23
+ if (status !== undefined && status >= 500)
24
+ span.setStatus({ code: SpanStatusCode.ERROR });
25
+ span.end();
26
+ },
27
+ };
28
+ }
29
+ export const statusOf = (e) => {
30
+ const x = e;
31
+ return (x && (x.status || x.statusCode)) || 500;
32
+ };
@@ -0,0 +1,21 @@
1
+ import type { ReporterOptions } from './reporter-core.js';
2
+ /** The slice of Jest's `TestResult` this reporter reads. */
3
+ export interface JestTestResult {
4
+ testFilePath?: string;
5
+ testResults?: {
6
+ fullName?: string;
7
+ ancestorTitles?: string[];
8
+ title: string;
9
+ status?: string;
10
+ duration?: number | null;
11
+ failureMessages?: string[];
12
+ invocations?: number;
13
+ }[];
14
+ }
15
+ export default class WatchtowerJestReporter {
16
+ private readonly client;
17
+ private readonly tests;
18
+ constructor(_globalConfig?: unknown, options?: ReporterOptions);
19
+ onTestResult(_test: unknown, result: JestTestResult): void;
20
+ onRunComplete(): Promise<void>;
21
+ }
@@ -0,0 +1,41 @@
1
+ // Jest reporter: `reporters: ['default', ['@watchtowerobservability/node/jest', { /* apiKey, client, ... */ }]]`.
2
+ // With the test-plan environment (test-plan.ts) a quarantined failure arrives as a pending test that
3
+ // still carries its failure message; it is reported as a quarantined failure. Uploads JUnit when
4
+ // WT_CI_RUN_ID is set.
5
+ import { clientFor, reportTests, outcome } from './reporter-core.js';
6
+ import { decider, loadPlan, suiteName, testId, uploadResults } from './test-plan.js';
7
+ export default class WatchtowerJestReporter {
8
+ client;
9
+ tests = [];
10
+ constructor(_globalConfig, options) {
11
+ this.client = clientFor(options);
12
+ }
13
+ onTestResult(_test, result) {
14
+ const end = Date.now();
15
+ const decide = decider(loadPlan());
16
+ for (const t of result.testResults || []) {
17
+ const names = (t.ancestorTitles || []).concat(t.title);
18
+ const id = testId(suiteName('jest'), result.testFilePath, names);
19
+ const d = decide(id);
20
+ const failures = t.failureMessages || [];
21
+ const qFail = d.quarantined !== undefined && t.status === 'pending' && failures.length > 0;
22
+ this.tests.push({
23
+ name: t.fullName || names.join(' '),
24
+ id,
25
+ outcome: qFail ? 'failed' : outcome(t.status),
26
+ durationMs: t.duration || 0,
27
+ message: failures[0],
28
+ endMs: end,
29
+ quarantined: qFail ? d.quarantined : undefined,
30
+ isNew: d.isNew,
31
+ attempts: Math.max(0, (t.invocations || 1) - 1),
32
+ });
33
+ }
34
+ }
35
+ async onRunComplete() {
36
+ await reportTests(this.client, this.tests, 'jest');
37
+ await uploadResults(this.client, suiteName('jest'), this.tests);
38
+ if (this.client)
39
+ await this.client.shutdown().catch(() => { });
40
+ }
41
+ }
@@ -0,0 +1 @@
1
+ export declare function load(id: string): unknown;
@@ -0,0 +1,5 @@
1
+ import { createRequire } from 'node:module';
2
+ const req = createRequire(import.meta.url);
3
+ export function load(id) {
4
+ return req(id);
5
+ }
@@ -0,0 +1,10 @@
1
+ import type { Resource } from '@opentelemetry/resources';
2
+ import { MeterProvider } from '@opentelemetry/sdk-metrics';
3
+ import type { PushMetricExporter } from '@opentelemetry/sdk-metrics';
4
+ /** Explicit flag, else `WATCHTOWER_LOGS` / `WATCHTOWER_METRICS` (default on); `OTEL_*_EXPORTER=none` turns it off. */
5
+ export declare function switchOn(name: string, otelExporterEnv: string, flag?: boolean): boolean;
6
+ export interface Metrics {
7
+ provider: MeterProvider;
8
+ stop(): void;
9
+ }
10
+ export declare function startMetrics(endpoint: string, headers: Record<string, string>, resource: Resource, bufferDir: string | undefined, fetch: typeof globalThis.fetch, exporter?: PushMetricExporter): Metrics;
@@ -0,0 +1,44 @@
1
+ // Metrics: the OTel metrics SDK with a periodic OTLP/HTTP reader. Counters and histograms use
2
+ // delta temporality unless OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE is set. Node runtime
3
+ // metrics (event loop delay and utilization, GC, heap) come from the optional peer
4
+ // @opentelemetry/instrumentation-runtime-node when it is installed.
5
+ import * as nodePath from 'node:path';
6
+ import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
7
+ import { AggregationTemporalityPreference, OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
8
+ import { MetricSpool } from './buffer.js';
9
+ import { load } from './load.js';
10
+ /** Explicit flag, else `WATCHTOWER_LOGS` / `WATCHTOWER_METRICS` (default on); `OTEL_*_EXPORTER=none` turns it off. */
11
+ export function switchOn(name, otelExporterEnv, flag) {
12
+ if (flag !== undefined)
13
+ return flag;
14
+ const env = process.env;
15
+ if ((env[otelExporterEnv] || '').trim().toLowerCase() === 'none')
16
+ return false;
17
+ return !['off', 'false', '0', 'no'].includes((env[name] || 'on').trim().toLowerCase());
18
+ }
19
+ export function startMetrics(endpoint, headers, resource, bufferDir, fetch, exporter) {
20
+ const url = `${endpoint}/v1/metrics`;
21
+ let exp = exporter;
22
+ if (!exp) {
23
+ const delta = process.env.OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE
24
+ ? {} : { temporalityPreference: AggregationTemporalityPreference.DELTA };
25
+ exp = new OTLPMetricExporter({ url, headers, ...delta });
26
+ if (bufferDir)
27
+ exp = new MetricSpool(exp, nodePath.join(bufferDir, 'metrics'), url, headers, fetch);
28
+ }
29
+ const interval = Number(process.env.OTEL_METRIC_EXPORT_INTERVAL) || 60000;
30
+ const reader = new PeriodicExportingMetricReader({
31
+ exporter: exp, exportIntervalMillis: interval, exportTimeoutMillis: Math.min(30000, interval),
32
+ });
33
+ const provider = new MeterProvider({ resource, readers: [reader] });
34
+ let runtime;
35
+ try {
36
+ const mod = load('@opentelemetry/instrumentation-runtime-node');
37
+ runtime = new mod.RuntimeNodeInstrumentation();
38
+ runtime.setMeterProvider(provider);
39
+ }
40
+ catch {
41
+ // optional peer not installed
42
+ }
43
+ return { provider, stop: () => runtime?.disable() };
44
+ }
@@ -0,0 +1 @@
1
+ {"type":"module"}
@@ -0,0 +1,42 @@
1
+ import type { Span } from '@opentelemetry/api';
2
+ export interface CaptureRule {
3
+ route?: string | null;
4
+ request_headers?: string[];
5
+ response_headers?: string[];
6
+ body_bytes?: number;
7
+ graphql_query?: boolean;
8
+ }
9
+ export declare const HARD_MAX = 8192;
10
+ export declare const setCaptureRules: (r: CaptureRule[]) => void;
11
+ export declare const captureActive: () => boolean;
12
+ /** Fetch the service's rules; any failure leaves capture off. */
13
+ export declare function loadCaptureRules(o: {
14
+ apiUrl: string;
15
+ key: string;
16
+ service: string;
17
+ fetch?: typeof fetch;
18
+ }): Promise<CaptureRule[]>;
19
+ /** `*` matches any run of characters (the edge's glob). */
20
+ export declare function glob(pat: string, s: string): boolean;
21
+ export declare const ruleFor: (route: string) => CaptureRule | undefined;
22
+ /** Default secret and PII detectors: secret-named JSON and form fields, keys, tokens, emails, SSNs, Luhn-valid cards. */
23
+ export declare function redactText(s: string): string;
24
+ export declare const textLike: (type?: string) => boolean;
25
+ /** First `n` UTF-8 bytes without splitting a character. */
26
+ export declare function capBytes(s: string, n: number): string;
27
+ /** Redact a wider window than kept so a secret cut at the edge is still masked, then cap. */
28
+ export declare const excerpt: (s: string, n: number) => string;
29
+ /** Operation type and name of a GraphQL document (`{ ... }` is an anonymous query). */
30
+ export declare function graphqlOp(doc: string): {
31
+ type: string;
32
+ name?: string;
33
+ } | undefined;
34
+ export interface Payload {
35
+ route: string;
36
+ reqType?: string;
37
+ reqBody?: unknown;
38
+ resType?: string;
39
+ resBody?: unknown;
40
+ }
41
+ /** Record the bodies and GraphQL operation on `span` per the rule matching the route; no rule, nothing recorded. */
42
+ export declare function capturePayload(span: Span, p: Payload): void;
@@ -0,0 +1,131 @@
1
+ export const HARD_MAX = 8192;
2
+ const R = '[REDACTED]';
3
+ let rules = [];
4
+ export const setCaptureRules = (r) => { rules = Array.isArray(r) ? r : []; };
5
+ export const captureActive = () => rules.length > 0;
6
+ /** Fetch the service's rules; any failure leaves capture off. */
7
+ export async function loadCaptureRules(o) {
8
+ try {
9
+ const f = o.fetch || globalThis.fetch;
10
+ const res = await f(`${o.apiUrl}/v1/capture-rules?service=${encodeURIComponent(o.service)}`, {
11
+ headers: { Authorization: `Bearer ${o.key}` },
12
+ });
13
+ if (!res.ok)
14
+ return [];
15
+ const body = (await res.json());
16
+ setCaptureRules(body.rules || []);
17
+ }
18
+ catch {
19
+ setCaptureRules([]);
20
+ }
21
+ return rules;
22
+ }
23
+ /** `*` matches any run of characters (the edge's glob). */
24
+ export function glob(pat, s) {
25
+ const body = pat.split('*').map((p) => p.replace(/[.+?^$()|{}[\]\\]/g, '\\$&')).join('.*');
26
+ return new RegExp('^' + body + '$', 's').test(s);
27
+ }
28
+ export const ruleFor = (route) => rules.find((r) => !r.route || glob(r.route, route));
29
+ const luhn = (s) => {
30
+ const d = s.replace(/\D/g, '');
31
+ let sum = 0;
32
+ for (let i = 0; i < d.length; i++) {
33
+ let x = Number(d[d.length - 1 - i]);
34
+ if (i % 2)
35
+ x = x * 2 > 9 ? x * 2 - 9 : x * 2;
36
+ sum += x;
37
+ }
38
+ return d.length >= 13 && sum % 10 === 0;
39
+ };
40
+ const SECRET_KEYS = 'password|passwd|secret|token|access_token|refresh_token|client_secret|api_?key|authorization';
41
+ const PATTERNS = [
42
+ /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
43
+ /eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g,
44
+ /bearer\s+[A-Za-z0-9._~+/-]+=*/gi,
45
+ /wt[ik]_[a-z0-9]{8}_[A-Za-z0-9_-]{43}/g,
46
+ /(?:AKIA|ASIA)[0-9A-Z]{16}/g,
47
+ /gh[pousr]_[A-Za-z0-9]{36,}/g,
48
+ /[rs]k_(?:live|test)_[A-Za-z0-9]{16,}/g,
49
+ /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}/g,
50
+ /\b\d{3}-\d{2}-\d{4}\b/g,
51
+ ];
52
+ /** Default secret and PII detectors: secret-named JSON and form fields, keys, tokens, emails, SSNs, Luhn-valid cards. */
53
+ export function redactText(s) {
54
+ let out = s
55
+ .replace(new RegExp(`("(?:${SECRET_KEYS})"\\s*:\\s*)"(?:[^"\\\\]|\\\\.)*"`, 'gi'), `$1"${R}"`)
56
+ .replace(new RegExp(`\\b((?:${SECRET_KEYS})=)[^&\\s]*`, 'gi'), `$1${R}`);
57
+ for (const re of PATTERNS)
58
+ out = out.replace(re, R);
59
+ return out.replace(/\b\d{4}[ -]?\d{4}[ -]?\d{4}[ -]?\d{1,7}\b/g, (m) => (luhn(m) ? R : m));
60
+ }
61
+ export const textLike = (type) => !type || /json|^text\/|xml|x-www-form-urlencoded|graphql/i.test(type);
62
+ /** First `n` UTF-8 bytes without splitting a character. */
63
+ export function capBytes(s, n) {
64
+ const b = Buffer.from(s, 'utf8');
65
+ if (b.length <= n)
66
+ return s;
67
+ return b.subarray(0, n).toString('utf8').replace(/�$/, '');
68
+ }
69
+ /** Redact a wider window than kept so a secret cut at the edge is still masked, then cap. */
70
+ export const excerpt = (s, n) => capBytes(redactText(capBytes(s, n * 2)), n);
71
+ /** Operation type and name of a GraphQL document (`{ ... }` is an anonymous query). */
72
+ export function graphqlOp(doc) {
73
+ const d = doc.replace(/#[^\n]*/g, '');
74
+ const m = /(?:^|\})\s*(query|mutation|subscription)\b\s*([_A-Za-z][_0-9A-Za-z]*)?/.exec(d);
75
+ if (m)
76
+ return { type: m[1], ...(m[2] ? { name: m[2] } : {}) };
77
+ return /^\s*\{/.test(d) ? { type: 'query' } : undefined;
78
+ }
79
+ const asText = (b) => {
80
+ if (b === undefined || b === null)
81
+ return undefined;
82
+ if (typeof b === 'string')
83
+ return b;
84
+ if (Buffer.isBuffer(b))
85
+ return b.toString('utf8');
86
+ if (typeof b.pipe === 'function')
87
+ return undefined; // a stream: never buffered
88
+ try {
89
+ return JSON.stringify(b);
90
+ }
91
+ catch {
92
+ return undefined;
93
+ }
94
+ };
95
+ /** Record the bodies and GraphQL operation on `span` per the rule matching the route; no rule, nothing recorded. */
96
+ export function capturePayload(span, p) {
97
+ const rule = ruleFor(p.route);
98
+ if (!rule)
99
+ return;
100
+ const n = Math.min(rule.body_bytes || 0, HARD_MAX);
101
+ const req = textLike(p.reqType) ? asText(p.reqBody) : undefined;
102
+ const res = textLike(p.resType) ? asText(p.resBody) : undefined;
103
+ if (n > 0 && req)
104
+ span.setAttribute('http.request.body', excerpt(req, n));
105
+ if (n > 0 && res)
106
+ span.setAttribute('http.response.body', excerpt(res, n));
107
+ let doc;
108
+ let opName;
109
+ if (req && /graphql/i.test(p.reqType || ''))
110
+ doc = req;
111
+ else if (req) {
112
+ try {
113
+ const j = (typeof p.reqBody === 'object' ? p.reqBody : JSON.parse(req));
114
+ if (j && typeof j.query === 'string') {
115
+ doc = j.query;
116
+ if (typeof j.operationName === 'string')
117
+ opName = j.operationName;
118
+ }
119
+ }
120
+ catch { /* not JSON */ }
121
+ }
122
+ const op = doc ? graphqlOp(doc) : undefined;
123
+ if (!op || !doc)
124
+ return;
125
+ span.setAttribute('graphql.operation.type', op.type);
126
+ const name = opName || op.name;
127
+ if (name)
128
+ span.setAttribute('graphql.operation.name', name);
129
+ if (rule.graphql_query)
130
+ span.setAttribute('graphql.document', excerpt(doc, HARD_MAX));
131
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Folded stacks (`[span_id=…,trace_id=…\t]a;b;c` root first, as `foldProfile` makes them) to a
3
+ * gzipped pprof with sample types samples/count and cpu/nanoseconds. The `k=v` prefix becomes
4
+ * sample labels. Frame names keep their `(file:line)` suffix; one function per distinct frame.
5
+ */
6
+ export declare function foldedToPprof(counts: Map<string, number>, periodNs: number, startMs: number, durationMs: number): Uint8Array;
@@ -0,0 +1,85 @@
1
+ // Minimal pprof (profile.proto) encoder, no dependency: folded stacks in, gzipped protobuf out.
2
+ import { gzipSync } from 'node:zlib';
3
+ /** Protobuf writer for the handful of field shapes profile.proto needs. */
4
+ class Pb {
5
+ b = [];
6
+ varint(x) {
7
+ let n = BigInt(x);
8
+ while (n > 127n) {
9
+ this.b.push(Number(n & 127n) | 128);
10
+ n >>= 7n;
11
+ }
12
+ this.b.push(Number(n));
13
+ }
14
+ int(field, v) {
15
+ if (v) {
16
+ this.varint(field << 3);
17
+ this.varint(v);
18
+ }
19
+ return this;
20
+ }
21
+ bytes(field, data) {
22
+ this.varint((field << 3) | 2);
23
+ this.varint(data.length);
24
+ for (let i = 0; i < data.length; i++)
25
+ this.b.push(data[i]);
26
+ return this;
27
+ }
28
+ msg(field, m) {
29
+ return this.bytes(field, m.b);
30
+ }
31
+ packed(field, vs) {
32
+ const p = new Pb();
33
+ for (const v of vs)
34
+ p.varint(v);
35
+ return this.bytes(field, p.b);
36
+ }
37
+ }
38
+ /**
39
+ * Folded stacks (`[span_id=…,trace_id=…\t]a;b;c` root first, as `foldProfile` makes them) to a
40
+ * gzipped pprof with sample types samples/count and cpu/nanoseconds. The `k=v` prefix becomes
41
+ * sample labels. Frame names keep their `(file:line)` suffix; one function per distinct frame.
42
+ */
43
+ export function foldedToPprof(counts, periodNs, startMs, durationMs) {
44
+ const strings = [''];
45
+ const index = new Map([['', 0]]);
46
+ const s = (x) => {
47
+ let i = index.get(x);
48
+ if (i === undefined) {
49
+ i = strings.length;
50
+ strings.push(x);
51
+ index.set(x, i);
52
+ }
53
+ return i;
54
+ };
55
+ const vt = (type, unit) => new Pb().int(1, s(type)).int(2, s(unit));
56
+ const frames = new Map();
57
+ const out = new Pb().msg(1, vt('samples', 'count')).msg(1, vt('cpu', 'nanoseconds'));
58
+ for (const [key, n] of counts) {
59
+ const tab = key.indexOf('\t');
60
+ const labels = tab >= 0 ? key.slice(0, tab) : '';
61
+ // pprof location ids are leaf first
62
+ const ids = key.slice(tab + 1).split(';').reverse().map((f) => {
63
+ let id = frames.get(f);
64
+ if (id === undefined)
65
+ frames.set(f, (id = frames.size + 1));
66
+ return id;
67
+ });
68
+ const sample = new Pb().packed(1, ids).packed(2, [n, n * periodNs]);
69
+ for (const kv of labels ? labels.split(',') : []) {
70
+ const eq = kv.indexOf('=');
71
+ if (eq > 0)
72
+ sample.msg(3, new Pb().int(1, s(kv.slice(0, eq))).int(2, s(kv.slice(eq + 1))));
73
+ }
74
+ out.msg(2, sample);
75
+ }
76
+ for (const [f, id] of frames) {
77
+ out.msg(4, new Pb().int(1, id).msg(4, new Pb().int(1, id))); // Location{id, line[{function_id}]}
78
+ out.msg(5, new Pb().int(1, id).int(2, s(f))); // Function{id, name}
79
+ }
80
+ out.int(9, BigInt(Math.round(startMs)) * 1000000n).int(10, BigInt(Math.round(durationMs)) * 1000000n);
81
+ out.msg(11, vt('cpu', 'nanoseconds')).int(12, periodNs);
82
+ for (const str of strings)
83
+ out.bytes(6, Buffer.from(str));
84
+ return new Uint8Array(gzipSync(Uint8Array.from(out.b)));
85
+ }