@geekmidas/telescope 1.1.1 → 10.0.0-alpha.0

package/src/instrumentation/core.ts

@@ -1,228 +0,0 @@
-import { DiagConsoleLogger, DiagLogLevel, diag } from '@opentelemetry/api';
-import {
-	BatchSpanProcessor,
-	type ReadableSpan,
-	SimpleSpanProcessor,
-	type Span,
-	type SpanExporter,
-	type SpanProcessor,
-} from '@opentelemetry/sdk-trace-base';
-import type {
-	SpanProcessorOptions,
-	SpanProcessorStrategy,
-} from '../adapters/types';
-
-/**
- * Global telemetry state for flush operations
- */
-interface TelemetryState {
-	spanProcessor: SpanProcessor | null;
-	logProcessor: unknown | null;
-	initialized: boolean;
-}
-
-const state: TelemetryState = {
-	spanProcessor: null,
-	logProcessor: null,
-	initialized: false,
-};
-
-/**
- * Create a span processor based on the strategy
- */
-export function createSpanProcessor(
-	exporter: SpanExporter,
-	options: SpanProcessorOptions,
-): SpanProcessor {
-	const { strategy, ...config } = options;
-
-	if (strategy === 'simple') {
-		return new SimpleSpanProcessor(exporter);
-	}
-
-	return new BatchSpanProcessor(exporter, {
-		maxQueueSize: config.maxQueueSize ?? 2048,
-		scheduledDelayMillis: config.scheduledDelayMillis ?? 5000,
-		exportTimeoutMillis: config.exportTimeoutMillis ?? 30000,
-		maxExportBatchSize: config.maxExportBatchSize ?? 512,
-	});
-}
-
-/**
- * Get the recommended span processor strategy for an environment
- */
-export function getRecommendedStrategy(
-	environment: 'server' | 'lambda' | 'edge' | 'custom',
-): SpanProcessorStrategy {
-	switch (environment) {
-		case 'lambda':
-		case 'edge':
-			// Use simple processor for serverless - immediate export
-			return 'simple';
-		default:
-			// Use batch processor for long-running servers - efficient batching
-			return 'batch';
-	}
-}
-
-/**
- * Set the global span processor for flush operations
- */
-export function setGlobalSpanProcessor(processor: SpanProcessor): void {
-	state.spanProcessor = processor;
-	state.initialized = true;
-}
-
-/**
- * Set the global log processor for flush operations
- */
-export function setGlobalLogProcessor(processor: unknown): void {
-	state.logProcessor = processor;
-}
-
-/**
- * Check if telemetry is initialized
- */
-export function isTelemetryInitialized(): boolean {
-	return state.initialized;
-}
-
-/**
- * Flush all pending telemetry data.
- * This is critical for serverless environments where the process may freeze.
- *
- * @example
- * ```typescript
- * // In a Lambda handler
- * export const handler = async (event, context) => {
- *   try {
- *     const result = await processRequest(event);
- *     return result;
- *   } finally {
- *     // Flush before Lambda freezes
- *     await flushTelemetry();
- *   }
- * };
- * ```
- */
-export async function flushTelemetry(timeoutMs = 30000): Promise<void> {
-	const promises: Promise<void>[] = [];
-
-	// Flush span processor
-	if (state.spanProcessor) {
-		promises.push(
-			Promise.race([
-				state.spanProcessor.forceFlush(),
-				new Promise<void>((_, reject) =>
-					setTimeout(() => reject(new Error('Span flush timeout')), timeoutMs),
-				),
-			]).catch((error) => {
-				if (diag.debug) {
-					diag.debug(`Span flush error: ${error.message}`);
-				}
-			}),
-		);
-	}
-
-	// Flush log processor if it has forceFlush method
-	if (
-		state.logProcessor &&
-		typeof (state.logProcessor as { forceFlush?: () => Promise<void> })
-			.forceFlush === 'function'
-	) {
-		promises.push(
-			Promise.race([
-				(
-					state.logProcessor as { forceFlush: () => Promise<void> }
-				).forceFlush(),
-				new Promise<void>((_, reject) =>
-					setTimeout(() => reject(new Error('Log flush timeout')), timeoutMs),
-				),
-			]).catch((error) => {
-				if (diag.debug) {
-					diag.debug(`Log flush error: ${error.message}`);
-				}
-			}),
-		);
-	}
-
-	await Promise.all(promises);
-}
-
-/**
- * Shutdown all telemetry processors
- */
-export async function shutdownTelemetry(): Promise<void> {
-	const promises: Promise<void>[] = [];
-
-	if (state.spanProcessor) {
-		promises.push(state.spanProcessor.shutdown());
-		state.spanProcessor = null;
-	}
-
-	if (
-		state.logProcessor &&
-		typeof (state.logProcessor as { shutdown?: () => Promise<void> })
-			.shutdown === 'function'
-	) {
-		promises.push(
-			(state.logProcessor as { shutdown: () => Promise<void> }).shutdown(),
-		);
-		state.logProcessor = null;
-	}
-
-	state.initialized = false;
-	await Promise.all(promises);
-}
-
-/**
- * Enable debug logging for telemetry
- */
-export function enableTelemetryDebug(): void {
-	diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
-}
-
-/**
- * Wraps a handler function to ensure telemetry is flushed before returning.
- * Useful for Lambda handlers.
- *
- * @example
- * ```typescript
- * export const handler = withTelemetryFlush(async (event, context) => {
- *   // Your Lambda logic here
- *   return { statusCode: 200, body: 'OK' };
- * });
- * ```
- */
-export function withTelemetryFlush<TEvent, TResult>(
-	handler: (event: TEvent, context: unknown) => Promise<TResult>,
-): (event: TEvent, context: unknown) => Promise<TResult> {
-	return async (event: TEvent, context: unknown): Promise<TResult> => {
-		try {
-			return await handler(event, context);
-		} finally {
-			await flushTelemetry();
-		}
-	};
-}
-
-/**
- * Noop span processor for testing or when telemetry is disabled
- */
-export class NoopSpanProcessor implements SpanProcessor {
-	forceFlush(): Promise<void> {
-		return Promise.resolve();
-	}
-
-	onStart(_span: Span): void {
-		// noop
-	}
-
-	onEnd(_span: ReadableSpan): void {
-		// noop
-	}
-
-	shutdown(): Promise<void> {
-		return Promise.resolve();
-	}
-}

package/src/instrumentation/hono.ts

@@ -1,270 +0,0 @@
-import { context, type Span, trace } from '@opentelemetry/api';
-/**
- * OpenTelemetry instrumentation middleware for Hono
- *
- * This middleware automatically creates spans for HTTP requests,
- * extracts trace context from incoming headers, and records
- * request/response metadata as span attributes.
- */
-import type { Context, MiddlewareHandler } from 'hono';
-import {
-	createHttpServerSpan,
-	endHttpSpan,
-	extractTraceContext,
-	type HttpSpanAttributes,
-} from './http';
-
-/**
- * Options for the Hono telemetry middleware
- */
-export interface HonoTelemetryMiddlewareOptions {
-	/**
-	 * Whether to record request body as span attribute
-	 * @default false
-	 */
-	recordBody?: boolean;
-
-	/**
-	 * Whether to record response body as span attribute
-	 * @default false
-	 */
-	recordResponseBody?: boolean;
-
-	/**
-	 * Custom function to extract user ID from context
-	 */
-	getUserId?: (c: Context) => string | undefined;
-
-	/**
-	 * Paths to skip tracing (supports wildcards)
-	 */
-	ignorePaths?: string[];
-
-	/**
-	 * Whether to skip tracing for this request
-	 */
-	shouldSkip?: (c: Context) => boolean;
-}
-
-// Key for storing span on context
-const SPAN_KEY = 'telemetry.span';
-const CONTEXT_KEY = 'telemetry.context';
-
-/**
- * Get the current span from Hono context
- */
-export function getSpanFromContext(c: Context): Span | undefined {
-	return c.get(SPAN_KEY);
-}
-
-/**
- * Get the current trace context from Hono context
- */
-export function getTraceContextFromHono(c: Context): any {
-	return c.get(CONTEXT_KEY);
-}
-
-/**
- * Create a telemetry middleware for Hono applications
- *
- * @example
- * ```typescript
- * import { honoTelemetryMiddleware } from '@geekmidas/telescope/instrumentation';
- *
- * const app = new Hono();
- * app.use('*', honoTelemetryMiddleware());
- * ```
- */
-export function honoTelemetryMiddleware(
-	options: HonoTelemetryMiddlewareOptions = {},
-): MiddlewareHandler {
-	return async (c, next) => {
-		// Check if path should be ignored
-		if (
-			options.ignorePaths &&
-			shouldIgnorePath(c.req.path, options.ignorePaths)
-		) {
-			return next();
-		}
-
-		// Skip if custom skip function returns true
-		if (options.shouldSkip?.(c)) {
-			return next();
-		}
-
-		// Extract trace context from headers
-		const headers: Record<string, string | string[] | undefined> = {};
-		c.req.raw.headers.forEach((value, key) => {
-			headers[key] = value;
-		});
-		const parentContext = extractTraceContext(headers);
-
-		// Build span attributes from request
-		const attrs = buildHonoSpanAttributes(c, options);
-
-		// Create the span
-		const span = createHttpServerSpan(attrs, parentContext);
-		const spanContext = trace.setSpan(parentContext, span);
-
-		// Store span and context on Hono context
-		c.set(SPAN_KEY, span);
-		c.set(CONTEXT_KEY, spanContext);
-
-		// Record body if requested
-		if (options.recordBody) {
-			try {
-				const body = await c.req.text();
-				if (body) {
-					span.setAttribute(
-						'http.request.body',
-						body.length > 4096 ? `${body.slice(0, 4096)}...` : body,
-					);
-				}
-			} catch {
-				// Body may have already been consumed
-			}
-		}
-
-		try {
-			// Execute the rest of the middleware chain within span context
-			await context.with(spanContext, async () => {
-				await next();
-			});
-
-			// Record response
-			const statusCode = c.res.status;
-
-			if (options.recordResponseBody) {
-				try {
-					const body = await c.res.clone().text();
-					if (body) {
-						span.setAttribute(
-							'http.response.body',
-							body.length > 4096 ? `${body.slice(0, 4096)}...` : body,
-						);
-					}
-				} catch {
-					// Response body may not be available
-				}
-			}
-
-			endHttpSpan(span, { statusCode });
-		} catch (error) {
-			endHttpSpan(
-				span,
-				{ statusCode: 500 },
-				error instanceof Error ? error : new Error(String(error)),
-			);
-			throw error;
-		}
-	};
-}
-
-/**
- * Build span attributes from Hono context
- */
-function buildHonoSpanAttributes(
-	c: Context,
-	options: HonoTelemetryMiddlewareOptions,
-): HttpSpanAttributes {
-	const req = c.req;
-	const url = new URL(req.url);
-
-	// Use actual path for route unless it's a specific route pattern
-	const routePath = c.req.routePath;
-	const route =
-		routePath && routePath !== '*' && !routePath.includes('/*')
-			? routePath
-			: url.pathname;
-
-	const attrs: HttpSpanAttributes = {
-		method: req.method,
-		url: req.url,
-		path: url.pathname,
-		route,
-		host: url.host,
-		scheme: url.protocol.replace(':', '') as 'http' | 'https',
-		userAgent: req.header('user-agent'),
-		clientIp: getClientIp(c),
-		requestId: req.header('x-request-id') || req.header('x-amzn-requestid'),
-	};
-
-	// Add user metadata if extractor provided
-	if (options.getUserId) {
-		const userId = options.getUserId(c);
-		if (userId) {
-			attrs.user = { userId };
-		}
-	}
-
-	return attrs;
-}
-
-/**
- * Extract client IP from Hono context
- */
-function getClientIp(c: Context): string | undefined {
-	// Try various headers in order of preference
-	const xForwardedFor = c.req.header('x-forwarded-for');
-	if (xForwardedFor) {
-		const first = xForwardedFor.split(',')[0];
-		return first?.trim();
-	}
-
-	const xRealIp = c.req.header('x-real-ip');
-	if (xRealIp) {
-		return xRealIp;
-	}
-
-	// Try CF-Connecting-IP (Cloudflare)
-	const cfConnectingIp = c.req.header('cf-connecting-ip');
-	if (cfConnectingIp) {
-		return cfConnectingIp;
-	}
-
-	return undefined;
-}
-
-/**
- * Check if path should be ignored
- */
-function shouldIgnorePath(path: string, ignorePaths: string[]): boolean {
-	for (const pattern of ignorePaths) {
-		if (pattern.endsWith('*')) {
-			// Wildcard match
-			const prefix = pattern.slice(0, -1);
-			if (path.startsWith(prefix)) {
-				return true;
-			}
-		} else if (path === pattern) {
-			// Exact match
-			return true;
-		}
-	}
-	return false;
-}
-
-/**
- * Run a function within the span context from Hono context
- *
- * @example
- * ```typescript
- * app.get('/api/users', async (c) => {
- *   return withHonoSpanContext(c, async () => {
- *     // Any spans created here will be children of the request span
- *     const users = await fetchUsers();
- *     return c.json(users);
- *   });
- * });
- * ```
- */
-export async function withHonoSpanContext<T>(
-	c: Context,
-	fn: () => Promise<T>,
-): Promise<T> {
-	const ctx = getTraceContextFromHono(c);
-	if (!ctx) {
-		return fn();
-	}
-	return context.with(ctx, fn);
-}