@watchtowerobservability/node 0.0.0-stage → 0.2.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 (105) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +121 -2
  3. package/dist/cjs/buffer.d.ts +49 -0
  4. package/dist/cjs/buffer.js +134 -0
  5. package/dist/cjs/errors.d.ts +17 -0
  6. package/dist/cjs/errors.js +55 -0
  7. package/dist/cjs/index.d.ts +120 -0
  8. package/dist/cjs/index.js +302 -0
  9. package/dist/cjs/integrations/azure-functions.d.ts +18 -0
  10. package/dist/cjs/integrations/azure-functions.js +97 -0
  11. package/dist/cjs/integrations/express.d.ts +25 -0
  12. package/dist/cjs/integrations/express.js +58 -0
  13. package/dist/cjs/integrations/fastify.d.ts +6 -0
  14. package/dist/cjs/integrations/fastify.js +44 -0
  15. package/dist/cjs/integrations/genai-agents.d.ts +36 -0
  16. package/dist/cjs/integrations/genai-agents.js +124 -0
  17. package/dist/cjs/integrations/genai-stream.d.ts +19 -0
  18. package/dist/cjs/integrations/genai-stream.js +135 -0
  19. package/dist/cjs/integrations/genai.d.ts +18 -0
  20. package/dist/cjs/integrations/genai.js +150 -0
  21. package/dist/cjs/integrations/koa.d.ts +19 -0
  22. package/dist/cjs/integrations/koa.js +34 -0
  23. package/dist/cjs/integrations/lambda.d.ts +11 -0
  24. package/dist/cjs/integrations/lambda.js +68 -0
  25. package/dist/cjs/integrations/logs.d.ts +10 -0
  26. package/dist/cjs/integrations/logs.js +77 -0
  27. package/dist/cjs/integrations/nestjs.d.ts +16 -0
  28. package/dist/cjs/integrations/nestjs.js +30 -0
  29. package/dist/cjs/integrations/next.d.ts +11 -0
  30. package/dist/cjs/integrations/next.js +59 -0
  31. package/dist/cjs/integrations/prisma.d.ts +3 -0
  32. package/dist/cjs/integrations/prisma.js +33 -0
  33. package/dist/cjs/integrations/util.d.ts +9 -0
  34. package/dist/cjs/integrations/util.js +37 -0
  35. package/dist/cjs/jest.d.ts +21 -0
  36. package/dist/cjs/jest.js +45 -0
  37. package/dist/cjs/load.d.ts +1 -0
  38. package/dist/cjs/load.js +11 -0
  39. package/dist/cjs/metrics.d.ts +10 -0
  40. package/dist/cjs/metrics.js +81 -0
  41. package/dist/cjs/package.json +1 -0
  42. package/dist/cjs/payload.d.ts +42 -0
  43. package/dist/cjs/payload.js +145 -0
  44. package/dist/cjs/probes.d.ts +97 -0
  45. package/dist/cjs/probes.js +422 -0
  46. package/dist/cjs/profiling.d.ts +81 -0
  47. package/dist/cjs/profiling.js +253 -0
  48. package/dist/cjs/reporter-core.d.ts +32 -0
  49. package/dist/cjs/reporter-core.js +102 -0
  50. package/dist/cjs/test-plan.d.ts +93 -0
  51. package/dist/cjs/test-plan.js +262 -0
  52. package/dist/cjs/vitest.d.ts +27 -0
  53. package/dist/cjs/vitest.js +52 -0
  54. package/dist/esm/buffer.d.ts +49 -0
  55. package/dist/esm/buffer.js +92 -0
  56. package/dist/esm/errors.d.ts +17 -0
  57. package/dist/esm/errors.js +50 -0
  58. package/dist/esm/index.d.ts +120 -0
  59. package/dist/esm/index.js +251 -0
  60. package/dist/esm/integrations/azure-functions.d.ts +18 -0
  61. package/dist/esm/integrations/azure-functions.js +60 -0
  62. package/dist/esm/integrations/express.d.ts +25 -0
  63. package/dist/esm/integrations/express.js +54 -0
  64. package/dist/esm/integrations/fastify.d.ts +6 -0
  65. package/dist/esm/integrations/fastify.js +41 -0
  66. package/dist/esm/integrations/genai-agents.d.ts +36 -0
  67. package/dist/esm/integrations/genai-agents.js +118 -0
  68. package/dist/esm/integrations/genai-stream.d.ts +19 -0
  69. package/dist/esm/integrations/genai-stream.js +130 -0
  70. package/dist/esm/integrations/genai.d.ts +18 -0
  71. package/dist/esm/integrations/genai.js +138 -0
  72. package/dist/esm/integrations/koa.d.ts +19 -0
  73. package/dist/esm/integrations/koa.js +31 -0
  74. package/dist/esm/integrations/lambda.d.ts +11 -0
  75. package/dist/esm/integrations/lambda.js +32 -0
  76. package/dist/esm/integrations/logs.d.ts +10 -0
  77. package/dist/esm/integrations/logs.js +40 -0
  78. package/dist/esm/integrations/nestjs.d.ts +16 -0
  79. package/dist/esm/integrations/nestjs.js +26 -0
  80. package/dist/esm/integrations/next.d.ts +11 -0
  81. package/dist/esm/integrations/next.js +22 -0
  82. package/dist/esm/integrations/prisma.d.ts +3 -0
  83. package/dist/esm/integrations/prisma.js +30 -0
  84. package/dist/esm/integrations/util.d.ts +9 -0
  85. package/dist/esm/integrations/util.js +32 -0
  86. package/dist/esm/jest.d.ts +21 -0
  87. package/dist/esm/jest.js +41 -0
  88. package/dist/esm/load.d.ts +1 -0
  89. package/dist/esm/load.js +5 -0
  90. package/dist/esm/metrics.d.ts +10 -0
  91. package/dist/esm/metrics.js +44 -0
  92. package/dist/esm/package.json +1 -0
  93. package/dist/esm/payload.d.ts +42 -0
  94. package/dist/esm/payload.js +131 -0
  95. package/dist/esm/probes.d.ts +97 -0
  96. package/dist/esm/probes.js +412 -0
  97. package/dist/esm/profiling.d.ts +81 -0
  98. package/dist/esm/profiling.js +242 -0
  99. package/dist/esm/reporter-core.d.ts +32 -0
  100. package/dist/esm/reporter-core.js +63 -0
  101. package/dist/esm/test-plan.d.ts +93 -0
  102. package/dist/esm/test-plan.js +248 -0
  103. package/dist/esm/vitest.d.ts +27 -0
  104. package/dist/esm/vitest.js +48 -0
  105. package/package.json +219 -4
@@ -0,0 +1,251 @@
1
+ // Thin Watchtower layer over the OpenTelemetry Node SDK: key header, endpoint default,
2
+ // offline buffer, wt.*-safe resource attributes, redaction hook, getPrompt/score/evaluate/observe.
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';
11
+ import { SpoolExporter, spoolLogs } from './buffer.js';
12
+ import { startMetrics, switchOn } from './metrics.js';
13
+ import * as nodePath from 'node:path';
14
+ import { captureException, installProcessHandlers, dropReserved } from './errors.js';
15
+ import { loadCaptureRules } from './payload.js';
16
+ export { captureException, metrics, trace };
17
+ export { setCaptureRules, capturePayload } from './payload.js';
18
+ export const DEFAULT_ENDPOINT = 'http://localhost:4318';
19
+ const SEVERITY = { trace: 1, debug: 5, info: 9, warn: 13, error: 17, fatal: 21 };
20
+ /** Drop caller-supplied wt.* keys: tenant identity comes only from the key. */
21
+ export function safeResource(attrs) {
22
+ return dropReserved(attrs);
23
+ }
24
+ const errMessage = (e) => String(e?.message || e);
25
+ export class Client {
26
+ endpoint;
27
+ apiUrl;
28
+ project;
29
+ headers;
30
+ fetch;
31
+ redact;
32
+ provider;
33
+ tracer;
34
+ loggerProvider;
35
+ logger;
36
+ /** Set when metrics are on; `init` makes it the global meter provider (`metrics.getMeter`). */
37
+ meterProvider;
38
+ stopRuntime = () => { };
39
+ uninstall;
40
+ constructor(opts) {
41
+ const o = opts || {};
42
+ const env = process.env;
43
+ const apiKey = o.apiKey || env.WT_INGEST_KEY;
44
+ if (!apiKey)
45
+ throw new Error('apiKey is required (or set WT_INGEST_KEY)');
46
+ this.endpoint = (o.endpoint || env.WT_OTLP_ENDPOINT || DEFAULT_ENDPOINT).replace(/\/+$/, '');
47
+ this.apiUrl = (o.apiUrl || env.WT_API_URL || this.endpoint).replace(/\/+$/, '');
48
+ this.project = o.project || env.WT_PROJECT_ID;
49
+ this.headers = { Authorization: `Bearer ${apiKey}` };
50
+ this.fetch = o.fetch || globalThis.fetch;
51
+ const environment = o.environment || env.WT_ENVIRONMENT;
52
+ const release = o.release || env.WT_RELEASE;
53
+ const resource = new Resource({
54
+ 'service.name': o.serviceName || env.WT_SERVICE || 'app',
55
+ ...(environment ? { 'deployment.environment.name': environment } : {}),
56
+ ...(release ? { 'service.version': release } : {}),
57
+ ...safeResource(o.resource),
58
+ });
59
+ this.redact = o.redact;
60
+ this.provider = new NodeTracerProvider({ resource });
61
+ if (o.redact)
62
+ this.provider.addSpanProcessor(redactor(o.redact));
63
+ let exporter = o.exporter;
64
+ if (!exporter) {
65
+ const url = `${this.endpoint}/v1/traces`;
66
+ exporter = new OTLPTraceExporter({ url, headers: this.headers });
67
+ // spans and log records spool to their own subdirectories
68
+ if (o.bufferDir)
69
+ exporter = new SpoolExporter(exporter, nodePath.join(o.bufferDir, 'traces'), url, this.headers, this.fetch);
70
+ }
71
+ this.provider.addSpanProcessor(new BatchSpanProcessor(exporter));
72
+ this.tracer = this.provider.getTracer('watchtower');
73
+ this.loggerProvider = new LoggerProvider({ resource });
74
+ const logsOn = switchOn('WATCHTOWER_LOGS', 'OTEL_LOGS_EXPORTER', o.logs);
75
+ let logExporter = logsOn ? o.logExporter : undefined;
76
+ if (logsOn && !logExporter && !o.exporter) {
77
+ const url = `${this.endpoint}/v1/logs`;
78
+ logExporter = new OTLPLogExporter({ url, headers: this.headers });
79
+ if (o.bufferDir)
80
+ logExporter = spoolLogs(logExporter, nodePath.join(o.bufferDir, 'logs'), url, this.headers, this.fetch);
81
+ }
82
+ if (logExporter) {
83
+ this.loggerProvider.addLogRecordProcessor(o.logExporter ? new SimpleLogRecordProcessor(logExporter) : new BatchLogRecordProcessor(logExporter));
84
+ }
85
+ this.logger = this.loggerProvider.getLogger('watchtower');
86
+ // with a test span exporter only an explicit metric exporter is used, as for logs
87
+ if (switchOn('WATCHTOWER_METRICS', 'OTEL_METRICS_EXPORTER', o.metrics) && (o.metricExporter || !o.exporter)) {
88
+ const m = startMetrics(this.endpoint, this.headers, resource, o.bufferDir, this.fetch, o.metricExporter);
89
+ this.meterProvider = m.provider;
90
+ this.stopRuntime = m.stop;
91
+ }
92
+ if (o.captureRules ?? env.WT_CAPTURE_RULES === '1') {
93
+ void loadCaptureRules({ apiUrl: this.apiUrl, key: apiKey, service: String(resource.attributes['service.name']), fetch: this.fetch });
94
+ }
95
+ }
96
+ /** Emit an OTLP log record; trace and span ids come from the active context. */
97
+ log(level, body, attributes) {
98
+ let attrs = dropReserved(attributes);
99
+ const redact = this.redact;
100
+ if (redact)
101
+ attrs = Object.fromEntries(Object.entries(attrs).map(([k, v]) => [k, redact(k, v)]));
102
+ this.logger.emit({
103
+ severityNumber: SEVERITY[level] || SEVERITY.info,
104
+ severityText: String(level).toUpperCase(),
105
+ body,
106
+ attributes: attrs,
107
+ });
108
+ }
109
+ forceFlush() {
110
+ return Promise.all([this.provider.forceFlush(), this.loggerProvider.forceFlush(), this.meterProvider?.forceFlush()]);
111
+ }
112
+ // keep the key out of console.log / JSON.stringify
113
+ toJSON() {
114
+ return { endpoint: this.endpoint, project: this.project, headers: { Authorization: 'Bearer ****' } };
115
+ }
116
+ [inspect.custom]() {
117
+ return `Client ${JSON.stringify(this)}`;
118
+ }
119
+ async _call(method, path, body) {
120
+ const url = `${this.apiUrl}/v1/projects/${this.project}/llm/${path}`;
121
+ const res = await this.fetch(url, {
122
+ method,
123
+ headers: { ...this.headers, 'Content-Type': 'application/json' },
124
+ body: body === undefined ? undefined : JSON.stringify(body),
125
+ });
126
+ if (!res.ok)
127
+ throw new Error(`watchtower ${method} ${path}: HTTP ${res.status}`);
128
+ return res.json();
129
+ }
130
+ getPrompt(promptId) {
131
+ return this._call('GET', `prompts/${promptId}`);
132
+ }
133
+ score(traceId, value, o) {
134
+ const x = o || {};
135
+ const body = { trace_id: traceId, value, name: x.name || 'user_feedback', source: 'sdk' };
136
+ if (x.spanId)
137
+ body.span_id = x.spanId;
138
+ if (x.comment)
139
+ body.comment = x.comment;
140
+ return this._call('POST', 'scores', body);
141
+ }
142
+ /** Run task per case under a span; record each scorer result as a score when a project is set. */
143
+ async evaluate(dataset, task, scorers, o) {
144
+ const x = { name: 'evaluate', errorTolerance: true, ...o };
145
+ const rows = [];
146
+ // resume: rows of an earlier run; cases that finished without errors are kept, not re-run
147
+ const done = new Map((x.resume || []).filter((r) => !Object.keys(r.errors || {}).length).map((r) => [r.case, r]));
148
+ for (const [i, c] of dataset.entries()) {
149
+ const kept = done.get(i);
150
+ if (kept) {
151
+ rows.push(kept);
152
+ continue;
153
+ }
154
+ await this.tracer.startActiveSpan(`${x.name}.case`, async (span) => {
155
+ const traceId = span.spanContext().traceId;
156
+ const row = { case: i, traceId, scores: {}, errors: {} };
157
+ rows.push(row);
158
+ try {
159
+ const input = c !== null && c !== undefined ? c.input : undefined;
160
+ const out = await task(input !== undefined ? input : c);
161
+ for (const [name, fn] of Object.entries(scorers)) {
162
+ try {
163
+ row.scores[name] = await fn(c, out);
164
+ if (this.project)
165
+ await this.score(traceId, row.scores[name], { name });
166
+ }
167
+ catch (e) {
168
+ if (!x.errorTolerance)
169
+ throw e;
170
+ row.errors[name] = errMessage(e);
171
+ }
172
+ }
173
+ }
174
+ catch (e) {
175
+ if (!x.errorTolerance)
176
+ throw e;
177
+ row.errors.task = errMessage(e);
178
+ }
179
+ finally {
180
+ span.end();
181
+ }
182
+ });
183
+ }
184
+ return rows;
185
+ }
186
+ /** Re-run only the cases that errored or are missing in `previous`. */
187
+ evaluateResume(dataset, task, scorers, previous, o) {
188
+ return this.evaluate(dataset, task, scorers, { ...o, resume: previous });
189
+ }
190
+ /** Wrap fn in a span. */
191
+ observe(name, fn) {
192
+ return (...args) => this.tracer.startActiveSpan(name, (span) => {
193
+ const end = () => span.end();
194
+ try {
195
+ const r = fn(...args);
196
+ if (r && typeof r.then === 'function')
197
+ return r.finally(end);
198
+ end();
199
+ return r;
200
+ }
201
+ catch (e) {
202
+ end();
203
+ throw e;
204
+ }
205
+ });
206
+ }
207
+ shutdown() {
208
+ this.stopRuntime();
209
+ return Promise.all([this.provider.shutdown(), this.loggerProvider.shutdown(), this.meterProvider?.shutdown()]).then(() => undefined);
210
+ }
211
+ }
212
+ function redactor(hook) {
213
+ return {
214
+ onStart() { },
215
+ onEnd(span) {
216
+ for (const k of Object.keys(span.attributes))
217
+ span.attributes[k] = hook(k, span.attributes[k]);
218
+ },
219
+ shutdown: () => Promise.resolve(),
220
+ forceFlush: () => Promise.resolve(),
221
+ };
222
+ }
223
+ let current;
224
+ export function init(opts) {
225
+ if (current && current.uninstall)
226
+ current.uninstall();
227
+ const c = new Client(opts);
228
+ current = c;
229
+ c.provider.register(); // global tracer + async context so trace.getActiveSpan() works
230
+ if (c.meterProvider) {
231
+ metrics.disable(); // a re-init replaces the previous client's provider
232
+ metrics.setGlobalMeterProvider(c.meterProvider);
233
+ }
234
+ if ((opts || {}).captureProcessErrors !== false) {
235
+ c.uninstall = installProcessHandlers(() => c.forceFlush());
236
+ }
237
+ return c;
238
+ }
239
+ function need() {
240
+ if (!current)
241
+ throw new Error('watchtower.init() has not been called');
242
+ return current;
243
+ }
244
+ export const flush = () => (current ? current.forceFlush() : Promise.resolve());
245
+ export const log = (l, b, a) => need().log(l, b, a);
246
+ export const getPrompt = (id) => need().getPrompt(id);
247
+ export const score = (t, v, o) => need().score(t, v, o);
248
+ export const evaluate = (d, t, s, o) => need().evaluate(d, t, s, o);
249
+ export const evaluateResume = (d, t, s, prev, o) => need().evaluateResume(d, t, s, prev, o);
250
+ export const observe = (n, f) => need().observe(n, f);
251
+ export const shutdown = () => (current ? current.shutdown() : Promise.resolve());
@@ -0,0 +1,18 @@
1
+ /** The slice of the Azure Functions v4 InvocationContext this wrapper reads. */
2
+ export interface AzureContextLike {
3
+ invocationId?: string;
4
+ functionName?: string;
5
+ options?: {
6
+ trigger?: {
7
+ type?: string;
8
+ };
9
+ };
10
+ }
11
+ /** Maps an Azure binding type to the OTel `faas.trigger` value. */
12
+ export declare function faasTrigger(type: string | undefined): string;
13
+ /** app.http('fn', { handler: wrapFunction(async (request, context) => ...) }). One span per
14
+ * invocation with cold start, invocation id and trigger; errors captured; HTTP 5xx results mark the
15
+ * span failed; spans flushed before the host may freeze the worker. */
16
+ export declare function wrapFunction<T, R, C extends AzureContextLike = AzureContextLike>(handler: (trigger: T, context: C) => Promise<R>, o?: {
17
+ name?: string;
18
+ }): (trigger: T, context: C) => Promise<R>;
@@ -0,0 +1,60 @@
1
+ import { SpanKind, SpanStatusCode, trace } from '@opentelemetry/api';
2
+ import { captureException } from '../errors.js';
3
+ import * as wt from '../index.js';
4
+ const PUBSUB = ['serviceBusTrigger', 'eventHubTrigger', 'queueTrigger', 'eventGridTrigger', 'kafkaTrigger', 'rabbitMQTrigger'];
5
+ const DATASOURCE = ['blobTrigger', 'cosmosDBTrigger', 'sqlTrigger'];
6
+ /** Maps an Azure binding type to the OTel `faas.trigger` value. */
7
+ export function faasTrigger(type) {
8
+ if (type === 'httpTrigger')
9
+ return 'http';
10
+ if (type === 'timerTrigger')
11
+ return 'timer';
12
+ if (type && PUBSUB.includes(type))
13
+ return 'pubsub';
14
+ if (type && DATASOURCE.includes(type))
15
+ return 'datasource';
16
+ return 'other';
17
+ }
18
+ let cold = true;
19
+ /** app.http('fn', { handler: wrapFunction(async (request, context) => ...) }). One span per
20
+ * invocation with cold start, invocation id and trigger; errors captured; HTTP 5xx results mark the
21
+ * span failed; spans flushed before the host may freeze the worker. */
22
+ export function wrapFunction(handler, o) {
23
+ return async (input, context) => {
24
+ const c = context || {};
25
+ const coldstart = cold;
26
+ cold = false;
27
+ const kind = faasTrigger(c.options?.trigger?.type);
28
+ return trace.getTracer('watchtower').startActiveSpan(o?.name || c.functionName || 'function', {
29
+ kind: kind === 'http' ? SpanKind.SERVER : SpanKind.CONSUMER,
30
+ attributes: {
31
+ 'cloud.provider': 'azure',
32
+ 'cloud.platform': 'azure_functions',
33
+ 'faas.name': c.functionName,
34
+ 'faas.invocation_id': c.invocationId,
35
+ 'faas.trigger': kind,
36
+ 'faas.coldstart': coldstart,
37
+ },
38
+ }, async (span) => {
39
+ try {
40
+ const r = await handler(input, context);
41
+ const status = r?.status;
42
+ if (kind === 'http' && typeof status === 'number') {
43
+ span.setAttribute('http.response.status_code', status);
44
+ if (status >= 500)
45
+ span.setStatus({ code: SpanStatusCode.ERROR });
46
+ }
47
+ return r;
48
+ }
49
+ catch (e) {
50
+ span.setStatus({ code: SpanStatusCode.ERROR });
51
+ captureException(e, { handled: false, attributes: { 'error.mechanism': 'azure_functions' } });
52
+ throw e;
53
+ }
54
+ finally {
55
+ span.end();
56
+ await wt.flush().catch(() => { });
57
+ }
58
+ });
59
+ };
60
+ }
@@ -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;