@geekmidas/telescope 9.0.2 → 10.0.0-alpha.1

package/src/adapters/middy.ts

@@ -1,402 +0,0 @@
-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

@@ -1,181 +0,0 @@
-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

@@ -1,51 +0,0 @@
-/**
- * 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

@@ -1,34 +0,0 @@
-// 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';