@agentuity/telemetry 3.0.0-alpha.0

package/src/exporters/jsonl-metric-exporter.ts

@@ -0,0 +1,120 @@
+import { type ExportResult, ExportResultCode } from '@opentelemetry/core';
+import {
+	type PushMetricExporter,
+	type ResourceMetrics,
+	AggregationTemporality,
+	InstrumentType,
+} from '@opentelemetry/sdk-metrics';
+import { existsSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+/**
+ * JSONL implementation of the PushMetricExporter interface
+ * Writes metrics to a timestamped JSONL file
+ */
+export class JSONLMetricExporter implements PushMetricExporter {
+	private currentFile: string | null = null;
+	private readonly basePath: string;
+	private readonly filePrefix: string;
+
+	/**
+	 * Creates a new JSONL metric exporter
+	 * @param basePath - Directory to store the JSONL files
+	 */
+	constructor(basePath: string) {
+		this.basePath = basePath;
+		this.filePrefix = 'otel-metric';
+		this.ensureDirectory();
+	}
+
+	private ensureDirectory(): void {
+		if (!existsSync(this.basePath)) {
+			mkdirSync(this.basePath, { recursive: true });
+		}
+	}
+
+	private getOrCreateFile(): string {
+		// If current file exists, use it
+		if (this.currentFile && existsSync(this.currentFile)) {
+			return this.currentFile;
+		}
+
+		this.currentFile = join(
+			this.basePath,
+			`${this.filePrefix}-${Date.now()}.${randomUUID()}.jsonl`
+		);
+		return this.currentFile;
+	}
+
+	/**
+	 * Exports metrics to a JSONL file
+	 *
+	 * @param metrics - The resource metrics to export
+	 * @param resultCallback - Callback function to report the export result
+	 */
+	export(metrics: ResourceMetrics, resultCallback: (result: ExportResult) => void): void {
+		try {
+			const file = this.getOrCreateFile();
+
+			const record = {
+				resource: metrics.resource.attributes,
+				scopeMetrics: metrics.scopeMetrics.map((sm) => ({
+					scope: sm.scope,
+					metrics: sm.metrics.map((m) => ({
+						descriptor: m.descriptor,
+						dataPointType: m.dataPointType,
+						dataPoints: m.dataPoints,
+						aggregationTemporality: m.aggregationTemporality,
+					})),
+				})),
+			};
+
+			const line = JSON.stringify(record) + '\n';
+			try {
+				appendFileSync(file, line, 'utf-8');
+			} catch (err) {
+				// File may have been deleted, reset and retry once
+				const code = (err as NodeJS.ErrnoException).code;
+				if (code === 'ENOENT') {
+					this.currentFile = null;
+					const newFile = this.getOrCreateFile();
+					appendFileSync(newFile, line, 'utf-8');
+				} else {
+					throw err;
+				}
+			}
+
+			resultCallback({ code: ExportResultCode.SUCCESS });
+		} catch (error) {
+			resultCallback({
+				code: ExportResultCode.FAILED,
+				error: error instanceof Error ? error : new Error(String(error)),
+			});
+		}
+	}
+
+	/**
+	 * Shuts down the exporter
+	 *
+	 * @returns A promise that resolves when shutdown is complete
+	 */
+	async shutdown(): Promise<void> {
+		this.currentFile = null;
+	}
+
+	/**
+	 * Forces a flush of any pending data
+	 */
+	async forceFlush(): Promise<void> {
+		// No-op for file-based exporter as writes are synchronous
+	}
+
+	/**
+	 * Selects the aggregation temporality for the given instrument type
+	 */
+	selectAggregationTemporality?(_instrumentType: InstrumentType): AggregationTemporality {
+		// Default to cumulative temporality
+		return AggregationTemporality.CUMULATIVE;
+	}
+}

package/src/exporters/jsonl-trace-exporter.ts

@@ -0,0 +1,121 @@
+import { type ExportResult, ExportResultCode } from '@opentelemetry/core';
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+import { existsSync, appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+/**
+ * JSONL implementation of the SpanExporter interface
+ * Writes traces to a timestamped JSONL file
+ */
+export class JSONLTraceExporter implements SpanExporter {
+	private currentFile: string | null = null;
+	private readonly basePath: string;
+	private readonly filePrefix: string;
+
+	/**
+	 * Creates a new JSONL trace exporter
+	 * @param basePath - Directory to store the JSONL files
+	 */
+	constructor(basePath: string) {
+		this.basePath = basePath;
+		this.filePrefix = 'otel-trace';
+		this.ensureDirectory();
+	}
+
+	private ensureDirectory(): void {
+		if (!existsSync(this.basePath)) {
+			mkdirSync(this.basePath, { recursive: true });
+		}
+	}
+
+	private getOrCreateFile(): string {
+		// If current file exists, use it
+		if (this.currentFile && existsSync(this.currentFile)) {
+			return this.currentFile;
+		}
+
+		this.currentFile = join(
+			this.basePath,
+			`${this.filePrefix}-${Date.now()}.${randomUUID()}.jsonl`
+		);
+		return this.currentFile;
+	}
+
+	/**
+	 * Exports spans to a JSONL file
+	 *
+	 * @param spans - The spans to export
+	 * @param resultCallback - Callback function to report the export result
+	 */
+	export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void {
+		try {
+			if (spans.length === 0) {
+				resultCallback({ code: ExportResultCode.SUCCESS });
+				return;
+			}
+			const file = this.getOrCreateFile();
+			const lines: string[] = [];
+			for (const span of spans) {
+				const record = {
+					traceId: span.spanContext().traceId,
+					spanId: span.spanContext().spanId,
+					traceState: span.spanContext().traceState?.serialize(),
+					name: span.name,
+					kind: span.kind,
+					startTime: span.startTime,
+					endTime: span.endTime,
+					attributes: span.attributes,
+					status: span.status,
+					events: span.events,
+					links: span.links,
+					resource: span.resource.attributes,
+					droppedAttributesCount: span.droppedAttributesCount,
+					droppedEventsCount: span.droppedEventsCount,
+					droppedLinksCount: span.droppedLinksCount,
+					duration: span.duration,
+					ended: span.ended,
+				};
+
+				lines.push(JSON.stringify(record));
+			}
+			const payload = `${lines.join('\n')}\n`;
+			try {
+				appendFileSync(file, payload, 'utf-8');
+			} catch (err) {
+				// File may have been deleted, reset and retry once
+				const code = (err as NodeJS.ErrnoException).code;
+				if (code === 'ENOENT') {
+					this.currentFile = null;
+					const newFile = this.getOrCreateFile();
+					appendFileSync(newFile, payload, 'utf-8');
+				} else {
+					throw err;
+				}
+			}
+
+			resultCallback({ code: ExportResultCode.SUCCESS });
+		} catch (error) {
+			resultCallback({
+				code: ExportResultCode.FAILED,
+				error: error instanceof Error ? error : new Error(String(error)),
+			});
+		}
+	}
+
+	/**
+	 * Shuts down the exporter
+	 *
+	 * @returns A promise that resolves when shutdown is complete
+	 */
+	async shutdown(): Promise<void> {
+		this.currentFile = null;
+	}
+
+	/**
+	 * Forces a flush of any pending data
+	 */
+	async forceFlush(): Promise<void> {
+		// No-op for file-based exporter as writes are synchronous
+	}
+}

package/src/fetch.ts

@@ -0,0 +1,105 @@
+import { context, propagation, SpanStatusCode, trace } from '@opentelemetry/api';
+
+/**
+ * Reference to the original fetch function before instrumentation
+ */
+export const __originalFetch = fetch; // save the original fetch before we patch it
+
+/**
+ * Instruments the global fetch function with OpenTelemetry tracing
+ *
+ * Replaces the global fetch with an instrumented version that creates spans
+ * for each HTTP request and propagates trace context in headers
+ */
+export function instrumentFetch() {
+	const patch = async (
+		input: string | Request | URL,
+		init: RequestInit | undefined
+	): Promise<Response> => {
+		const url =
+			typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+
+		const method =
+			init?.method ||
+			(typeof input !== 'string' && !(input instanceof URL) ? input.method || 'GET' : 'GET');
+
+		// Get the active span if it exists
+		const activeSpan = trace.getActiveSpan();
+
+		// If there's no active span, just call the original fetch
+		if (!activeSpan) {
+			return __originalFetch(input, init);
+		}
+
+		// Get the current active context
+		const currentContext = context.active();
+		const _url = new URL(url);
+
+		// Create a child span using the current context
+		const childSpan = trace.getTracer('fetch').startSpan(
+			`${method} ${_url.pathname}`,
+			{
+				attributes: {
+					'http.url': url,
+					'http.path': _url.pathname,
+					'http.method': method,
+					host: _url.host,
+				},
+			},
+			currentContext
+		);
+
+		try {
+			// Prepare trace context injection
+			const carrier: Record<string, string> = {};
+
+			// Create a new context with the child span
+			const newContext = trace.setSpan(currentContext, childSpan);
+
+			// Use the new context for propagation
+			propagation.inject(newContext, carrier);
+
+			// Preserve original headers and add trace context
+			// Handle headers from both Request input and init parameter
+			const baseHeaders =
+				typeof input !== 'string' && !(input instanceof URL) && input instanceof Request
+					? input.headers
+					: undefined;
+			const headers = new Headers(baseHeaders ?? init?.headers ?? {});
+
+			// Add trace context headers (overwriting any already present)
+			for (const [key, value] of Object.entries(carrier)) {
+				headers.set(key, value);
+			}
+
+			// Create new init object with updated headers
+			const newInit = {
+				...init,
+				headers,
+			};
+
+			const response = await __originalFetch(input, newInit);
+
+			// Add response attributes to span
+			childSpan.setAttributes({
+				'http.status_code': response.status,
+				'http.user_agent': response.headers.get('user-agent') || '',
+			});
+
+			if (!response.ok) {
+				childSpan.setStatus({ code: SpanStatusCode.ERROR });
+			} else {
+				childSpan.setStatus({ code: SpanStatusCode.OK });
+			}
+
+			return response;
+		} catch (error) {
+			childSpan.recordException(error as Error);
+			childSpan.setStatus({ code: SpanStatusCode.ERROR });
+			throw error;
+		} finally {
+			childSpan.end();
+		}
+	};
+	globalThis.fetch = patch as typeof fetch;
+}

package/src/globals.ts

@@ -0,0 +1,18 @@
+/**
+ * Global state for Telemetry instance (survives hot reloads)
+ */
+
+import type { TelemetryResponse } from './telemetry';
+
+const telemetryInstanceKey = Symbol.for('@agentuity/telemetry:instance');
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const g = globalThis as any;
+
+export const telemetry = {
+	get: (): TelemetryResponse | undefined =>
+		g[telemetryInstanceKey] as TelemetryResponse | undefined,
+	set: (v: TelemetryResponse): void => {
+		g[telemetryInstanceKey] = v;
+	},
+};

package/src/http.ts

@@ -0,0 +1,53 @@
+import { context, propagation } from '@opentelemetry/api';
+
+/**
+ * Injects trace context into response headers using the OpenTelemetry propagation API
+ *
+ * @param headers - Optional existing headers to include
+ * @returns A record of headers with trace context injected
+ */
+export function injectTraceContextToHeaders(
+	headers: Record<string, string> | Headers = {}
+): Record<string, string> {
+	let _headers: Record<string, string>;
+	if (headers instanceof Headers) {
+		_headers = {};
+		headers.forEach((v, k) => {
+			_headers[k] = v;
+		});
+	} else {
+		_headers = { ...headers };
+	}
+	// Create a carrier object for the headers
+	const carrier: Record<string, string> = { ..._headers } as Record<string, string>;
+
+	// Get the current context
+	const currentContext = context.active();
+
+	// Inject trace context into the carrier
+	propagation.inject(currentContext, carrier);
+
+	return carrier;
+}
+
+/**
+ * Extracts trace context from Bun Request headers
+ *
+ * @param req - The Bun Request object
+ * @returns The context with trace information
+ */
+export function extractTraceContextFromRequest(
+	req: Request
+): ReturnType<typeof propagation.extract> {
+	// Create a carrier object from the headers
+	const carrier: Record<string, string> = {};
+
+	// Convert headers to the format expected by the propagator
+	req.headers.forEach((value, key) => {
+		carrier[key.toLowerCase()] = value;
+	});
+
+	// Extract the context using the global propagator
+	const activeContext = context.active();
+	return propagation.extract(activeContext, carrier);
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @agentuity/telemetry - OpenTelemetry telemetry for Agentuity
+ *
+ * Auto-initializes from environment variables on import (Vercel-style).
+ *
+ * @example Automatic initialization (recommended)
+ * ```typescript
+ * // Just import - auto-configures from AGENTUITY_* env vars
+ * import '@agentuity/telemetry';
+ *
+ * // Then access the globals anywhere
+ * import { tracer, logger, meter } from '@agentuity/telemetry';
+ * ```
+ *
+ * @example Explicit configuration
+ * ```typescript
+ * import { register } from '@agentuity/telemetry';
+ *
+ * register({
+ *   name: 'my-app',
+ *   version: '1.0.0',
+ *   // ... optional overrides
+ * });
+ * ```
+ */
+
+// Re-export types
+export type { Logger } from './logger';
+
+// Re-export console reference for custom loggers
+export { __originalConsole } from './logger';
+export type { TelemetryConfig, TelemetryResponse } from './telemetry';
+
+// Re-export HTTP utilities for trace context propagation
+export { injectTraceContextToHeaders, extractTraceContextFromRequest } from './http';
+
+// Re-export trace state utilities
+export {
+	enrichContextWithTraceState,
+	generateTraceId,
+	generateSpanId,
+	type TraceStateEntries,
+} from './tracestate';
+
+// Core registration function
+export { register, registerTelemetry, getTelemetry, ensureInitialized } from './telemetry';
+
+// Lazy-loaded exports - auto-initialized from env vars
+import type { Tracer, Meter } from '@opentelemetry/api';
+import type { Logger } from './logger';
+import { ensureInitialized } from './telemetry';
+
+/**
+ * Get the OpenTelemetry tracer (auto-initialized)
+ */
+export const tracer: Tracer = new Proxy({} as Tracer, {
+	get: (_, prop) => ensureInitialized().tracer[prop as keyof Tracer],
+});
+
+/**
+ * Get the OpenTelemetry meter (auto-initialized)
+ */
+export const meter: Meter = new Proxy({} as Meter, {
+	get: (_, prop) => ensureInitialized().meter[prop as keyof Meter],
+});
+
+/**
+ * Get the Logger instance (auto-initialized)
+ */
+export const logger: Logger = new Proxy({} as Logger, {
+	get: (_, prop) => ensureInitialized().logger[prop as keyof Logger],
+});
+
+/**
+ * Shutdown telemetry (call on process exit)
+ */
+export async function shutdown(): Promise<void> {
+	const telemetry = ensureInitialized();
+	if (telemetry?.shutdown) {
+		await telemetry.shutdown();
+	}
+}