@geekmidas/telescope 9.0.2 → 10.0.0-alpha.1

package/src/instrumentation/otel.ts

@@ -1,271 +0,0 @@
-/**
- * OpenTelemetry implementation of the Telemetry interface
- *
- * This provides automatic span creation for Lambda handlers using
- * OpenTelemetry. Works with any OTel-compatible backend (Jaeger, Zipkin,
- * Datadog, Honeycomb, etc.)
- */
-import { type Span, trace } from '@opentelemetry/api';
-import type { Context as LambdaContext } from 'aws-lambda';
-
-/**
- * Context object returned by onRequestStart, passed to subsequent hooks.
- * This matches the Telemetry interface from @geekmidas/constructs.
- */
-export interface TelemetryContext {
-	[key: string]: unknown;
-}
-
-/**
- * Request information passed to telemetry hooks.
- * This matches the Telemetry interface from @geekmidas/constructs.
- */
-export interface TelemetryRequest {
-	event: any;
-	context: LambdaContext;
-}
-
-/**
- * Response information passed to onRequestEnd.
- * This matches the Telemetry interface from @geekmidas/constructs.
- */
-export interface TelemetryResponse {
-	statusCode: number;
-	body?: string;
-	headers?: Record<string, string>;
-}
-
-/**
- * Telemetry interface for instrumenting endpoint requests.
- * This matches the Telemetry interface from @geekmidas/constructs.
- */
-export interface Telemetry {
-	onRequestStart(request: TelemetryRequest): TelemetryContext;
-	onRequestEnd(ctx: TelemetryContext, response: TelemetryResponse): void;
-	onRequestError(ctx: TelemetryContext, error: Error): void;
-}
-
-import {
-	createHttpServerSpan,
-	endHttpSpan,
-	extractTraceContext,
-	type HttpSpanAttributes,
-} from './http';
-
-/**
- * Options for OTelTelemetry
- */
-export interface OTelTelemetryOptions {
-	/**
-	 * 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 event
-	 */
-	getUserId?: (event: any) => string | undefined;
-
-	/**
-	 * Custom function to extract endpoint name from event
-	 */
-	getEndpointName?: (event: any) => string | undefined;
-
-	/**
-	 * Custom function to extract operation ID from event
-	 */
-	getOperationId?: (event: any) => string | undefined;
-}
-
-/**
- * Telemetry context with span reference
- */
-interface OTelContext extends TelemetryContext {
-	span: Span;
-	otelContext: any;
-}
-
-/**
- * OpenTelemetry implementation of the Telemetry interface
- *
- * @example
- * ```typescript
- * import { OTelTelemetry } from '@geekmidas/telescope/instrumentation';
- *
- * const adaptor = new AmazonApiGatewayV2Endpoint(envParser, endpoint, {
- *   telemetry: new OTelTelemetry(),
- * });
- * ```
- *
- * @example With options
- * ```typescript
- * const adaptor = new AmazonApiGatewayV2Endpoint(envParser, endpoint, {
- *   telemetry: new OTelTelemetry({
- *     recordBody: true,
- *     getUserId: (event) => event.requestContext?.authorizer?.userId,
- *   }),
- * });
- * ```
- */
-export class OTelTelemetry implements Telemetry {
-	constructor(private options: OTelTelemetryOptions = {}) {}
-
-	onRequestStart(request: TelemetryRequest): TelemetryContext {
-		const { event, context: lambdaContext } = request;
-
-		// Extract trace context from headers
-		const headers = normalizeHeaders(event.headers || {});
-		const parentContext = extractTraceContext(headers);
-
-		// Build span attributes from event
-		const attrs = this.buildSpanAttributes(event, lambdaContext);
-
-		// Create the span
-		const span = createHttpServerSpan(attrs, parentContext);
-		const otelContext = trace.setSpan(parentContext, span);
-
-		// Add Lambda-specific attributes
-		span.setAttribute('faas.invocation_id', lambdaContext.awsRequestId);
-		span.setAttribute('faas.name', lambdaContext.functionName);
-
-		// Record body if requested
-		if (this.options.recordBody && event.body) {
-			const bodyStr =
-				typeof event.body === 'string'
-					? event.body
-					: JSON.stringify(event.body);
-			span.setAttribute(
-				'http.request.body',
-				bodyStr.length > 4096 ? `${bodyStr.slice(0, 4096)}...` : bodyStr,
-			);
-		}
-
-		return { span, otelContext } as OTelContext;
-	}
-
-	onRequestEnd(ctx: TelemetryContext, response: TelemetryResponse): void {
-		const { span } = ctx as OTelContext;
-
-		if (this.options.recordResponseBody && response.body) {
-			span.setAttribute(
-				'http.response.body',
-				response.body.length > 4096
-					? `${response.body.slice(0, 4096)}...`
-					: response.body,
-			);
-		}
-
-		endHttpSpan(span, { statusCode: response.statusCode });
-	}
-
-	onRequestError(ctx: TelemetryContext, error: Error): void {
-		const { span } = ctx as OTelContext;
-		endHttpSpan(span, { statusCode: 500 }, error);
-	}
-
-	/**
-	 * Build span attributes from Lambda event
-	 */
-	private buildSpanAttributes(
-		event: any,
-		lambdaContext: any,
-	): HttpSpanAttributes {
-		// Detect event type (API Gateway v1, v2, ALB, or direct invoke)
-		const isV2 =
-			'requestContext' in event && 'http' in (event.requestContext || {});
-		const isV1 =
-			'requestContext' in event &&
-			'httpMethod' in event &&
-			!('http' in (event.requestContext || {}));
-
-		let method = 'INVOKE';
-		let path = '/';
-		let route: string | undefined;
-		let host: string | undefined;
-		let scheme: 'http' | 'https' | undefined;
-		let userAgent: string | undefined;
-		let clientIp: string | undefined;
-		let requestId: string | undefined;
-
-		if (isV2) {
-			// API Gateway v2 (HTTP API)
-			const http = event.requestContext.http;
-			method = http.method;
-			path = event.rawPath || http.path;
-			route = event.routeKey?.replace(/^[A-Z]+\s+/, ''); // Remove HTTP method prefix
-			host = event.headers?.host;
-			scheme = 'https';
-			userAgent = http.userAgent;
-			clientIp = http.sourceIp;
-			requestId = event.requestContext.requestId;
-		} else if (isV1) {
-			// API Gateway v1 (REST API)
-			method = event.httpMethod;
-			path = event.path;
-			route = event.resource;
-			host = event.headers?.Host || event.headers?.host;
-			scheme = 'https';
-			userAgent =
-				event.headers?.['User-Agent'] || event.headers?.['user-agent'];
-			clientIp = event.requestContext?.identity?.sourceIp;
-			requestId = event.requestContext?.requestId;
-		} else if ('httpMethod' in event) {
-			// ALB event
-			method = event.httpMethod;
-			path = event.path;
-			host = event.headers?.host;
-			userAgent =
-				event.headers?.['user-agent'] || event.headers?.['User-Agent'];
-			clientIp = event.headers?.['x-forwarded-for']?.split(',')[0]?.trim();
-		}
-
-		const attrs: HttpSpanAttributes = {
-			method,
-			path,
-			route,
-			host,
-			scheme,
-			userAgent,
-			clientIp,
-			requestId: requestId || lambdaContext.awsRequestId,
-		};
-
-		// Add endpoint metadata if extractors provided
-		if (this.options.getEndpointName || this.options.getOperationId) {
-			attrs.endpoint = {
-				name: this.options.getEndpointName?.(event),
-				operationId: this.options.getOperationId?.(event),
-			};
-		}
-
-		// Add user metadata if extractor provided
-		if (this.options.getUserId) {
-			const userId = this.options.getUserId(event);
-			if (userId) {
-				attrs.user = { userId };
-			}
-		}
-
-		return attrs;
-	}
-}
-
-/**
- * Normalize headers to lowercase keys
- */
-function normalizeHeaders(
-	headers: Record<string, string | string[] | undefined>,
-): Record<string, string | string[] | undefined> {
-	const normalized: Record<string, string | string[] | undefined> = {};
-	for (const [key, value] of Object.entries(headers)) {
-		normalized[key.toLowerCase()] = value;
-	}
-	return normalized;
-}

package/src/instrumentation/setup.ts

@@ -1,246 +0,0 @@
-import { DiagConsoleLogger, DiagLogLevel, diag } from '@opentelemetry/api';
-import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
-import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { PinoInstrumentation } from '@opentelemetry/instrumentation-pino';
-import { Resource } from '@opentelemetry/resources';
-import {
-	BatchLogRecordProcessor,
-	LoggerProvider,
-} from '@opentelemetry/sdk-logs';
-import { NodeSDK } from '@opentelemetry/sdk-node';
-import {
-	ConsoleSpanExporter,
-	type SpanExporter,
-} from '@opentelemetry/sdk-trace-node';
-import {
-	ATTR_SERVICE_NAME,
-	ATTR_SERVICE_VERSION,
-} from '@opentelemetry/semantic-conventions';
-import type { SpanProcessorStrategy } from '../adapters/types';
-import {
-	createSpanProcessor,
-	getRecommendedStrategy,
-	setGlobalLogProcessor,
-	setGlobalSpanProcessor,
-} from './core';
-
-/**
- * Options for configuring telemetry
- */
-export interface TelemetryOptions {
-	/**
-	 * Service name for resource identification
-	 */
-	serviceName: string;
-
-	/**
-	 * Service version
-	 */
-	serviceVersion?: string;
-
-	/**
-	 * OTLP endpoint URL (e.g., 'http://localhost:3000/__telescope/v1')
-	 * If not provided, traces will be logged to console
-	 */
-	endpoint?: string;
-
-	/**
-	 * Whether to instrument Pino for log correlation
-	 * @default true
-	 */
-	instrumentPino?: boolean;
-
-	/**
-	 * Whether to enable auto-instrumentation for common libraries
-	 * (http, fetch, express, etc.)
-	 * @default true
-	 */
-	autoInstrument?: boolean;
-
-	/**
-	 * Enable debug logging for OTel SDK
-	 * @default false
-	 */
-	debug?: boolean;
-
-	/**
-	 * Additional resource attributes
-	 */
-	resourceAttributes?: Record<string, string>;
-
-	/**
-	 * Headers to send with OTLP requests
-	 */
-	headers?: Record<string, string>;
-
-	/**
-	 * Span processor strategy.
-	 * - 'batch': Efficient batching for long-running servers (default)
-	 * - 'simple': Immediate export for serverless environments (Lambda, Edge)
-	 *
-	 * If not specified, automatically selected based on environment detection.
-	 */
-	spanProcessorStrategy?: SpanProcessorStrategy;
-
-	/**
-	 * Environment type for automatic configuration
-	 * @default 'server'
-	 */
-	environment?: 'server' | 'lambda' | 'edge' | 'custom';
-}
-
-let sdk: NodeSDK | null = null;
-
-/**
- * Set up OpenTelemetry instrumentation.
- * Call this BEFORE importing your application code.
- *
- * @example
- * ```typescript
- * // instrumentation.ts (create this file)
- * import { setupTelemetry } from '@geekmidas/telescope/instrumentation';
- *
- * setupTelemetry({
- *   serviceName: 'my-api',
- *   endpoint: 'http://localhost:3000/__telescope/v1',
- * });
- *
- * // Then in your entry point:
- * // import './instrumentation';
- * // import { app } from './app';
- * ```
- */
-export function setupTelemetry(options: TelemetryOptions): void {
-	if (sdk) {
-		return;
-	}
-
-	const {
-		serviceName,
-		serviceVersion = '1.0.0',
-		endpoint,
-		instrumentPino = true,
-		autoInstrument = true,
-		debug = false,
-		resourceAttributes = {},
-		headers = {},
-		spanProcessorStrategy,
-		environment = 'server',
-	} = options;
-
-	// Enable debug logging if requested
-	if (debug) {
-		diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
-	}
-
-	// Create resource
-	const resource = new Resource({
-		[ATTR_SERVICE_NAME]: serviceName,
-		[ATTR_SERVICE_VERSION]: serviceVersion,
-		...resourceAttributes,
-	});
-
-	// Build instrumentations list
-	const instrumentations = [];
-
-	// Add Pino instrumentation for log correlation
-	if (instrumentPino) {
-		instrumentations.push(
-			new PinoInstrumentation({
-				// Inject trace context into log records
-				logHook: (span, record) => {
-					record.trace_id = span.spanContext().traceId;
-					record.span_id = span.spanContext().spanId;
-					record.trace_flags = span.spanContext().traceFlags;
-				},
-			}),
-		);
-	}
-
-	// Add auto-instrumentations for common libraries
-	if (autoInstrument) {
-		instrumentations.push(
-			getNodeAutoInstrumentations({
-				// Disable file system instrumentation (too noisy)
-				'@opentelemetry/instrumentation-fs': { enabled: false },
-				// Configure HTTP instrumentation
-				'@opentelemetry/instrumentation-http': {
-					ignoreIncomingRequestHook: (request) => {
-						// Ignore health checks and internal routes
-						const path = request.url || '';
-						return (
-							path.includes('/__health') ||
-							path.includes('/__telescope') ||
-							path.includes('/favicon')
-						);
-					},
-				},
-			}),
-		);
-	}
-
-	// Create exporters
-	let traceExporter: SpanExporter;
-	if (endpoint) {
-		traceExporter = new OTLPTraceExporter({
-			url: `${endpoint}/traces`,
-			headers,
-		});
-	} else {
-		// Fall back to console exporter for debugging
-		traceExporter = new ConsoleSpanExporter();
-	}
-
-	// Determine span processor strategy
-	const strategy = spanProcessorStrategy ?? getRecommendedStrategy(environment);
-	const spanProcessor = createSpanProcessor(traceExporter, { strategy });
-
-	// Register globally for flush operations
-	setGlobalSpanProcessor(spanProcessor);
-
-	// Create and configure SDK
-	sdk = new NodeSDK({
-		resource,
-		traceExporter,
-		spanProcessors: [spanProcessor],
-		instrumentations,
-	});
-
-	// Set up log exporter if endpoint is provided
-	if (endpoint) {
-		const logExporter = new OTLPLogExporter({
-			url: `${endpoint}/logs`,
-			headers,
-		});
-
-		const loggerProvider = new LoggerProvider({ resource });
-		const logProcessor = new BatchLogRecordProcessor(logExporter);
-		loggerProvider.addLogRecordProcessor(logProcessor);
-
-		// Register for flush operations
-		setGlobalLogProcessor(logProcessor);
-	}
-
-	// Start the SDK
-	sdk.start();
-
-	// Graceful shutdown
-	process.on('SIGTERM', () => {
-		sdk
-			?.shutdown()
-			.then(() => {})
-			.catch((_error) => {})
-			.finally(() => process.exit(0));
-	});
-}
-
-/**
- * Shut down telemetry (for testing or graceful shutdown)
- */
-export async function shutdownTelemetry(): Promise<void> {
-	if (sdk) {
-		await sdk.shutdown();
-		sdk = null;
-	}
-}

package/src/instrumentation/tracing.ts

@@ -1,145 +0,0 @@
-import {
-	type Attributes,
-	context,
-	type Span,
-	SpanStatusCode,
-	trace,
-} from '@opentelemetry/api';
-
-/**
- * Get the currently active span
- */
-export function getActiveSpan(): Span | undefined {
-	return trace.getActiveSpan();
-}
-
-/**
- * Set attributes on the active span
- */
-export function setSpanAttributes(attributes: Attributes): void {
-	const span = getActiveSpan();
-	if (span) {
-		span.setAttributes(attributes);
-	}
-}
-
-/**
- * Create a new span as a child of the current span
- */
-export function createSpan(name: string, attributes?: Attributes): Span {
-	const tracer = trace.getTracer('@geekmidas/telescope');
-	const span = tracer.startSpan(name, { attributes });
-	return span;
-}
-
-/**
- * Execute a function within a new span context
- *
- * @example
- * ```typescript
- * const result = await withSpan('processOrder', async (span) => {
- *   span.setAttribute('order.id', orderId);
- *   const order = await processOrder(orderId);
- *   return order;
- * });
- * ```
- */
-export async function withSpan<T>(
-	name: string,
-	fn: (span: Span) => Promise<T>,
-	attributes?: Attributes,
-): Promise<T> {
-	const tracer = trace.getTracer('@geekmidas/telescope');
-	const span = tracer.startSpan(name, { attributes });
-
-	try {
-		const result = await context.with(
-			trace.setSpan(context.active(), span),
-			() => fn(span),
-		);
-		span.setStatus({ code: SpanStatusCode.OK });
-		return result;
-	} catch (error) {
-		span.setStatus({
-			code: SpanStatusCode.ERROR,
-			message: error instanceof Error ? error.message : 'Unknown error',
-		});
-		span.recordException(
-			error instanceof Error ? error : new Error(String(error)),
-		);
-		throw error;
-	} finally {
-		span.end();
-	}
-}
-
-/**
- * Synchronous version of withSpan
- */
-export function withSpanSync<T>(
-	name: string,
-	fn: (span: Span) => T,
-	attributes?: Attributes,
-): T {
-	const tracer = trace.getTracer('@geekmidas/telescope');
-	const span = tracer.startSpan(name, { attributes });
-
-	try {
-		const result = context.with(trace.setSpan(context.active(), span), () =>
-			fn(span),
-		);
-		span.setStatus({ code: SpanStatusCode.OK });
-		return result;
-	} catch (error) {
-		span.setStatus({
-			code: SpanStatusCode.ERROR,
-			message: error instanceof Error ? error.message : 'Unknown error',
-		});
-		span.recordException(
-			error instanceof Error ? error : new Error(String(error)),
-		);
-		throw error;
-	} finally {
-		span.end();
-	}
-}
-
-/**
- * Get the current trace ID (useful for log correlation)
- */
-export function getTraceId(): string | undefined {
-	const span = getActiveSpan();
-	return span?.spanContext().traceId;
-}
-
-/**
- * Get the current span ID
- */
-export function getSpanId(): string | undefined {
-	const span = getActiveSpan();
-	return span?.spanContext().spanId;
-}
-
-/**
- * Record an exception on the current span
- */
-export function recordException(error: Error): void {
-	const span = getActiveSpan();
-	if (span) {
-		span.recordException(error);
-		span.setStatus({
-			code: SpanStatusCode.ERROR,
-			message: error.message,
-		});
-	}
-}
-
-/**
- * Add an event to the current span
- */
-export function addSpanEvent(name: string, attributes?: Attributes): void {
-	const span = getActiveSpan();
-	if (span) {
-		span.addEvent(name, attributes);
-	}
-}