@geekmidas/telescope 10.0.0-alpha.99 → 10.0.0

package/src/adapters/middy.ts

@@ -0,0 +1,402 @@
+import type { MiddlewareObj } from '@middy/core';
+import type {
+	APIGatewayProxyEvent,
+	APIGatewayProxyEventV2,
+	Context,
+} from 'aws-lambda';
+import { flushTelemetry } from '../instrumentation/core';
+import type { Telescope } from '../Telescope';
+
+/**
+ * Options for the Telescope Middy middleware
+ */
+export interface TelescopeMiddlewareOptions {
+	/**
+	 * Minimum remaining time (ms) before forcing a flush.
+	 * If remaining time drops below this, flush immediately.
+	 * @default 1000 (1 second)
+	 */
+	flushThresholdMs?: number;
+
+	/**
+	 * Whether to record request/response bodies
+	 * @default true
+	 */
+	recordBody?: boolean;
+
+	/**
+	 * Timeout for flush operation in ms
+	 * @default 5000
+	 */
+	flushTimeoutMs?: number;
+}
+
+// Track if we've registered the process hooks
+let processHooksRegistered = false;
+
+/**
+ * Register process-level hooks for telemetry flush.
+ * Called once per Lambda cold start.
+ */
+function registerProcessHooks(): void {
+	if (processHooksRegistered) return;
+	processHooksRegistered = true;
+
+	// Flush on SIGTERM (Lambda shutdown)
+	process.on('SIGTERM', async () => {
+		await flushTelemetry(5000).catch(() => {});
+	});
+
+	// Note: beforeExit doesn't work reliably in Lambda
+	// because Lambda freezes rather than exits
+}
+
+/**
+ * Extract request data from API Gateway event (v1 or v2)
+ */
+function extractRequestData(
+	event: APIGatewayProxyEvent | APIGatewayProxyEventV2,
+): {
+	method: string;
+	path: string;
+	url: string;
+	headers: Record<string, string>;
+	query: Record<string, string>;
+	body: unknown;
+	ip?: string;
+	requestId?: string;
+	requestSize?: number;
+} {
+	const headers: Record<string, string> = {};
+	if (event.headers) {
+		for (const [key, value] of Object.entries(event.headers)) {
+			if (value) headers[key.toLowerCase()] = value;
+		}
+	}
+
+	// Get request size from Content-Length header
+	const contentLength = headers['content-length'];
+	const requestSize = contentLength ? parseInt(contentLength, 10) : undefined;
+
+	// API Gateway v2 (HTTP API)
+	if ('rawPath' in event && event.requestContext?.http) {
+		const v2Event = event as APIGatewayProxyEventV2;
+		// Filter out undefined values from query parameters
+		const query: Record<string, string> = {};
+		if (v2Event.queryStringParameters) {
+			for (const [key, value] of Object.entries(
+				v2Event.queryStringParameters,
+			)) {
+				if (value !== undefined) {
+					query[key] = value;
+				}
+			}
+		}
+		return {
+			method: v2Event.requestContext.http.method,
+			path: v2Event.rawPath,
+			url:
+				v2Event.rawPath +
+				(v2Event.rawQueryString ? `?${v2Event.rawQueryString}` : ''),
+			headers,
+			query,
+			body: parseBody(v2Event.body, v2Event.isBase64Encoded),
+			ip: v2Event.requestContext.http.sourceIp,
+			requestId: v2Event.requestContext.requestId,
+			requestSize,
+		};
+	}
+
+	// API Gateway v1 (REST API)
+	const v1Event = event as APIGatewayProxyEvent;
+	const queryString = v1Event.queryStringParameters
+		? new URLSearchParams(
+				v1Event.queryStringParameters as Record<string, string>,
+			).toString()
+		: '';
+
+	return {
+		method: v1Event.httpMethod,
+		path: v1Event.path,
+		url: v1Event.path + (queryString ? `?${queryString}` : ''),
+		headers,
+		query: (v1Event.queryStringParameters as Record<string, string>) || {},
+		body: parseBody(v1Event.body, v1Event.isBase64Encoded),
+		ip: v1Event.requestContext?.identity?.sourceIp,
+		requestId: v1Event.requestContext?.requestId,
+		requestSize,
+	};
+}
+
+/**
+ * Parse request body
+ */
+function parseBody(
+	body: string | null | undefined,
+	isBase64Encoded?: boolean,
+): unknown {
+	if (!body) return undefined;
+
+	try {
+		const decoded = isBase64Encoded
+			? Buffer.from(body, 'base64').toString('utf-8')
+			: body;
+		return JSON.parse(decoded);
+	} catch {
+		return body;
+	}
+}
+
+/**
+ * Extract response data from Lambda response
+ */
+function extractResponseData(response: unknown): {
+	status: number;
+	headers: Record<string, string>;
+	body: unknown;
+	responseSize?: number;
+} {
+	if (response && typeof response === 'object' && 'statusCode' in response) {
+		const res = response as {
+			statusCode?: number;
+			headers?: Record<string, string>;
+			body?: string;
+		};
+		const headers = res.headers || {};
+		// Get response size from Content-Length header (case-insensitive)
+		const contentLengthKey = Object.keys(headers).find(
+			(k) => k.toLowerCase() === 'content-length',
+		);
+		const contentLengthValue = contentLengthKey
+			? headers[contentLengthKey]
+			: undefined;
+		// Prefer Content-Length header, fallback to body size
+		const responseSize = contentLengthValue
+			? parseInt(contentLengthValue, 10)
+			: res.body
+				? Buffer.byteLength(res.body, 'utf8')
+				: undefined;
+		return {
+			status: res.statusCode || 200,
+			headers,
+			body: res.body ? tryParseJson(res.body) : undefined,
+			responseSize,
+		};
+	}
+
+	return { status: 200, headers: {}, body: response };
+}
+
+function tryParseJson(str: string): unknown {
+	try {
+		return JSON.parse(str);
+	} catch {
+		return str;
+	}
+}
+
+/**
+ * Middy middleware that integrates Telescope with Lambda handlers.
+ *
+ * Features:
+ * - Records all requests and responses to Telescope
+ * - Captures exceptions automatically
+ * - Flushes telemetry before Lambda freezes
+ * - Uses Lambda context for smart flush timing
+ *
+ * @example
+ * ```typescript
+ * import middy from '@middy/core';
+ * import { telescopeMiddleware } from '@geekmidas/telescope/lambda';
+ *
+ * const handler = middy(baseHandler)
+ *   .use(telescopeMiddleware(telescope));
+ * ```
+ */
+export function telescopeMiddleware(
+	telescope: Telescope,
+	options: TelescopeMiddlewareOptions = {},
+): MiddlewareObj<
+	APIGatewayProxyEvent | APIGatewayProxyEventV2,
+	any,
+	Error,
+	Context
+> {
+	const {
+		flushThresholdMs = 1000,
+		recordBody = true,
+		flushTimeoutMs = 5000,
+	} = options;
+
+	// Register process hooks on first use
+	registerProcessHooks();
+
+	return {
+		before: async (request) => {
+			// Store start time for duration calculation
+			(request as any).__telescopeStartTime = Date.now();
+
+			// Don't wait for empty event loop - we'll flush manually
+			request.context.callbackWaitsForEmptyEventLoop = false;
+		},
+
+		after: async (request) => {
+			const startTime = (request as any).__telescopeStartTime || Date.now();
+			const duration = Date.now() - startTime;
+
+			try {
+				const reqData = extractRequestData(request.event);
+				const resData = extractResponseData(request.response);
+
+				await telescope.recordRequest({
+					method: reqData.method,
+					path: reqData.path,
+					url: reqData.url,
+					headers: reqData.headers,
+					query: reqData.query,
+					body: recordBody ? reqData.body : undefined,
+					ip: reqData.ip,
+					status: resData.status,
+					responseHeaders: resData.headers,
+					responseBody: recordBody ? resData.body : undefined,
+					duration,
+					requestSize: reqData.requestSize,
+					responseSize: resData.responseSize,
+				});
+			} catch {
+				// Don't let telescope errors break the response
+			}
+
+			// Smart flush: check remaining time
+			await smartFlush(request.context, flushThresholdMs, flushTimeoutMs);
+		},
+
+		onError: async (request) => {
+			const startTime = (request as any).__telescopeStartTime || Date.now();
+			const duration = Date.now() - startTime;
+
+			try {
+				// Record the exception
+				if (request.error) {
+					await telescope.exception(request.error);
+				}
+
+				// Also record the failed request
+				const reqData = extractRequestData(request.event);
+				await telescope.recordRequest({
+					method: reqData.method,
+					path: reqData.path,
+					url: reqData.url,
+					headers: reqData.headers,
+					query: reqData.query,
+					body: recordBody ? reqData.body : undefined,
+					ip: reqData.ip,
+					status: 500,
+					responseHeaders: {},
+					responseBody: { error: request.error?.message },
+					duration,
+					requestSize: reqData.requestSize,
+				});
+			} catch {
+				// Don't let telescope errors mask the original error
+			}
+
+			// Always flush on error
+			await smartFlush(request.context, flushThresholdMs, flushTimeoutMs);
+		},
+	};
+}
+
+/**
+ * Smart flush that respects Lambda's remaining execution time
+ */
+async function smartFlush(
+	context: Context,
+	thresholdMs: number,
+	timeoutMs: number,
+): Promise<void> {
+	const remaining = context.getRemainingTimeInMillis();
+
+	// If we have plenty of time, use normal timeout
+	// If time is running low, use a shorter timeout
+	const effectiveTimeout = Math.min(
+		timeoutMs,
+		Math.max(remaining - thresholdMs, 100), // Leave at least threshold ms for response
+	);
+
+	if (effectiveTimeout > 0) {
+		await flushTelemetry(effectiveTimeout).catch(() => {});
+	}
+}
+
+/**
+ * Create a wrapped Lambda handler with Telescope integration.
+ * Alternative to using Middy middleware directly.
+ *
+ * @example
+ * ```typescript
+ * import { createTelescopeHandler } from '@geekmidas/telescope/lambda';
+ *
+ * export const handler = createTelescopeHandler(telescope, async (event, context) => {
+ *   return { statusCode: 200, body: 'OK' };
+ * });
+ * ```
+ */
+export function createTelescopeHandler<TEvent, TResult>(
+	telescope: Telescope,
+	handler: (event: TEvent, context: Context) => Promise<TResult>,
+	options: TelescopeMiddlewareOptions = {},
+): (event: TEvent, context: Context) => Promise<TResult> {
+	const {
+		flushThresholdMs = 1000,
+		recordBody = true,
+		flushTimeoutMs = 5000,
+	} = options;
+
+	registerProcessHooks();
+
+	return async (event: TEvent, context: Context): Promise<TResult> => {
+		const startTime = Date.now();
+		context.callbackWaitsForEmptyEventLoop = false;
+
+		try {
+			const result = await handler(event, context);
+			const duration = Date.now() - startTime;
+
+			// Record successful request
+			try {
+				const reqData = extractRequestData(event as any);
+				const resData = extractResponseData(result);
+
+				await telescope.recordRequest({
+					method: reqData.method,
+					path: reqData.path,
+					url: reqData.url,
+					headers: reqData.headers,
+					query: reqData.query,
+					body: recordBody ? reqData.body : undefined,
+					ip: reqData.ip,
+					status: resData.status,
+					responseHeaders: resData.headers,
+					responseBody: recordBody ? resData.body : undefined,
+					duration,
+					requestSize: reqData.requestSize,
+					responseSize: resData.responseSize,
+				});
+			} catch {
+				// Ignore telescope errors
+			}
+
+			await smartFlush(context, flushThresholdMs, flushTimeoutMs);
+			return result;
+		} catch (error) {
+			// Record exception
+			if (error instanceof Error) {
+				await telescope.exception(error).catch(() => {});
+			}
+
+			await smartFlush(context, flushThresholdMs, flushTimeoutMs);
+			throw error;
+		}
+	};
+}

package/src/adapters/types.ts

@@ -0,0 +1,181 @@
+import type { Context as HonoContext } from 'hono';
+
+/**
+ * Environment types for adapter configuration
+ */
+export type TelescopeEnvironment = 'server' | 'lambda' | 'edge' | 'custom';
+
+/**
+ * Request context passed to adapters
+ */
+export interface AdapterRequestContext {
+	/** Unique request ID */
+	id: string;
+	/** HTTP method */
+	method: string;
+	/** Request path */
+	path: string;
+	/** Full URL */
+	url: string;
+	/** Request headers */
+	headers: Record<string, string>;
+	/** Query parameters */
+	query: Record<string, string>;
+	/** Request body (if recorded) */
+	body?: unknown;
+	/** Client IP address */
+	ip?: string;
+	/** Request start time */
+	startTime: number;
+	/** Request body size in bytes */
+	requestSize?: number;
+}
+
+/**
+ * Response context passed to adapters
+ */
+export interface AdapterResponseContext {
+	/** HTTP status code */
+	status: number;
+	/** Response headers */
+	headers: Record<string, string>;
+	/** Response body (if recorded) */
+	body?: unknown;
+	/** Request duration in milliseconds */
+	duration: number;
+	/** Response body size in bytes */
+	responseSize?: number;
+}
+
+/**
+ * Error context for exception handling
+ */
+export interface AdapterErrorContext {
+	/** The error that occurred */
+	error: Error;
+	/** Associated request ID */
+	requestId?: string;
+	/** Whether the error was handled */
+	handled: boolean;
+}
+
+/**
+ * Span processor strategy for telemetry export
+ */
+export type SpanProcessorStrategy = 'batch' | 'simple';
+
+/**
+ * Options for span processor configuration
+ */
+export interface SpanProcessorOptions {
+	/** Processor strategy (batch for servers, simple for Lambda) */
+	strategy: SpanProcessorStrategy;
+	/** Maximum queue size for batch processor (default: 2048) */
+	maxQueueSize?: number;
+	/** Scheduled delay for batch processor in ms (default: 5000) */
+	scheduledDelayMillis?: number;
+	/** Export timeout in ms (default: 30000) */
+	exportTimeoutMillis?: number;
+	/** Maximum export batch size (default: 512) */
+	maxExportBatchSize?: number;
+}
+
+/**
+ * Adapter lifecycle hooks
+ */
+export interface AdapterLifecycle {
+	/**
+	 * Called when the adapter is initialized
+	 */
+	onSetup?(): Promise<void> | void;
+
+	/**
+	 * Called before the adapter is destroyed
+	 */
+	onDestroy?(): Promise<void> | void;
+}
+
+/**
+ * Base adapter configuration
+ */
+export interface AdapterConfig {
+	/** Environment type */
+	environment: TelescopeEnvironment;
+	/** Span processor options */
+	spanProcessor?: SpanProcessorOptions;
+	/** Whether to auto-flush on response */
+	autoFlush?: boolean;
+}
+
+/**
+ * Interface for environment-specific adapters.
+ * Adapters handle the integration between Telescope core and the runtime environment.
+ */
+export interface TelescopeAdapter<TConfig extends AdapterConfig = AdapterConfig>
+	extends AdapterLifecycle {
+	/** Adapter configuration */
+	readonly config: TConfig;
+
+	/**
+	 * Extract request context from the runtime's request object.
+	 * This is called at the start of request processing.
+	 */
+	extractRequestContext(request: unknown): AdapterRequestContext;
+
+	/**
+	 * Extract response context from the runtime's response object.
+	 * This is called after the response is generated.
+	 */
+	extractResponseContext(
+		response: unknown,
+		startTime: number,
+	): AdapterResponseContext;
+
+	/**
+	 * Flush any pending telemetry data.
+	 * Critical for serverless environments where the process may be frozen.
+	 */
+	flush(): Promise<void>;
+}
+
+/**
+ * Hono-specific adapter configuration
+ */
+export interface HonoAdapterConfig extends AdapterConfig {
+	environment: 'server' | 'lambda' | 'edge';
+}
+
+/**
+ * Lambda-specific adapter configuration
+ */
+export interface LambdaAdapterConfig extends AdapterConfig {
+	environment: 'lambda';
+	/** Whether to detect Lambda resource attributes */
+	detectResource?: boolean;
+	/** Custom resource attributes */
+	resourceAttributes?: Record<string, string>;
+}
+
+/**
+ * Type helper for Hono context with Telescope
+ */
+export interface TelescopeHonoContext {
+	/** Request ID for correlation */
+	requestId: string;
+	/** Request start time */
+	startTime: number;
+}
+
+/**
+ * Hono context variables type
+ */
+export interface TelescopeHonoVariables {
+	telescope: TelescopeHonoContext;
+}
+
+/**
+ * Extended Hono context with Telescope variables
+ */
+export type HonoContextWithTelescope = HonoContext<{
+	Variables: TelescopeHonoVariables;
+}>;

package/src/core.ts

@@ -0,0 +1,51 @@
+/**
+ * Telescope Core
+ *
+ * Core types, interfaces, and utilities for Telescope.
+ * This module is environment-agnostic and can be used anywhere.
+ */
+
+// Adapter types and interfaces
+export type {
+	AdapterConfig,
+	AdapterErrorContext,
+	AdapterLifecycle,
+	AdapterRequestContext,
+	AdapterResponseContext,
+	HonoAdapterConfig,
+	HonoContextWithTelescope,
+	LambdaAdapterConfig,
+	SpanProcessorOptions,
+	SpanProcessorStrategy,
+	TelescopeAdapter,
+	TelescopeEnvironment,
+	TelescopeHonoContext,
+	TelescopeHonoVariables,
+} from './adapters/types';
+
+// Instrumentation core utilities
+export {
+	createSpanProcessor,
+	enableTelemetryDebug,
+	flushTelemetry,
+	getRecommendedStrategy,
+	isTelemetryInitialized,
+	NoopSpanProcessor,
+	setGlobalLogProcessor,
+	setGlobalSpanProcessor,
+	shutdownTelemetry,
+	withTelemetryFlush,
+} from './instrumentation/core';
+
+// Tracing utilities
+export {
+	addSpanEvent,
+	createSpan,
+	getActiveSpan,
+	getSpanId,
+	getTraceId,
+	recordException,
+	setSpanAttributes,
+	withSpan,
+	withSpanSync,
+} from './instrumentation/tracing';

package/src/index.ts

@@ -0,0 +1,34 @@
+// Core
+
+export type { MetricsAggregatorOptions } from './metrics';
+// Metrics
+export { MetricsAggregator } from './metrics';
+export type { InMemoryStorageOptions } from './storage/memory';
+// Storage
+export { InMemoryStorage } from './storage/memory';
+export { Telescope } from './Telescope';
+
+// Types
+export type {
+	EndpointBucket,
+	EndpointMetrics,
+	ExceptionEntry,
+	LogEntry,
+	MetricsBucket,
+	MetricsQueryOptions,
+	NormalizedTelescopeOptions,
+	QueryOptions,
+	RequestContext,
+	RequestEntry,
+	RequestMetrics,
+	SourceContext,
+	StackFrame,
+	StatusDistribution,
+	TelescopeEvent,
+	TelescopeEventType,
+	TelescopeOptions,
+	TelescopeStats,
+	TelescopeStorage,
+	TimeRange,
+	TimeSeriesPoint,
+} from './types';