@geekmidas/telescope 1.1.1 → 10.0.0-alpha.0

package/src/instrumentation/http.ts

@@ -1,306 +0,0 @@
-import {
-	type Attributes,
-	type Context,
-	context,
-	propagation,
-	type Span,
-	SpanKind,
-	SpanStatusCode,
-	trace,
-} from '@opentelemetry/api';
-
-/**
- * HTTP request attributes following OpenTelemetry semantic conventions
- */
-export interface HttpRequestAttributes {
-	method: string;
-	url?: string;
-	path?: string;
-	route?: string;
-	host?: string;
-	scheme?: 'http' | 'https';
-	userAgent?: string;
-	clientIp?: string;
-	requestId?: string;
-}
-
-/**
- * HTTP response attributes
- */
-export interface HttpResponseAttributes {
-	statusCode: number;
-	responseSize?: number;
-}
-
-/**
- * Endpoint-specific attributes
- */
-export interface EndpointAttributes {
-	name?: string;
-	operationId?: string;
-	tags?: string[];
-}
-
-/**
- * User/session attributes
- */
-export interface UserAttributes {
-	userId?: string;
-	sessionId?: string;
-	roles?: string[];
-}
-
-/**
- * Full span attributes for HTTP requests
- */
-export interface HttpSpanAttributes extends HttpRequestAttributes {
-	response?: HttpResponseAttributes;
-	endpoint?: EndpointAttributes;
-	user?: UserAttributes;
-	custom?: Attributes;
-}
-
-const TRACER_NAME = '@geekmidas/constructs';
-
-/**
- * Get or create a tracer for constructs instrumentation
- */
-export function getConstructsTracer() {
-	return trace.getTracer(TRACER_NAME);
-}
-
-/**
- * Convert HTTP attributes to OpenTelemetry semantic conventions
- */
-export function toOtelAttributes(attrs: HttpSpanAttributes): Attributes {
-	const otelAttrs: Attributes = {};
-
-	// HTTP request attributes (OpenTelemetry semantic conventions)
-	if (attrs.method) otelAttrs['http.request.method'] = attrs.method;
-	if (attrs.url) otelAttrs['url.full'] = attrs.url;
-	if (attrs.path) otelAttrs['url.path'] = attrs.path;
-	if (attrs.route) otelAttrs['http.route'] = attrs.route;
-	if (attrs.host) otelAttrs['server.address'] = attrs.host;
-	if (attrs.scheme) otelAttrs['url.scheme'] = attrs.scheme;
-	if (attrs.userAgent) otelAttrs['user_agent.original'] = attrs.userAgent;
-	if (attrs.clientIp) otelAttrs['client.address'] = attrs.clientIp;
-	if (attrs.requestId) otelAttrs['http.request.id'] = attrs.requestId;
-
-	// HTTP response attributes
-	if (attrs.response?.statusCode) {
-		otelAttrs['http.response.status_code'] = attrs.response.statusCode;
-	}
-	if (attrs.response?.responseSize) {
-		otelAttrs['http.response.body.size'] = attrs.response.responseSize;
-	}
-
-	// Endpoint attributes
-	if (attrs.endpoint?.name) otelAttrs['endpoint.name'] = attrs.endpoint.name;
-	if (attrs.endpoint?.operationId) {
-		otelAttrs['endpoint.operation_id'] = attrs.endpoint.operationId;
-	}
-	if (attrs.endpoint?.tags?.length) {
-		otelAttrs['endpoint.tags'] = attrs.endpoint.tags;
-	}
-
-	// User attributes
-	if (attrs.user?.userId) otelAttrs['enduser.id'] = attrs.user.userId;
-	if (attrs.user?.sessionId) otelAttrs['session.id'] = attrs.user.sessionId;
-	if (attrs.user?.roles?.length)
-		otelAttrs['enduser.role'] = attrs.user.roles.join(',');
-
-	// Custom attributes
-	if (attrs.custom) {
-		Object.assign(otelAttrs, attrs.custom);
-	}
-
-	return otelAttrs;
-}
-
-/**
- * Extract trace context from HTTP headers
- */
-export function extractTraceContext(
-	headers: Record<string, string | string[] | undefined>,
-): Context {
-	// Normalize headers to Record<string, string>
-	const normalizedHeaders: Record<string, string> = {};
-	for (const [key, value] of Object.entries(headers)) {
-		if (value) {
-			const stringValue = Array.isArray(value) ? value[0] : value;
-			if (stringValue) {
-				normalizedHeaders[key.toLowerCase()] = stringValue;
-			}
-		}
-	}
-
-	return propagation.extract(context.active(), normalizedHeaders);
-}
-
-/**
- * Inject trace context into HTTP headers
- */
-export function injectTraceContext(
-	headers: Record<string, string>,
-	ctx?: Context,
-): Record<string, string> {
-	const result = { ...headers };
-	propagation.inject(ctx ?? context.active(), result);
-	return result;
-}
-
-/**
- * Create an HTTP server span for an incoming request
- */
-export function createHttpServerSpan(
-	attrs: HttpSpanAttributes,
-	parentContext?: Context,
-): Span {
-	const tracer = getConstructsTracer();
-	const spanName = attrs.route
-		? `${attrs.method} ${attrs.route}`
-		: `${attrs.method} ${attrs.path || '/'}`;
-
-	const ctx = parentContext ?? context.active();
-
-	return tracer.startSpan(
-		spanName,
-		{
-			kind: SpanKind.SERVER,
-			attributes: toOtelAttributes(attrs),
-		},
-		ctx,
-	);
-}
-
-/**
- * End an HTTP span with response data
- */
-export function endHttpSpan(
-	span: Span,
-	response: HttpResponseAttributes,
-	error?: Error,
-): void {
-	span.setAttribute('http.response.status_code', response.statusCode);
-
-	if (response.responseSize) {
-		span.setAttribute('http.response.body.size', response.responseSize);
-	}
-
-	if (error) {
-		span.recordException(error);
-		span.setStatus({
-			code: SpanStatusCode.ERROR,
-			message: error.message,
-		});
-	} else if (response.statusCode >= 400) {
-		span.setStatus({
-			code: SpanStatusCode.ERROR,
-			message: `HTTP ${response.statusCode}`,
-		});
-	} else {
-		span.setStatus({ code: SpanStatusCode.OK });
-	}
-
-	span.end();
-}
-
-/**
- * Execute a function within an HTTP server span context
- *
- * @example
- * ```typescript
- * const result = await withHttpSpan(
- *   { method: 'GET', path: '/users', route: '/users' },
- *   async (span) => {
- *     const users = await getUsers();
- *     return { statusCode: 200, body: users };
- *   }
- * );
- * ```
- */
-export async function withHttpSpan<T>(
-	attrs: HttpSpanAttributes,
-	fn: (span: Span) => Promise<T & { statusCode?: number }>,
-	parentContext?: Context,
-): Promise<T> {
-	const span = createHttpServerSpan(attrs, parentContext);
-
-	try {
-		const result = await context.with(
-			trace.setSpan(parentContext ?? context.active(), span),
-			() => fn(span),
-		);
-
-		const statusCode = (result as { statusCode?: number }).statusCode ?? 200;
-		endHttpSpan(span, { statusCode });
-
-		return result;
-	} catch (error) {
-		endHttpSpan(
-			span,
-			{ statusCode: 500 },
-			error instanceof Error ? error : new Error(String(error)),
-		);
-		throw error;
-	}
-}
-
-/**
- * Create a child span for internal operations (middleware, handlers, etc.)
- */
-export function createChildSpan(name: string, attributes?: Attributes): Span {
-	const tracer = getConstructsTracer();
-	return tracer.startSpan(name, {
-		kind: SpanKind.INTERNAL,
-		attributes,
-	});
-}
-
-/**
- * Execute a function within a child span
- */
-export async function withChildSpan<T>(
-	name: string,
-	fn: (span: Span) => Promise<T>,
-	attributes?: Attributes,
-): Promise<T> {
-	const span = createChildSpan(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();
-	}
-}
-
-/**
- * Check if tracing is enabled (OpenTelemetry API is available and configured)
- */
-export function isTracingEnabled(): boolean {
-	try {
-		const tracer = trace.getTracer(TRACER_NAME);
-		// Check if we have a real tracer (not a no-op)
-		const span = tracer.startSpan('test');
-		const isReal =
-			span.spanContext().traceId !== '00000000000000000000000000000000';
-		span.end();
-		return isReal;
-	} catch {
-		return false;
-	}
-}

package/src/instrumentation/index.ts

@@ -1,90 +0,0 @@
-/**
- * OpenTelemetry Instrumentation for @geekmidas/constructs
- *
- * This module provides automatic instrumentation for constructs endpoints,
- * functions, crons, and subscribers using the OpenTelemetry SDK.
- *
- * @example
- * ```typescript
- * import { setupTelemetry } from '@geekmidas/telescope/instrumentation';
- *
- * // Call before importing your app code
- * setupTelemetry({
- *   serviceName: 'my-api',
- *   // Dev: send to Telescope
- *   endpoint: 'http://localhost:3000/__telescope/v1',
- *   // Enable Pino log correlation
- *   instrumentPino: true,
- * });
- * ```
- */
-
-export type {
-	SpanProcessorOptions,
-	SpanProcessorStrategy,
-} from '../adapters/types';
-export {
-	createSpanProcessor,
-	enableTelemetryDebug,
-	flushTelemetry,
-	getRecommendedStrategy,
-	isTelemetryInitialized,
-	NoopSpanProcessor,
-	setGlobalLogProcessor,
-	setGlobalSpanProcessor,
-	withTelemetryFlush,
-} from './core';
-export type { HonoTelemetryMiddlewareOptions } from './hono';
-// Middleware for Hono auto-instrumentation
-export {
-	getSpanFromContext,
-	getTraceContextFromHono,
-	honoTelemetryMiddleware,
-	withHonoSpanContext,
-} from './hono';
-export type {
-	EndpointAttributes,
-	HttpRequestAttributes,
-	HttpResponseAttributes,
-	HttpSpanAttributes,
-	UserAttributes,
-} from './http';
-
-// HTTP instrumentation utilities for constructs
-export {
-	createChildSpan,
-	createHttpServerSpan,
-	endHttpSpan,
-	extractTraceContext,
-	getConstructsTracer,
-	injectTraceContext,
-	isTracingEnabled,
-	toOtelAttributes,
-	withChildSpan,
-	withHttpSpan,
-} from './http';
-export type { TelemetryMiddlewareOptions } from './middleware';
-
-// Middleware for Lambda auto-instrumentation
-export {
-	getContextFromEvent,
-	getSpanFromEvent,
-	telemetryMiddleware,
-	withEventContext,
-} from './middleware';
-export type { OTelTelemetryOptions } from './otel';
-// OTelTelemetry - Telemetry interface implementation using OpenTelemetry
-export { OTelTelemetry } from './otel';
-export type { TelemetryOptions } from './setup';
-export { setupTelemetry, shutdownTelemetry } from './setup';
-export {
-	addSpanEvent,
-	createSpan,
-	getActiveSpan,
-	getSpanId,
-	getTraceId,
-	recordException,
-	setSpanAttributes,
-	withSpan,
-	withSpanSync,
-} from './tracing';

package/src/instrumentation/middleware.ts

@@ -1,297 +0,0 @@
-/**
- * OpenTelemetry instrumentation middleware for @geekmidas/constructs
- *
- * This middleware automatically creates spans for HTTP requests,
- * extracts trace context from incoming headers, and records
- * request/response metadata as span attributes.
- */
-import type { MiddlewareObj } from '@middy/core';
-import { context, type Span, trace } from '@opentelemetry/api';
-import type { Context as LambdaContext } from 'aws-lambda';
-import {
-	createHttpServerSpan,
-	endHttpSpan,
-	extractTraceContext,
-	type HttpSpanAttributes,
-} from './http';
-
-/**
- * Options for the telemetry middleware
- */
-export interface TelemetryMiddlewareOptions {
-	/**
-	 * 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 endpoint name from event
-	 */
-	getEndpointName?: (event: any) => string | undefined;
-
-	/**
-	 * Custom function to extract operation ID from event
-	 */
-	getOperationId?: (event: any) => string | undefined;
-
-	/**
-	 * Custom function to extract user ID from event
-	 */
-	getUserId?: (event: any) => string | undefined;
-
-	/**
-	 * Whether to skip tracing for this request
-	 */
-	shouldSkip?: (event: any) => boolean;
-}
-
-// Symbol for storing span on event
-const SPAN_SYMBOL = Symbol('telemetry.span');
-const CONTEXT_SYMBOL = Symbol('telemetry.context');
-
-/**
- * Get the current span from the Lambda event
- */
-export function getSpanFromEvent(event: any): Span | undefined {
-	return event?.[SPAN_SYMBOL];
-}
-
-/**
- * Get the current trace context from the Lambda event
- */
-export function getContextFromEvent(event: any): any {
-	return event?.[CONTEXT_SYMBOL];
-}
-
-/**
- * Create a telemetry middleware for Lambda handlers
- *
- * @example
- * ```typescript
- * import { telemetryMiddleware } from '@geekmidas/telescope/instrumentation';
- *
- * const adaptor = new AmazonApiGatewayV2Endpoint(envParser, endpoint, {
- *   telemetry: { middleware: telemetryMiddleware() },
- * });
- * ```
- */
-export function telemetryMiddleware(
-	options: TelemetryMiddlewareOptions = {},
-): MiddlewareObj<any, any, Error, LambdaContext> {
-	return {
-		before: async (request) => {
-			// Skip if custom skip function returns true
-			if (options.shouldSkip?.(request.event)) {
-				return;
-			}
-
-			const event = request.event;
-			const lambdaContext = request.context;
-
-			// Extract trace context from headers
-			const headers = normalizeHeaders(event.headers || {});
-			const parentContext = extractTraceContext(headers);
-
-			// Build span attributes from event
-			const attrs = buildSpanAttributes(event, lambdaContext, options);
-
-			// Create the span
-			const span = createHttpServerSpan(attrs, parentContext);
-
-			// Store span and context on event for access in handler
-			event[SPAN_SYMBOL] = span;
-			event[CONTEXT_SYMBOL] = trace.setSpan(parentContext, span);
-
-			// Add Lambda-specific attributes
-			span.setAttribute('faas.invocation_id', lambdaContext.awsRequestId);
-			span.setAttribute('faas.name', lambdaContext.functionName);
-
-			if (options.recordBody && event.body) {
-				const bodyStr =
-					typeof event.body === 'string'
-						? event.body
-						: JSON.stringify(event.body);
-				// Truncate large bodies
-				span.setAttribute(
-					'http.request.body',
-					bodyStr.length > 4096 ? `${bodyStr.slice(0, 4096)}...` : bodyStr,
-				);
-			}
-		},
-
-		after: async (request) => {
-			const span = getSpanFromEvent(request.event);
-			if (!span) {
-				return;
-			}
-
-			const response = request.response;
-			const statusCode =
-				typeof response?.statusCode === 'number' ? response.statusCode : 200;
-
-			if (options.recordResponseBody && response?.body) {
-				const bodyStr =
-					typeof response.body === 'string'
-						? response.body
-						: JSON.stringify(response.body);
-				span.setAttribute(
-					'http.response.body',
-					bodyStr.length > 4096 ? `${bodyStr.slice(0, 4096)}...` : bodyStr,
-				);
-			}
-
-			endHttpSpan(span, { statusCode });
-		},
-
-		onError: async (request) => {
-			const span = getSpanFromEvent(request.event);
-			if (!span) {
-				return;
-			}
-
-			const error = request.error;
-			const response = request.response;
-
-			// Determine status code from response or error
-			let statusCode = 500;
-			if (response?.statusCode) {
-				statusCode = response.statusCode;
-			} else if (error && 'statusCode' in error) {
-				statusCode = (error as any).statusCode;
-			}
-
-			endHttpSpan(
-				span,
-				{ statusCode },
-				error instanceof Error ? error : new Error(String(error)),
-			);
-		},
-	};
-}
-
-/**
- * Build span attributes from Lambda event
- */
-function buildSpanAttributes(
-	event: any,
-	lambdaContext: LambdaContext,
-	options: TelemetryMiddlewareOptions,
-): 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 (options.getEndpointName || options.getOperationId) {
-		attrs.endpoint = {
-			name: options.getEndpointName?.(event),
-			operationId: options.getOperationId?.(event),
-		};
-	}
-
-	// Add user metadata if extractor provided
-	if (options.getUserId) {
-		const userId = 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;
-}
-
-/**
- * Run a function within the span context from a Lambda event
- *
- * @example
- * ```typescript
- * await withEventContext(event, async () => {
- *   // Any spans created here will be children of the request span
- *   await doSomething();
- * });
- * ```
- */
-export async function withEventContext<T>(
-	event: any,
-	fn: () => Promise<T>,
-): Promise<T> {
-	const ctx = getContextFromEvent(event);
-	if (!ctx) {
-		return fn();
-	}
-	return context.with(ctx, fn);
-}