@watchtowerobservability/node 0.4.0 → 0.6.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 (62) hide show
  1. package/README.md +44 -9
  2. package/dist/cjs/buffer.d.ts +2 -3
  3. package/dist/cjs/buffer.js +6 -6
  4. package/dist/cjs/env.d.ts +12 -0
  5. package/dist/cjs/env.js +37 -0
  6. package/dist/cjs/errors.d.ts +8 -0
  7. package/dist/cjs/errors.js +23 -0
  8. package/dist/cjs/index.d.ts +34 -12
  9. package/dist/cjs/index.js +106 -52
  10. package/dist/cjs/instrument.d.ts +7 -0
  11. package/dist/cjs/instrument.js +51 -0
  12. package/dist/cjs/integrations/genai-agents.d.ts +4 -1
  13. package/dist/cjs/integrations/genai-agents.js +27 -24
  14. package/dist/cjs/integrations/genai-frameworks.d.ts +25 -0
  15. package/dist/cjs/integrations/genai-frameworks.js +211 -0
  16. package/dist/cjs/integrations/genai.d.ts +1 -0
  17. package/dist/cjs/integrations/genai.js +7 -2
  18. package/dist/cjs/integrations/next.d.ts +4 -1
  19. package/dist/cjs/integrations/next.js +13 -7
  20. package/dist/cjs/load.d.ts +2 -0
  21. package/dist/cjs/load.js +54 -5
  22. package/dist/cjs/metrics.d.ts +1 -2
  23. package/dist/cjs/metrics.js +6 -6
  24. package/dist/cjs/origin.d.ts +9 -0
  25. package/dist/cjs/origin.js +43 -0
  26. package/dist/cjs/redact.d.ts +8 -0
  27. package/dist/cjs/redact.js +43 -0
  28. package/dist/cjs/register.d.ts +1 -0
  29. package/dist/cjs/register.js +29 -0
  30. package/dist/cjs/sampling.d.ts +53 -0
  31. package/dist/cjs/sampling.js +98 -0
  32. package/dist/esm/buffer.d.ts +2 -3
  33. package/dist/esm/buffer.js +6 -6
  34. package/dist/esm/env.d.ts +12 -0
  35. package/dist/esm/env.js +33 -0
  36. package/dist/esm/errors.d.ts +8 -0
  37. package/dist/esm/errors.js +22 -0
  38. package/dist/esm/index.d.ts +34 -12
  39. package/dist/esm/index.js +104 -51
  40. package/dist/esm/instrument.d.ts +7 -0
  41. package/dist/esm/instrument.js +48 -0
  42. package/dist/esm/integrations/genai-agents.d.ts +4 -1
  43. package/dist/esm/integrations/genai-agents.js +4 -4
  44. package/dist/esm/integrations/genai-frameworks.d.ts +25 -0
  45. package/dist/esm/integrations/genai-frameworks.js +206 -0
  46. package/dist/esm/integrations/genai.d.ts +1 -0
  47. package/dist/esm/integrations/genai.js +3 -1
  48. package/dist/esm/integrations/next.d.ts +4 -1
  49. package/dist/esm/integrations/next.js +11 -6
  50. package/dist/esm/load.d.ts +2 -0
  51. package/dist/esm/load.js +78 -2
  52. package/dist/esm/metrics.d.ts +1 -2
  53. package/dist/esm/metrics.js +5 -5
  54. package/dist/esm/origin.d.ts +9 -0
  55. package/dist/esm/origin.js +39 -0
  56. package/dist/esm/redact.d.ts +8 -0
  57. package/dist/esm/redact.js +39 -0
  58. package/dist/esm/register.d.ts +1 -0
  59. package/dist/esm/register.js +27 -0
  60. package/dist/esm/sampling.d.ts +53 -0
  61. package/dist/esm/sampling.js +91 -0
  62. package/package.json +86 -14
package/dist/esm/index.js CHANGED
@@ -1,22 +1,27 @@
1
1
  // Thin Watchtower layer over the OpenTelemetry Node SDK: key header, endpoint default,
2
2
  // offline buffer, wt.*-safe resource attributes, redaction hook, getPrompt/score/evaluate/observe.
3
3
  import { inspect } from 'node:util';
4
- import { metrics, trace } from '@opentelemetry/api';
5
- import { Resource } from '@opentelemetry/resources';
6
- import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
7
- import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
8
- import { LoggerProvider, SimpleLogRecordProcessor, BatchLogRecordProcessor } from '@opentelemetry/sdk-logs';
9
- import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
10
- import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
4
+ import { context, diag, metrics, propagation, trace } from '@opentelemetry/api';
5
+ import { need as needPeer } from './load.js';
6
+ import { otelEnv } from './env.js';
7
+ import { instrumentAll } from './instrument.js';
8
+ import { LOG_BODY_KEY, redactor } from './redact.js';
11
9
  import { SpoolExporter, spoolLogs } from './buffer.js';
12
10
  import { startMetrics, switchOn } from './metrics.js';
13
11
  import * as nodePath from 'node:path';
14
12
  import { captureException, installProcessHandlers, dropReserved } from './errors.js';
15
13
  import { loadCaptureRules } from './payload.js';
16
14
  import { startProfiling } from './profiling.js';
15
+ import { RemoteSampler } from './sampling.js';
16
+ import { codeOrigin } from './origin.js';
17
17
  export { captureException, metrics, trace };
18
18
  export { setCaptureRules, capturePayload } from './payload.js';
19
19
  export const DEFAULT_ENDPOINT = 'http://localhost:4318';
20
+ /** code.filepath/code.lineno of the frame that called `log()` (stack line 0 is "Error", 1 is `log`, 2 the caller). */
21
+ export function callerOf(stack) {
22
+ const m = /\(?((?:file:\/\/)?[^()\s]+):(\d+):\d+\)?$/.exec((stack ?? '').split('\n')[2] ?? '');
23
+ return m ? { 'code.filepath': m[1].replace(/^file:\/\//, ''), 'code.lineno': Number(m[2]) } : {};
24
+ }
20
25
  const SEVERITY = { trace: 1, debug: 5, info: 9, warn: 13, error: 17, fatal: 21 };
21
26
  /** Drop caller-supplied wt.* keys: tenant identity comes only from the key. */
22
27
  export function safeResource(attrs) {
@@ -30,7 +35,9 @@ export class Client {
30
35
  headers;
31
36
  fetch;
32
37
  redact;
38
+ logCaller;
33
39
  provider;
40
+ resource;
34
41
  tracer;
35
42
  loggerProvider;
36
43
  logger;
@@ -38,56 +45,83 @@ export class Client {
38
45
  meterProvider;
39
46
  stopRuntime = () => { };
40
47
  uninstall;
48
+ /** Set when remote sampling is on. */
49
+ remoteSampler;
41
50
  /** Set when WT_PROFILING=1 started the continuous profiler. */
42
51
  profiler;
43
52
  constructor(opts) {
44
53
  const o = opts || {};
45
54
  const env = process.env;
46
- const apiKey = o.apiKey || env.WT_INGEST_KEY;
55
+ const oe = otelEnv(env);
56
+ const apiKey = o.apiKey || env.WT_INGEST_KEY || oe.bearer;
47
57
  if (!apiKey)
48
58
  throw new Error('apiKey is required (or set WT_INGEST_KEY)');
49
- this.endpoint = (o.endpoint || env.WT_OTLP_ENDPOINT || DEFAULT_ENDPOINT).replace(/\/+$/, '');
59
+ this.endpoint = (o.endpoint || env.WT_OTLP_ENDPOINT || oe.endpoint || DEFAULT_ENDPOINT).replace(/\/+$/, '');
50
60
  this.apiUrl = (o.apiUrl || env.WT_API_URL || this.endpoint).replace(/\/+$/, '');
51
61
  this.project = o.project || env.WT_PROJECT_ID;
52
- this.headers = { Authorization: `Bearer ${apiKey}` };
62
+ this.headers = { ...oe.headers, Authorization: `Bearer ${apiKey}` };
53
63
  this.fetch = o.fetch || globalThis.fetch;
54
- const environment = o.environment || env.WT_ENVIRONMENT;
55
- const release = o.release || env.WT_RELEASE;
56
- const resource = new Resource({
57
- 'service.name': o.serviceName || env.WT_SERVICE || 'app',
64
+ const environment = o.environment || env.WT_ENVIRONMENT || oe.resource['deployment.environment.name'];
65
+ const release = o.release || env.WT_RELEASE || oe.resource['service.version'];
66
+ // the OTel SDK packages are optional peers, loaded here (not at import time) with a clear error when missing
67
+ const { resourceFromAttributes } = needPeer('@opentelemetry/resources');
68
+ const resource = resourceFromAttributes({
69
+ ...safeResource(oe.resource),
70
+ 'service.name': o.serviceName || env.WT_SERVICE || oe.serviceName || 'app',
58
71
  ...(environment ? { 'deployment.environment.name': environment } : {}),
59
72
  ...(release ? { 'service.version': release } : {}),
60
73
  ...safeResource(o.resource),
61
74
  });
75
+ this.resource = resource;
62
76
  this.redact = o.redact;
63
- this.provider = new NodeTracerProvider({ resource });
64
- if (o.redact)
65
- this.provider.addSpanProcessor(redactor(o.redact));
77
+ this.logCaller = o.logCaller ?? env.WATCHTOWER_LOG_CALLER === '1';
66
78
  let exporter = o.exporter;
67
79
  if (!exporter) {
68
80
  const url = `${this.endpoint}/v1/traces`;
81
+ const { OTLPTraceExporter } = needPeer('@opentelemetry/exporter-trace-otlp-http');
69
82
  exporter = new OTLPTraceExporter({ url, headers: this.headers });
70
83
  // spans and log records spool to their own subdirectories
71
84
  if (o.bufferDir)
72
85
  exporter = new SpoolExporter(exporter, nodePath.join(o.bufferDir, 'traces'), url, this.headers, this.fetch);
73
86
  }
74
- this.provider.addSpanProcessor(new BatchSpanProcessor(exporter));
87
+ // the redactor runs first, so the batch processor exports redacted attributes
88
+ const { BatchSpanProcessor, TracerProvider: TP } = needPeer('@opentelemetry/sdk-trace');
89
+ let sampler;
90
+ if (o.remoteSampling ?? env.WT_REMOTE_SAMPLING === '1') {
91
+ const { ParentBasedSampler } = needPeer('@opentelemetry/sdk-trace');
92
+ this.remoteSampler = new RemoteSampler({
93
+ endpoint: this.endpoint, headers: this.headers, service: String(resource.attributes['service.name']), env: environment,
94
+ intervalMs: (o.samplingIntervalS ?? (Number(env.WT_SAMPLING_INTERVAL_S) || 30)) * 1000, fetch: this.fetch,
95
+ });
96
+ sampler = new ParentBasedSampler({ root: this.remoteSampler });
97
+ }
98
+ this.provider = new TP({
99
+ resource,
100
+ ...(sampler ? { sampler: sampler } : {}),
101
+ spanProcessors: [
102
+ ...(o.codeOrigin ?? env.WT_CODE_ORIGIN === '1' ? [codeOrigin()] : []),
103
+ ...(o.redact ? [redactor(o.redact)] : []),
104
+ new BatchSpanProcessor({ exporter }),
105
+ ],
106
+ });
75
107
  this.tracer = this.provider.getTracer('watchtower');
76
- this.loggerProvider = new LoggerProvider({ resource });
77
- const logsOn = switchOn('WATCHTOWER_LOGS', 'OTEL_LOGS_EXPORTER', o.logs);
108
+ // an explicit exporter never switches the other signals off: only `logs` / `metrics` / the env switches do
109
+ const logsOn = switchOn('WATCHTOWER_LOGS', 'OTEL_LOGS_EXPORTER', o.logs ?? (o.logExporter ? true : undefined));
78
110
  let logExporter = logsOn ? o.logExporter : undefined;
79
- if (logsOn && !logExporter && !o.exporter) {
111
+ if (logsOn && !logExporter) {
80
112
  const url = `${this.endpoint}/v1/logs`;
113
+ const { OTLPLogExporter } = needPeer('@opentelemetry/exporter-logs-otlp-http');
81
114
  logExporter = new OTLPLogExporter({ url, headers: this.headers });
82
115
  if (o.bufferDir)
83
116
  logExporter = spoolLogs(logExporter, nodePath.join(o.bufferDir, 'logs'), url, this.headers, this.fetch);
84
117
  }
85
- if (logExporter) {
86
- this.loggerProvider.addLogRecordProcessor(o.logExporter ? new SimpleLogRecordProcessor(logExporter) : new BatchLogRecordProcessor(logExporter));
87
- }
118
+ const { LoggerProvider: LP, BatchLogRecordProcessor } = needPeer('@opentelemetry/sdk-logs');
119
+ this.loggerProvider = new LP({
120
+ resource,
121
+ processors: !logExporter ? [] : [new BatchLogRecordProcessor({ exporter: logExporter })],
122
+ });
88
123
  this.logger = this.loggerProvider.getLogger('watchtower');
89
- // with a test span exporter only an explicit metric exporter is used, as for logs
90
- if (switchOn('WATCHTOWER_METRICS', 'OTEL_METRICS_EXPORTER', o.metrics) && (o.metricExporter || !o.exporter)) {
124
+ if (switchOn('WATCHTOWER_METRICS', 'OTEL_METRICS_EXPORTER', o.metrics ?? (o.metricExporter ? true : undefined))) {
91
125
  const m = startMetrics(this.endpoint, this.headers, resource, o.bufferDir, this.fetch, o.metricExporter);
92
126
  this.meterProvider = m.provider;
93
127
  this.stopRuntime = m.stop;
@@ -100,8 +134,12 @@ export class Client {
100
134
  log(level, body, attributes) {
101
135
  let attrs = dropReserved(attributes);
102
136
  const redact = this.redact;
103
- if (redact)
137
+ if (redact) {
104
138
  attrs = Object.fromEntries(Object.entries(attrs).map(([k, v]) => [k, redact(k, v)]));
139
+ body = String(redact(LOG_BODY_KEY, body) ?? '');
140
+ }
141
+ if (this.logCaller)
142
+ attrs = { ...attrs, ...callerOf(new Error().stack) };
105
143
  this.logger.emit({
106
144
  severityNumber: SEVERITY[level] || SEVERITY.info,
107
145
  severityText: String(level).toUpperCase(),
@@ -209,34 +247,49 @@ export class Client {
209
247
  }
210
248
  shutdown() {
211
249
  this.stopRuntime();
250
+ this.remoteSampler?.stop();
212
251
  return Promise.all([this.profiler?.then((p) => p?.stop()), this.provider.shutdown(), this.loggerProvider.shutdown(), this.meterProvider?.shutdown()]).then(() => undefined);
213
252
  }
214
253
  }
215
- function redactor(hook) {
216
- return {
217
- onStart() { },
218
- onEnd(span) {
219
- for (const k of Object.keys(span.attributes))
220
- span.attributes[k] = hook(k, span.attributes[k]);
221
- },
222
- shutdown: () => Promise.resolve(),
223
- forceFlush: () => Promise.resolve(),
224
- };
254
+ // One state per process, not per module copy: a CommonJS and an ESM copy of this package (a `-r` preload plus an `import`
255
+ // app, say) must share the client or flush()/shutdown() in one copy would miss the init() of the other.
256
+ const state = (globalThis[Symbol.for('watchtower.node.state')] ??= {});
257
+ /**
258
+ * Register the global tracer provider, context manager, propagator and meter provider. OTel allows each to be set once
259
+ * (a second set returns false and changes nothing), so a provider the app or an earlier instrumentation registered is
260
+ * left alone and a warning says so; only globals a previous `init` installed are torn down on a re-init.
261
+ */
262
+ function registerGlobals(c) {
263
+ if (state.ownsGlobals) { // a re-init replaces what the previous init installed
264
+ trace.disable();
265
+ context.disable();
266
+ propagation.disable();
267
+ metrics.disable();
268
+ }
269
+ const { AsyncLocalStorageContextManager } = needPeer('@opentelemetry/context-async-hooks');
270
+ const { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator } = needPeer('@opentelemetry/core');
271
+ const ok = [
272
+ trace.setGlobalTracerProvider(c.provider),
273
+ context.setGlobalContextManager(new AsyncLocalStorageContextManager().enable()),
274
+ propagation.setGlobalPropagator(new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()] })),
275
+ ...(c.meterProvider ? [metrics.setGlobalMeterProvider(c.meterProvider)] : []),
276
+ ];
277
+ state.ownsGlobals = ok[0] === true;
278
+ if (ok.includes(false))
279
+ diag.warn('watchtower: an OpenTelemetry global (tracer provider, context manager, propagator or meter provider) was already registered and was kept; call init() before other OTel setup to own them');
225
280
  }
226
- let current;
227
281
  export function init(opts) {
228
- if (current && current.uninstall)
229
- current.uninstall();
230
- void current?.profiler?.then((p) => p?.stop());
282
+ if (state.current && state.current.uninstall)
283
+ state.current.uninstall();
284
+ void state.current?.profiler?.then((p) => p?.stop());
231
285
  const c = new Client(opts);
232
- current = c;
233
- c.provider.register(); // global tracer + async context so trace.getActiveSpan() works
234
- if (c.meterProvider) {
235
- metrics.disable(); // a re-init replaces the previous client's provider
236
- metrics.setGlobalMeterProvider(c.meterProvider);
286
+ state.current = c;
287
+ registerGlobals(c);
288
+ if (opts?.instrument ?? !['0', 'off', 'false', 'no'].includes((process.env.WT_INSTRUMENT || '').trim().toLowerCase())) {
289
+ instrumentAll({ tracerProvider: c.provider, meterProvider: c.meterProvider }, [c.endpoint, c.apiUrl]);
237
290
  }
238
291
  if (process.env.WT_PROFILING === '1') {
239
- const attrs = c.provider.resource.attributes;
292
+ const attrs = c.resource.attributes;
240
293
  c.profiler = startProfiling({
241
294
  apiKey: c.headers.Authorization.slice('Bearer '.length),
242
295
  endpoint: c.endpoint,
@@ -250,15 +303,15 @@ export function init(opts) {
250
303
  return c;
251
304
  }
252
305
  function need() {
253
- if (!current)
306
+ if (!state.current)
254
307
  throw new Error('watchtower.init() has not been called');
255
- return current;
308
+ return state.current;
256
309
  }
257
- export const flush = () => (current ? current.forceFlush() : Promise.resolve());
310
+ export const flush = () => (state.current ? state.current.forceFlush() : Promise.resolve());
258
311
  export const log = (l, b, a) => need().log(l, b, a);
259
312
  export const getPrompt = (id) => need().getPrompt(id);
260
313
  export const score = (t, v, o) => need().score(t, v, o);
261
314
  export const evaluate = (d, t, s, o) => need().evaluate(d, t, s, o);
262
315
  export const evaluateResume = (d, t, s, prev, o) => need().evaluateResume(d, t, s, prev, o);
263
316
  export const observe = (n, f) => need().observe(n, f);
264
- export const shutdown = () => (current ? current.shutdown() : Promise.resolve());
317
+ export const shutdown = () => (state.current ? state.current.shutdown() : Promise.resolve());
@@ -0,0 +1,7 @@
1
+ interface Providers {
2
+ tracerProvider: unknown;
3
+ meterProvider?: unknown;
4
+ }
5
+ /** Register whichever of the four instrumentations is installed. Returns the package names that were enabled. */
6
+ export declare function instrumentAll(p: Providers, selfUrls: string[]): string[];
7
+ export {};
@@ -0,0 +1,48 @@
1
+ // Auto-instrumentation: node:http, fetch (undici), pg and ioredis, each only when its optional peer package is installed.
2
+ import { load } from './load.js';
3
+ const ENTRIES = [
4
+ {
5
+ pkg: '@opentelemetry/instrumentation-http', ctor: 'HttpInstrumentation',
6
+ // our own exports and API calls must not become spans
7
+ opts: (self) => ({ ignoreOutgoingRequestHook: (r) => self.some((u) => (r.hostname || r.host) === u.hostname && String(r.port ?? (u.protocol === 'https:' ? 443 : 80)) === String(u.port || (u.protocol === 'https:' ? 443 : 80))) }),
8
+ },
9
+ {
10
+ pkg: '@opentelemetry/instrumentation-undici', ctor: 'UndiciInstrumentation',
11
+ opts: (self) => ({ ignoreRequestHook: (r) => self.some((u) => r.origin === u.origin) }),
12
+ },
13
+ { pkg: '@opentelemetry/instrumentation-pg', ctor: 'PgInstrumentation', opts: () => ({}) },
14
+ { pkg: '@opentelemetry/instrumentation-ioredis', ctor: 'IORedisInstrumentation', opts: () => ({}) },
15
+ ];
16
+ /** Register whichever of the four instrumentations is installed. Returns the package names that were enabled. */
17
+ export function instrumentAll(p, selfUrls) {
18
+ let registerInstrumentations;
19
+ try {
20
+ ({ registerInstrumentations } = load('@opentelemetry/instrumentation'));
21
+ }
22
+ catch {
23
+ return []; // optional peer not installed
24
+ }
25
+ const self = selfUrls.flatMap((u) => { try {
26
+ return [new URL(u)];
27
+ }
28
+ catch {
29
+ return [];
30
+ } });
31
+ const found = [];
32
+ const names = [];
33
+ for (const e of ENTRIES) {
34
+ try {
35
+ const Ctor = load(e.pkg)[e.ctor];
36
+ if (Ctor) {
37
+ found.push(new Ctor(e.opts(self)));
38
+ names.push(e.pkg);
39
+ }
40
+ }
41
+ catch {
42
+ // package not installed (or failed to construct): skip it, never break init
43
+ }
44
+ }
45
+ if (found.length)
46
+ registerInstrumentations({ instrumentations: found, tracerProvider: p.tracerProvider, meterProvider: p.meterProvider });
47
+ return names;
48
+ }
@@ -1,5 +1,8 @@
1
- import type { Span } from '@opentelemetry/api';
1
+ import type { Attributes, Span } from '@opentelemetry/api';
2
2
  type Obj = Record<string, unknown>;
3
+ export declare const obj: (v: unknown) => Obj;
4
+ export declare const s: (v: unknown) => string;
5
+ export declare function start(name: string, attrs: Attributes, parent?: Span, startTime?: number): Span;
3
6
  /** The part of LlamaIndex.TS `Settings.callbackManager` used here. */
4
7
  export interface CallbackManagerLike {
5
8
  on(event: string, handler: (e: {
@@ -4,12 +4,12 @@
4
4
  // argument text is recorded. Both take the framework's own object, so neither package is a dependency.
5
5
  import { context, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
6
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) {
7
+ export const obj = (v) => (v && typeof v === 'object' ? v : {});
8
+ export const s = (v) => (typeof v === 'string' ? v : '');
9
+ export function start(name, attrs, parent, startTime) {
10
10
  const ctx = parent ? trace.setSpan(context.active(), parent) : context.active();
11
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);
12
+ return trace.getTracer('watchtower').startSpan(name, { kind: SpanKind.INTERNAL, attributes: clean, ...(startTime !== undefined ? { startTime } : {}) }, ctx);
13
13
  }
14
14
  /** instrumentLlamaIndex(Settings) (from `llamaindex`): llm-start/stream/end and tool call events as spans. */
15
15
  export function instrumentLlamaIndex(settings) {
@@ -0,0 +1,25 @@
1
+ import type { Span } from '@opentelemetry/api';
2
+ type Fn = (...a: unknown[]) => unknown;
3
+ /**
4
+ * langchainCallbackHandler(): pass it as `callbacks: [handler]` to a LangChain.js model, chain or LangGraph.js graph
5
+ * (`graph.invoke(input, { callbacks: [handler] })`). LangGraph nodes (chains whose metadata names `langgraph_node`)
6
+ * and the graph itself become `invoke_agent` spans, tools `execute_tool`, model calls `chat`, nested as they run;
7
+ * plain LCEL chains get no span. Returns a plain handler object (LangChain wraps it) with the open spans for tests.
8
+ */
9
+ export declare function langchainCallbackHandler(): Record<string, unknown> & {
10
+ open: Map<string, Span>;
11
+ };
12
+ /**
13
+ * instrumentVercelAI({ generateText, streamText }) with the functions from `ai`: returns wrapped copies (ES module
14
+ * exports cannot be patched). Pass `agentName` to name the run (default: the `experimental_telemetry.functionId`, else `agent`).
15
+ * const { generateText } = instrumentVercelAI({ generateText: ai.generateText });
16
+ * A multi-step loop (`maxSteps` / `stopWhen`) gives one `invoke_agent` span with a `chat` span per step and an
17
+ * `execute_tool` span per tool call.
18
+ */
19
+ export declare function instrumentVercelAI<T extends {
20
+ generateText?: Fn;
21
+ streamText?: Fn;
22
+ }>(ai: T, agentName?: string): T;
23
+ /** instrumentMastra(agent): wraps `agent.generate` and `agent.stream` of a Mastra `Agent`; the run is named after the agent. Returns the agent. */
24
+ export declare function instrumentMastra<T>(agent: T): T;
25
+ export {};
@@ -0,0 +1,206 @@
1
+ // GenAI spans for the TypeScript agent frameworks: LangGraph.js (a LangChain.js callback handler), the Vercel AI SDK
2
+ // agent loop (generateText / streamText with several steps) and Mastra agents. Same shape as the Python
3
+ // instrumentors and `genai-agents.ts`: `invoke_agent` / `chat` / `execute_tool` spans, nested as the run nests,
4
+ // never any prompt, completion or tool argument text. CrewAI has no JavaScript port, so there is no CrewAI hook here.
5
+ // Nothing is imported from the frameworks: each function takes their object.
6
+ import { context, SpanStatusCode, trace } from '@opentelemetry/api';
7
+ import { obj, s, start } from './genai-agents.js';
8
+ const num = (v) => (typeof v === 'number' ? v : undefined);
9
+ const thenable = (v) => !!v && typeof v.then === 'function';
10
+ function fail(span, e) {
11
+ span.recordException(e);
12
+ span.setStatus({ code: SpanStatusCode.ERROR, message: e?.message });
13
+ }
14
+ /**
15
+ * langchainCallbackHandler(): pass it as `callbacks: [handler]` to a LangChain.js model, chain or LangGraph.js graph
16
+ * (`graph.invoke(input, { callbacks: [handler] })`). LangGraph nodes (chains whose metadata names `langgraph_node`)
17
+ * and the graph itself become `invoke_agent` spans, tools `execute_tool`, model calls `chat`, nested as they run;
18
+ * plain LCEL chains get no span. Returns a plain handler object (LangChain wraps it) with the open spans for tests.
19
+ */
20
+ export function langchainCallbackHandler() {
21
+ const open = new Map(), up = new Map();
22
+ const begin = (runId, parentId, name, attrs) => {
23
+ up.set(runId, parentId);
24
+ let p = parentId;
25
+ while (p !== undefined && !open.has(p))
26
+ p = up.get(p); // a parent without a span: skip to its own parent
27
+ open.set(runId, start(name, attrs, p === undefined ? undefined : open.get(p)));
28
+ };
29
+ const close = (runId, error) => {
30
+ up.delete(runId);
31
+ const span = open.get(runId);
32
+ open.delete(runId);
33
+ if (span && error !== undefined)
34
+ fail(span, error);
35
+ return span;
36
+ };
37
+ const llmStart = (extra, llm) => (runId, parentId) => {
38
+ const p = obj(obj(extra).invocation_params), k = obj(obj(llm).kwargs);
39
+ const model = s(p.model) || s(p.model_name) || s(k.model) || s(k.modelName);
40
+ begin(runId, parentId, `chat ${model}`.trim(), { 'gen_ai.operation.name': 'chat', 'gen_ai.system': 'langchain', 'gen_ai.request.model': model });
41
+ };
42
+ const ender = (runId, error) => { close(runId, error)?.end(); };
43
+ const h = {
44
+ open,
45
+ handleChatModelStart: (llm, _m, runId, parentId, extra) => llmStart(extra, llm)(runId, parentId),
46
+ handleLLMStart: (llm, _p, runId, parentId, extra) => llmStart(extra, llm)(runId, parentId),
47
+ handleLLMEnd: (output, runId) => {
48
+ const span = close(runId);
49
+ if (!span)
50
+ return;
51
+ const o = obj(output), tu = obj(obj(o.llmOutput).tokenUsage);
52
+ const first = Array.isArray(o.generations) && Array.isArray(o.generations[0]) ? obj(o.generations[0][0]) : {};
53
+ const msg = obj(first.message), um = obj(msg.usage_metadata), rm = obj(msg.response_metadata);
54
+ const input = num(tu.promptTokens) ?? num(um.input_tokens), out = num(tu.completionTokens) ?? num(um.output_tokens);
55
+ if (input !== undefined)
56
+ span.setAttribute('gen_ai.usage.input_tokens', input);
57
+ if (out !== undefined)
58
+ span.setAttribute('gen_ai.usage.output_tokens', out);
59
+ if (s(rm.model_name))
60
+ span.setAttribute('gen_ai.response.model', s(rm.model_name));
61
+ if (s(rm.finish_reason))
62
+ span.setAttribute('gen_ai.response.finish_reasons', [s(rm.finish_reason)]);
63
+ span.end();
64
+ },
65
+ handleLLMError: (e, runId) => ender(runId, e),
66
+ handleChainStart: (_c, _i, runId, parentId, _t, metadata, _rt, runName) => {
67
+ const m = obj(metadata), node = s(m.langgraph_node);
68
+ // only LangGraph runs get spans (the graph root and its nodes); plain LCEL chains are noise
69
+ if (!node && !(parentId === undefined && m.langgraph_step !== undefined)) {
70
+ up.set(runId, parentId);
71
+ return;
72
+ }
73
+ const who = node && runName === node ? node : runName || node || 'graph';
74
+ begin(runId, parentId, `invoke_agent ${who}`, { 'gen_ai.operation.name': 'invoke_agent', 'gen_ai.agent.name': who, 'gen_ai.system': 'langgraph' });
75
+ },
76
+ handleChainEnd: (_o, runId) => ender(runId),
77
+ handleChainError: (e, runId) => ender(runId, e),
78
+ handleToolStart: (tool, _i, runId, parentId, _t, _m, runName) => {
79
+ const name = runName || s(obj(tool).name) || s(obj(obj(tool).kwargs).name);
80
+ begin(runId, parentId, `execute_tool ${name}`.trim(), { 'gen_ai.operation.name': 'execute_tool', 'gen_ai.tool.name': name });
81
+ },
82
+ handleToolEnd: (_o, runId) => ender(runId),
83
+ handleToolError: (e, runId) => ender(runId, e),
84
+ };
85
+ return h;
86
+ }
87
+ /** Wraps every `execute` of an AI SDK / Mastra tool set so each call is an `execute_tool` span under the agent run. */
88
+ function wrapTools(tools, root) {
89
+ const out = {};
90
+ for (const [name, t] of Object.entries(obj(tools))) {
91
+ const tool = obj(t), exec = tool.execute;
92
+ if (typeof exec !== 'function') {
93
+ out[name] = t;
94
+ continue;
95
+ }
96
+ out[name] = {
97
+ ...tool,
98
+ execute: (...a) => {
99
+ const sp = start(`execute_tool ${name}`, { 'gen_ai.operation.name': 'execute_tool', 'gen_ai.tool.name': name }, root);
100
+ const done = (e) => { if (e !== undefined)
101
+ fail(sp, e); sp.end(); };
102
+ try {
103
+ const r = exec.apply(tool, a);
104
+ if (thenable(r))
105
+ r.then(() => done(), (e) => done(e ?? new Error('tool failed')));
106
+ else
107
+ done();
108
+ return r;
109
+ }
110
+ catch (e) {
111
+ done(e);
112
+ throw e;
113
+ }
114
+ },
115
+ };
116
+ }
117
+ return out;
118
+ }
119
+ /**
120
+ * One agent run as an `invoke_agent` span. `onStepFinish` (injected, the caller's own still runs) turns every model
121
+ * step into a `chat` span with usage, timed from the previous step's end; tool `execute` calls become
122
+ * `execute_tool` spans. `optsAt` is the position of the options argument. A stream ends the run in `onFinish` /
123
+ * `onError`; a promise ends it when it settles.
124
+ */
125
+ function agentRun(system, name, orig, self, args, optsAt, stream) {
126
+ const root = start(`invoke_agent ${name}`.trim(), { 'gen_ai.operation.name': 'invoke_agent', 'gen_ai.agent.name': name, 'gen_ai.system': system });
127
+ let ended = false, last = Date.now();
128
+ const end = (e) => { if (ended)
129
+ return; ended = true; if (e !== undefined)
130
+ fail(root, e); root.end(); };
131
+ const opts = { ...obj(args[optsAt]) };
132
+ const onStep = opts.onStepFinish, onFinish = opts.onFinish, onError = opts.onError;
133
+ opts.onStepFinish = (e) => {
134
+ const d = obj(e), u = obj(d.usage), r = obj(d.response);
135
+ const model = s(r.modelId) || s(r.model) || s(d.model);
136
+ const sp = start(`chat ${model}`.trim(), { 'gen_ai.operation.name': 'chat', 'gen_ai.system': system, 'gen_ai.response.model': model }, root, last);
137
+ const input = num(u.inputTokens) ?? num(u.promptTokens), out = num(u.outputTokens) ?? num(u.completionTokens);
138
+ if (input !== undefined)
139
+ sp.setAttribute('gen_ai.usage.input_tokens', input);
140
+ if (out !== undefined)
141
+ sp.setAttribute('gen_ai.usage.output_tokens', out);
142
+ if (s(d.finishReason))
143
+ sp.setAttribute('gen_ai.response.finish_reasons', [s(d.finishReason)]);
144
+ sp.end();
145
+ last = Date.now();
146
+ return onStep?.(e);
147
+ };
148
+ if (stream) {
149
+ opts.onFinish = (e) => { end(); return onFinish?.(e); };
150
+ opts.onError = (e) => { end(obj(e).error ?? e ?? new Error('stream failed')); return onError?.(e); };
151
+ }
152
+ if (opts.tools)
153
+ opts.tools = wrapTools(opts.tools, root);
154
+ const a = [...args];
155
+ a[optsAt] = opts;
156
+ let res;
157
+ try {
158
+ res = context.with(trace.setSpan(context.active(), root), () => orig.apply(self, a));
159
+ }
160
+ catch (e) {
161
+ end(e);
162
+ throw e;
163
+ }
164
+ if (!stream) {
165
+ // side branch only: the caller keeps the framework's own promise
166
+ if (thenable(res))
167
+ res.then(() => end(), (e) => end(e ?? new Error('run failed')));
168
+ else
169
+ end();
170
+ }
171
+ return res;
172
+ }
173
+ /**
174
+ * instrumentVercelAI({ generateText, streamText }) with the functions from `ai`: returns wrapped copies (ES module
175
+ * exports cannot be patched). Pass `agentName` to name the run (default: the `experimental_telemetry.functionId`, else `agent`).
176
+ * const { generateText } = instrumentVercelAI({ generateText: ai.generateText });
177
+ * A multi-step loop (`maxSteps` / `stopWhen`) gives one `invoke_agent` span with a `chat` span per step and an
178
+ * `execute_tool` span per tool call.
179
+ */
180
+ export function instrumentVercelAI(ai, agentName) {
181
+ const out = { ...ai };
182
+ const nameOf = (a) => agentName || s(obj(obj(a[0]).experimental_telemetry).functionId) || 'agent';
183
+ if (typeof ai.generateText === 'function') {
184
+ const f = ai.generateText;
185
+ out.generateText = function (...a) { return agentRun('vercel_ai', nameOf(a), f, this, a, 0, false); };
186
+ }
187
+ if (typeof ai.streamText === 'function') {
188
+ const f = ai.streamText;
189
+ out.streamText = function (...a) { return agentRun('vercel_ai', nameOf(a), f, this, a, 0, true); };
190
+ }
191
+ return out;
192
+ }
193
+ /** instrumentMastra(agent): wraps `agent.generate` and `agent.stream` of a Mastra `Agent`; the run is named after the agent. Returns the agent. */
194
+ export function instrumentMastra(agent) {
195
+ const a = agent;
196
+ const name = s(a.name) || 'agent';
197
+ for (const [method, stream] of [['generate', false], ['stream', true]]) {
198
+ const f = a[method];
199
+ if (typeof f !== 'function' || f.__wt)
200
+ continue;
201
+ const wrapped = function (...args) { return agentRun('mastra', name, f, this, args, 1, stream); };
202
+ wrapped.__wt = true;
203
+ a[method] = wrapped;
204
+ }
205
+ return agent;
206
+ }
@@ -1,4 +1,5 @@
1
1
  export { instrumentLlamaIndex, instrumentOpenAIAgents } from './genai-agents.js';
2
+ export { instrumentMastra, instrumentVercelAI, langchainCallbackHandler } from './genai-frameworks.js';
2
3
  /**
3
4
  * instrumentOpenAI(new OpenAI()): chat.completions.create and responses.create. Returns the client.
4
5
  * For an OpenAI-compatible gateway pass its name: instrumentOpenAI(new OpenAI({ baseURL: litellmUrl }), 'litellm').
@@ -1,10 +1,12 @@
1
1
  // GenAI spans (OTel GenAI semconv) for the openai, anthropic, AWS Bedrock, Google GenAI, Mistral and Ollama SDKs (and
2
- // LiteLLM through its OpenAI-compatible proxy), LlamaIndex and the OpenAI Agents SDK (genai-agents.ts), and a
2
+ // LiteLLM through its OpenAI-compatible proxy), LlamaIndex and the OpenAI Agents SDK (genai-agents.ts), LangGraph.js,
3
+ // Mastra and the Vercel AI SDK agent loop (genai-frameworks.ts), and a
3
4
  // telemetry option for the Vercel AI SDK. Streams record time to first chunk, usage and tool calls (genai-stream.ts).
4
5
  // Prompt and completion text is never recorded.
5
6
  import { context, SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
6
7
  import { applyExtract, extract, tapStream } from './genai-stream.js';
7
8
  export { instrumentLlamaIndex, instrumentOpenAIAgents } from './genai-agents.js';
9
+ export { instrumentMastra, instrumentVercelAI, langchainCallbackHandler } from './genai-frameworks.js';
8
10
  const DONE = Symbol('wt.instrumented');
9
11
  const plain = (b) => (b || {});
10
12
  function wrap(target, method, system, req = plain) {
@@ -1,5 +1,8 @@
1
+ import * as wt from '../index.js';
2
+ /** Build a Next.js instrumentation `register` that passes `options` to `init`; no-op off the Node.js runtime or without a key. */
3
+ export declare function makeRegister(options?: wt.InitOptions): () => Promise<void>;
1
4
  /** Next.js instrumentation hook: init from WT_* env on the Node.js runtime; no-op without WT_INGEST_KEY. */
2
- export declare function register(): Promise<void>;
5
+ export declare const register: () => Promise<void>;
3
6
  /** Next.js onRequestError: server render, route handler and server action errors. */
4
7
  export declare function onRequestError(err: unknown, request?: {
5
8
  path?: string;
@@ -1,12 +1,17 @@
1
1
  // instrumentation.js: module.exports = require('@watchtowerobservability/node/next');
2
+ // or, with options: export const register = makeRegister({ redact }); export { onRequestError } from '@watchtowerobservability/node/next';
2
3
  import * as wt from '../index.js';
3
- /** Next.js instrumentation hook: init from WT_* env on the Node.js runtime; no-op without WT_INGEST_KEY. */
4
- export async function register() {
5
- const rt = process.env.NEXT_RUNTIME;
6
- if ((rt && rt !== 'nodejs') || !process.env.WT_INGEST_KEY)
7
- return;
8
- wt.init({});
4
+ /** Build a Next.js instrumentation `register` that passes `options` to `init`; no-op off the Node.js runtime or without a key. */
5
+ export function makeRegister(options = {}) {
6
+ return async function register() {
7
+ const rt = process.env.NEXT_RUNTIME;
8
+ if ((rt && rt !== 'nodejs') || !(options.apiKey || process.env.WT_INGEST_KEY))
9
+ return;
10
+ wt.init(options);
11
+ };
9
12
  }
13
+ /** Next.js instrumentation hook: init from WT_* env on the Node.js runtime; no-op without WT_INGEST_KEY. */
14
+ export const register = makeRegister();
10
15
  /** Next.js onRequestError: server render, route handler and server action errors. */
11
16
  export async function onRequestError(err, request, context) {
12
17
  const c = context || {};
@@ -1 +1,3 @@
1
1
  export declare function load(id: string): unknown;
2
+ /** Load an OpenTelemetry SDK package (an optional peer); a missing one throws an error naming what to install. */
3
+ export declare function need<T>(id: string): T;