@geekmidas/telescope 1.1.1 → 10.0.0-alpha.0

package/dist/middleware-Dy1ctr2N.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"middleware-Dy1ctr2N.mjs","names":["event: any","options: TelemetryMiddlewareOptions","lambdaContext: LambdaContext","route: string | undefined","host: string | undefined","scheme: 'http' | 'https' | undefined","userAgent: string | undefined","clientIp: string | undefined","requestId: string | undefined","attrs: HttpSpanAttributes","headers: Record<string, string | string[] | undefined>","normalized: Record<string, string | string[] | undefined>","fn: () => Promise<T>"],"sources":["../src/instrumentation/middleware.ts"],"sourcesContent":["/**\n * OpenTelemetry instrumentation middleware for @geekmidas/constructs\n *\n * This middleware automatically creates spans for HTTP requests,\n * extracts trace context from incoming headers, and records\n * request/response metadata as span attributes.\n */\nimport type { MiddlewareObj } from '@middy/core';\nimport { context, type Span, trace } from '@opentelemetry/api';\nimport type { Context as LambdaContext } from 'aws-lambda';\nimport {\n\tcreateHttpServerSpan,\n\tendHttpSpan,\n\textractTraceContext,\n\ttype HttpSpanAttributes,\n} from './http';\n\n/**\n * Options for the telemetry middleware\n */\nexport interface TelemetryMiddlewareOptions {\n\t/**\n\t * Whether to record request body as span attribute\n\t * @default false\n\t */\n\trecordBody?: boolean;\n\n\t/**\n\t * Whether to record response body as span attribute\n\t * @default false\n\t */\n\trecordResponseBody?: boolean;\n\n\t/**\n\t * Custom function to extract endpoint name from event\n\t */\n\tgetEndpointName?: (event: any) => string | undefined;\n\n\t/**\n\t * Custom function to extract operation ID from event\n\t */\n\tgetOperationId?: (event: any) => string | undefined;\n\n\t/**\n\t * Custom function to extract user ID from event\n\t */\n\tgetUserId?: (event: any) => string | undefined;\n\n\t/**\n\t * Whether to skip tracing for this request\n\t */\n\tshouldSkip?: (event: any) => boolean;\n}\n\n// Symbol for storing span on event\nconst SPAN_SYMBOL = Symbol('telemetry.span');\nconst CONTEXT_SYMBOL = Symbol('telemetry.context');\n\n/**\n * Get the current span from the Lambda event\n */\nexport function getSpanFromEvent(event: any): Span | undefined {\n\treturn event?.[SPAN_SYMBOL];\n}\n\n/**\n * Get the current trace context from the Lambda event\n */\nexport function getContextFromEvent(event: any): any {\n\treturn event?.[CONTEXT_SYMBOL];\n}\n\n/**\n * Create a telemetry middleware for Lambda handlers\n *\n * @example\n * ```typescript\n * import { telemetryMiddleware } from '@geekmidas/telescope/instrumentation';\n *\n * const adaptor = new AmazonApiGatewayV2Endpoint(envParser, endpoint, {\n *   telemetry: { middleware: telemetryMiddleware() },\n * });\n * ```\n */\nexport function telemetryMiddleware(\n\toptions: TelemetryMiddlewareOptions = {},\n): MiddlewareObj<any, any, Error, LambdaContext> {\n\treturn {\n\t\tbefore: async (request) => {\n\t\t\t// Skip if custom skip function returns true\n\t\t\tif (options.shouldSkip?.(request.event)) {\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst event = request.event;\n\t\t\tconst lambdaContext = request.context;\n\n\t\t\t// Extract trace context from headers\n\t\t\tconst headers = normalizeHeaders(event.headers || {});\n\t\t\tconst parentContext = extractTraceContext(headers);\n\n\t\t\t// Build span attributes from event\n\t\t\tconst attrs = buildSpanAttributes(event, lambdaContext, options);\n\n\t\t\t// Create the span\n\t\t\tconst span = createHttpServerSpan(attrs, parentContext);\n\n\t\t\t// Store span and context on event for access in handler\n\t\t\tevent[SPAN_SYMBOL] = span;\n\t\t\tevent[CONTEXT_SYMBOL] = trace.setSpan(parentContext, span);\n\n\t\t\t// Add Lambda-specific attributes\n\t\t\tspan.setAttribute('faas.invocation_id', lambdaContext.awsRequestId);\n\t\t\tspan.setAttribute('faas.name', lambdaContext.functionName);\n\n\t\t\tif (options.recordBody && event.body) {\n\t\t\t\tconst bodyStr =\n\t\t\t\t\ttypeof event.body === 'string'\n\t\t\t\t\t\t? event.body\n\t\t\t\t\t\t: JSON.stringify(event.body);\n\t\t\t\t// Truncate large bodies\n\t\t\t\tspan.setAttribute(\n\t\t\t\t\t'http.request.body',\n\t\t\t\t\tbodyStr.length > 4096 ? `${bodyStr.slice(0, 4096)}...` : bodyStr,\n\t\t\t\t);\n\t\t\t}\n\t\t},\n\n\t\tafter: async (request) => {\n\t\t\tconst span = getSpanFromEvent(request.event);\n\t\t\tif (!span) {\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst response = request.response;\n\t\t\tconst statusCode =\n\t\t\t\ttypeof response?.statusCode === 'number' ? response.statusCode : 200;\n\n\t\t\tif (options.recordResponseBody && response?.body) {\n\t\t\t\tconst bodyStr =\n\t\t\t\t\ttypeof response.body === 'string'\n\t\t\t\t\t\t? response.body\n\t\t\t\t\t\t: JSON.stringify(response.body);\n\t\t\t\tspan.setAttribute(\n\t\t\t\t\t'http.response.body',\n\t\t\t\t\tbodyStr.length > 4096 ? `${bodyStr.slice(0, 4096)}...` : bodyStr,\n\t\t\t\t);\n\t\t\t}\n\n\t\t\tendHttpSpan(span, { statusCode });\n\t\t},\n\n\t\tonError: async (request) => {\n\t\t\tconst span = getSpanFromEvent(request.event);\n\t\t\tif (!span) {\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tconst error = request.error;\n\t\t\tconst response = request.response;\n\n\t\t\t// Determine status code from response or error\n\t\t\tlet statusCode = 500;\n\t\t\tif (response?.statusCode) {\n\t\t\t\tstatusCode = response.statusCode;\n\t\t\t} else if (error && 'statusCode' in error) {\n\t\t\t\tstatusCode = (error as any).statusCode;\n\t\t\t}\n\n\t\t\tendHttpSpan(\n\t\t\t\tspan,\n\t\t\t\t{ statusCode },\n\t\t\t\terror instanceof Error ? error : new Error(String(error)),\n\t\t\t);\n\t\t},\n\t};\n}\n\n/**\n * Build span attributes from Lambda event\n */\nfunction buildSpanAttributes(\n\tevent: any,\n\tlambdaContext: LambdaContext,\n\toptions: TelemetryMiddlewareOptions,\n): HttpSpanAttributes {\n\t// Detect event type (API Gateway v1, v2, ALB, or direct invoke)\n\tconst isV2 =\n\t\t'requestContext' in event && 'http' in (event.requestContext || {});\n\tconst isV1 =\n\t\t'requestContext' in event &&\n\t\t'httpMethod' in event &&\n\t\t!('http' in (event.requestContext || {}));\n\n\tlet method = 'INVOKE';\n\tlet path = '/';\n\tlet route: string | undefined;\n\tlet host: string | undefined;\n\tlet scheme: 'http' | 'https' | undefined;\n\tlet userAgent: string | undefined;\n\tlet clientIp: string | undefined;\n\tlet requestId: string | undefined;\n\n\tif (isV2) {\n\t\t// API Gateway v2 (HTTP API)\n\t\tconst http = event.requestContext.http;\n\t\tmethod = http.method;\n\t\tpath = event.rawPath || http.path;\n\t\troute = event.routeKey?.replace(/^[A-Z]+\\s+/, ''); // Remove HTTP method prefix\n\t\thost = event.headers?.host;\n\t\tscheme = 'https';\n\t\tuserAgent = http.userAgent;\n\t\tclientIp = http.sourceIp;\n\t\trequestId = event.requestContext.requestId;\n\t} else if (isV1) {\n\t\t// API Gateway v1 (REST API)\n\t\tmethod = event.httpMethod;\n\t\tpath = event.path;\n\t\troute = event.resource;\n\t\thost = event.headers?.Host || event.headers?.host;\n\t\tscheme = 'https';\n\t\tuserAgent = event.headers?.['User-Agent'] || event.headers?.['user-agent'];\n\t\tclientIp = event.requestContext?.identity?.sourceIp;\n\t\trequestId = event.requestContext?.requestId;\n\t} else if ('httpMethod' in event) {\n\t\t// ALB event\n\t\tmethod = event.httpMethod;\n\t\tpath = event.path;\n\t\thost = event.headers?.host;\n\t\tuserAgent = event.headers?.['user-agent'] || event.headers?.['User-Agent'];\n\t\tclientIp = event.headers?.['x-forwarded-for']?.split(',')[0]?.trim();\n\t}\n\n\tconst attrs: HttpSpanAttributes = {\n\t\tmethod,\n\t\tpath,\n\t\troute,\n\t\thost,\n\t\tscheme,\n\t\tuserAgent,\n\t\tclientIp,\n\t\trequestId: requestId || lambdaContext.awsRequestId,\n\t};\n\n\t// Add endpoint metadata if extractors provided\n\tif (options.getEndpointName || options.getOperationId) {\n\t\tattrs.endpoint = {\n\t\t\tname: options.getEndpointName?.(event),\n\t\t\toperationId: options.getOperationId?.(event),\n\t\t};\n\t}\n\n\t// Add user metadata if extractor provided\n\tif (options.getUserId) {\n\t\tconst userId = options.getUserId(event);\n\t\tif (userId) {\n\t\t\tattrs.user = { userId };\n\t\t}\n\t}\n\n\treturn attrs;\n}\n\n/**\n * Normalize headers to lowercase keys\n */\nfunction normalizeHeaders(\n\theaders: Record<string, string | string[] | undefined>,\n): Record<string, string | string[] | undefined> {\n\tconst normalized: Record<string, string | string[] | undefined> = {};\n\tfor (const [key, value] of Object.entries(headers)) {\n\t\tnormalized[key.toLowerCase()] = value;\n\t}\n\treturn normalized;\n}\n\n/**\n * Run a function within the span context from a Lambda event\n *\n * @example\n * ```typescript\n * await withEventContext(event, async () => {\n *   // Any spans created here will be children of the request span\n *   await doSomething();\n * });\n * ```\n */\nexport async function withEventContext<T>(\n\tevent: any,\n\tfn: () => Promise<T>,\n): Promise<T> {\n\tconst ctx = getContextFromEvent(event);\n\tif (!ctx) {\n\t\treturn fn();\n\t}\n\treturn context.with(ctx, fn);\n}\n"],"mappings":"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"}

package/dist/otel-DPKNyJ0t.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"otel-DPKNyJ0t.mjs","names":["options: OTelTelemetryOptions","request: TelemetryRequest","ctx: TelemetryContext","response: TelemetryResponse","error: Error","event: any","lambdaContext: any","route: string | undefined","host: string | undefined","scheme: 'http' | 'https' | undefined","userAgent: string | undefined","clientIp: string | undefined","requestId: string | undefined","attrs: HttpSpanAttributes","headers: Record<string, string | string[] | undefined>","normalized: Record<string, string | string[] | undefined>"],"sources":["../src/instrumentation/otel.ts"],"sourcesContent":["/**\n * OpenTelemetry implementation of the Telemetry interface\n *\n * This provides automatic span creation for Lambda handlers using\n * OpenTelemetry. Works with any OTel-compatible backend (Jaeger, Zipkin,\n * Datadog, Honeycomb, etc.)\n */\nimport { type Span, trace } from '@opentelemetry/api';\nimport type { Context as LambdaContext } from 'aws-lambda';\n\n/**\n * Context object returned by onRequestStart, passed to subsequent hooks.\n * This matches the Telemetry interface from @geekmidas/constructs.\n */\nexport interface TelemetryContext {\n\t[key: string]: unknown;\n}\n\n/**\n * Request information passed to telemetry hooks.\n * This matches the Telemetry interface from @geekmidas/constructs.\n */\nexport interface TelemetryRequest {\n\tevent: any;\n\tcontext: LambdaContext;\n}\n\n/**\n * Response information passed to onRequestEnd.\n * This matches the Telemetry interface from @geekmidas/constructs.\n */\nexport interface TelemetryResponse {\n\tstatusCode: number;\n\tbody?: string;\n\theaders?: Record<string, string>;\n}\n\n/**\n * Telemetry interface for instrumenting endpoint requests.\n * This matches the Telemetry interface from @geekmidas/constructs.\n */\nexport interface Telemetry {\n\tonRequestStart(request: TelemetryRequest): TelemetryContext;\n\tonRequestEnd(ctx: TelemetryContext, response: TelemetryResponse): void;\n\tonRequestError(ctx: TelemetryContext, error: Error): void;\n}\n\nimport {\n\tcreateHttpServerSpan,\n\tendHttpSpan,\n\textractTraceContext,\n\ttype HttpSpanAttributes,\n} from './http';\n\n/**\n * Options for OTelTelemetry\n */\nexport interface OTelTelemetryOptions {\n\t/**\n\t * Whether to record request body as span attribute\n\t * @default false\n\t */\n\trecordBody?: boolean;\n\n\t/**\n\t * Whether to record response body as span attribute\n\t * @default false\n\t */\n\trecordResponseBody?: boolean;\n\n\t/**\n\t * Custom function to extract user ID from event\n\t */\n\tgetUserId?: (event: any) => string | undefined;\n\n\t/**\n\t * Custom function to extract endpoint name from event\n\t */\n\tgetEndpointName?: (event: any) => string | undefined;\n\n\t/**\n\t * Custom function to extract operation ID from event\n\t */\n\tgetOperationId?: (event: any) => string | undefined;\n}\n\n/**\n * Telemetry context with span reference\n */\ninterface OTelContext extends TelemetryContext {\n\tspan: Span;\n\totelContext: any;\n}\n\n/**\n * OpenTelemetry implementation of the Telemetry interface\n *\n * @example\n * ```typescript\n * import { OTelTelemetry } from '@geekmidas/telescope/instrumentation';\n *\n * const adaptor = new AmazonApiGatewayV2Endpoint(envParser, endpoint, {\n *   telemetry: new OTelTelemetry(),\n * });\n * ```\n *\n * @example With options\n * ```typescript\n * const adaptor = new AmazonApiGatewayV2Endpoint(envParser, endpoint, {\n *   telemetry: new OTelTelemetry({\n *     recordBody: true,\n *     getUserId: (event) => event.requestContext?.authorizer?.userId,\n *   }),\n * });\n * ```\n */\nexport class OTelTelemetry implements Telemetry {\n\tconstructor(private options: OTelTelemetryOptions = {}) {}\n\n\tonRequestStart(request: TelemetryRequest): TelemetryContext {\n\t\tconst { event, context: lambdaContext } = request;\n\n\t\t// Extract trace context from headers\n\t\tconst headers = normalizeHeaders(event.headers || {});\n\t\tconst parentContext = extractTraceContext(headers);\n\n\t\t// Build span attributes from event\n\t\tconst attrs = this.buildSpanAttributes(event, lambdaContext);\n\n\t\t// Create the span\n\t\tconst span = createHttpServerSpan(attrs, parentContext);\n\t\tconst otelContext = trace.setSpan(parentContext, span);\n\n\t\t// Add Lambda-specific attributes\n\t\tspan.setAttribute('faas.invocation_id', lambdaContext.awsRequestId);\n\t\tspan.setAttribute('faas.name', lambdaContext.functionName);\n\n\t\t// Record body if requested\n\t\tif (this.options.recordBody && event.body) {\n\t\t\tconst bodyStr =\n\t\t\t\ttypeof event.body === 'string'\n\t\t\t\t\t? event.body\n\t\t\t\t\t: JSON.stringify(event.body);\n\t\t\tspan.setAttribute(\n\t\t\t\t'http.request.body',\n\t\t\t\tbodyStr.length > 4096 ? `${bodyStr.slice(0, 4096)}...` : bodyStr,\n\t\t\t);\n\t\t}\n\n\t\treturn { span, otelContext } as OTelContext;\n\t}\n\n\tonRequestEnd(ctx: TelemetryContext, response: TelemetryResponse): void {\n\t\tconst { span } = ctx as OTelContext;\n\n\t\tif (this.options.recordResponseBody && response.body) {\n\t\t\tspan.setAttribute(\n\t\t\t\t'http.response.body',\n\t\t\t\tresponse.body.length > 4096\n\t\t\t\t\t? `${response.body.slice(0, 4096)}...`\n\t\t\t\t\t: response.body,\n\t\t\t);\n\t\t}\n\n\t\tendHttpSpan(span, { statusCode: response.statusCode });\n\t}\n\n\tonRequestError(ctx: TelemetryContext, error: Error): void {\n\t\tconst { span } = ctx as OTelContext;\n\t\tendHttpSpan(span, { statusCode: 500 }, error);\n\t}\n\n\t/**\n\t * Build span attributes from Lambda event\n\t */\n\tprivate buildSpanAttributes(\n\t\tevent: any,\n\t\tlambdaContext: any,\n\t): HttpSpanAttributes {\n\t\t// Detect event type (API Gateway v1, v2, ALB, or direct invoke)\n\t\tconst isV2 =\n\t\t\t'requestContext' in event && 'http' in (event.requestContext || {});\n\t\tconst isV1 =\n\t\t\t'requestContext' in event &&\n\t\t\t'httpMethod' in event &&\n\t\t\t!('http' in (event.requestContext || {}));\n\n\t\tlet method = 'INVOKE';\n\t\tlet path = '/';\n\t\tlet route: string | undefined;\n\t\tlet host: string | undefined;\n\t\tlet scheme: 'http' | 'https' | undefined;\n\t\tlet userAgent: string | undefined;\n\t\tlet clientIp: string | undefined;\n\t\tlet requestId: string | undefined;\n\n\t\tif (isV2) {\n\t\t\t// API Gateway v2 (HTTP API)\n\t\t\tconst http = event.requestContext.http;\n\t\t\tmethod = http.method;\n\t\t\tpath = event.rawPath || http.path;\n\t\t\troute = event.routeKey?.replace(/^[A-Z]+\\s+/, ''); // Remove HTTP method prefix\n\t\t\thost = event.headers?.host;\n\t\t\tscheme = 'https';\n\t\t\tuserAgent = http.userAgent;\n\t\t\tclientIp = http.sourceIp;\n\t\t\trequestId = event.requestContext.requestId;\n\t\t} else if (isV1) {\n\t\t\t// API Gateway v1 (REST API)\n\t\t\tmethod = event.httpMethod;\n\t\t\tpath = event.path;\n\t\t\troute = event.resource;\n\t\t\thost = event.headers?.Host || event.headers?.host;\n\t\t\tscheme = 'https';\n\t\t\tuserAgent =\n\t\t\t\tevent.headers?.['User-Agent'] || event.headers?.['user-agent'];\n\t\t\tclientIp = event.requestContext?.identity?.sourceIp;\n\t\t\trequestId = event.requestContext?.requestId;\n\t\t} else if ('httpMethod' in event) {\n\t\t\t// ALB event\n\t\t\tmethod = event.httpMethod;\n\t\t\tpath = event.path;\n\t\t\thost = event.headers?.host;\n\t\t\tuserAgent =\n\t\t\t\tevent.headers?.['user-agent'] || event.headers?.['User-Agent'];\n\t\t\tclientIp = event.headers?.['x-forwarded-for']?.split(',')[0]?.trim();\n\t\t}\n\n\t\tconst attrs: HttpSpanAttributes = {\n\t\t\tmethod,\n\t\t\tpath,\n\t\t\troute,\n\t\t\thost,\n\t\t\tscheme,\n\t\t\tuserAgent,\n\t\t\tclientIp,\n\t\t\trequestId: requestId || lambdaContext.awsRequestId,\n\t\t};\n\n\t\t// Add endpoint metadata if extractors provided\n\t\tif (this.options.getEndpointName || this.options.getOperationId) {\n\t\t\tattrs.endpoint = {\n\t\t\t\tname: this.options.getEndpointName?.(event),\n\t\t\t\toperationId: this.options.getOperationId?.(event),\n\t\t\t};\n\t\t}\n\n\t\t// Add user metadata if extractor provided\n\t\tif (this.options.getUserId) {\n\t\t\tconst userId = this.options.getUserId(event);\n\t\t\tif (userId) {\n\t\t\t\tattrs.user = { userId };\n\t\t\t}\n\t\t}\n\n\t\treturn attrs;\n\t}\n}\n\n/**\n * Normalize headers to lowercase keys\n */\nfunction normalizeHeaders(\n\theaders: Record<string, string | string[] | undefined>,\n): Record<string, string | string[] | undefined> {\n\tconst normalized: Record<string, string | string[] | undefined> = {};\n\tfor (const [key, value] of Object.entries(headers)) {\n\t\tnormalized[key.toLowerCase()] = value;\n\t}\n\treturn normalized;\n}\n"],"mappings":"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"}

package/dist/otel-DuiBeBPU.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"otel-DuiBeBPU.cjs","names":["options: OTelTelemetryOptions","request: TelemetryRequest","ctx: TelemetryContext","response: TelemetryResponse","error: Error","event: any","lambdaContext: any","route: string | undefined","host: string | undefined","scheme: 'http' | 'https' | undefined","userAgent: string | undefined","clientIp: string | undefined","requestId: string | undefined","attrs: HttpSpanAttributes","headers: Record<string, string | string[] | undefined>","normalized: Record<string, string | string[] | undefined>"],"sources":["../src/instrumentation/otel.ts"],"sourcesContent":["/**\n * OpenTelemetry implementation of the Telemetry interface\n *\n * This provides automatic span creation for Lambda handlers using\n * OpenTelemetry. Works with any OTel-compatible backend (Jaeger, Zipkin,\n * Datadog, Honeycomb, etc.)\n */\nimport { type Span, trace } from '@opentelemetry/api';\nimport type { Context as LambdaContext } from 'aws-lambda';\n\n/**\n * Context object returned by onRequestStart, passed to subsequent hooks.\n * This matches the Telemetry interface from @geekmidas/constructs.\n */\nexport interface TelemetryContext {\n\t[key: string]: unknown;\n}\n\n/**\n * Request information passed to telemetry hooks.\n * This matches the Telemetry interface from @geekmidas/constructs.\n */\nexport interface TelemetryRequest {\n\tevent: any;\n\tcontext: LambdaContext;\n}\n\n/**\n * Response information passed to onRequestEnd.\n * This matches the Telemetry interface from @geekmidas/constructs.\n */\nexport interface TelemetryResponse {\n\tstatusCode: number;\n\tbody?: string;\n\theaders?: Record<string, string>;\n}\n\n/**\n * Telemetry interface for instrumenting endpoint requests.\n * This matches the Telemetry interface from @geekmidas/constructs.\n */\nexport interface Telemetry {\n\tonRequestStart(request: TelemetryRequest): TelemetryContext;\n\tonRequestEnd(ctx: TelemetryContext, response: TelemetryResponse): void;\n\tonRequestError(ctx: TelemetryContext, error: Error): void;\n}\n\nimport {\n\tcreateHttpServerSpan,\n\tendHttpSpan,\n\textractTraceContext,\n\ttype HttpSpanAttributes,\n} from './http';\n\n/**\n * Options for OTelTelemetry\n */\nexport interface OTelTelemetryOptions {\n\t/**\n\t * Whether to record request body as span attribute\n\t * @default false\n\t */\n\trecordBody?: boolean;\n\n\t/**\n\t * Whether to record response body as span attribute\n\t * @default false\n\t */\n\trecordResponseBody?: boolean;\n\n\t/**\n\t * Custom function to extract user ID from event\n\t */\n\tgetUserId?: (event: any) => string | undefined;\n\n\t/**\n\t * Custom function to extract endpoint name from event\n\t */\n\tgetEndpointName?: (event: any) => string | undefined;\n\n\t/**\n\t * Custom function to extract operation ID from event\n\t */\n\tgetOperationId?: (event: any) => string | undefined;\n}\n\n/**\n * Telemetry context with span reference\n */\ninterface OTelContext extends TelemetryContext {\n\tspan: Span;\n\totelContext: any;\n}\n\n/**\n * OpenTelemetry implementation of the Telemetry interface\n *\n * @example\n * ```typescript\n * import { OTelTelemetry } from '@geekmidas/telescope/instrumentation';\n *\n * const adaptor = new AmazonApiGatewayV2Endpoint(envParser, endpoint, {\n *   telemetry: new OTelTelemetry(),\n * });\n * ```\n *\n * @example With options\n * ```typescript\n * const adaptor = new AmazonApiGatewayV2Endpoint(envParser, endpoint, {\n *   telemetry: new OTelTelemetry({\n *     recordBody: true,\n *     getUserId: (event) => event.requestContext?.authorizer?.userId,\n *   }),\n * });\n * ```\n */\nexport class OTelTelemetry implements Telemetry {\n\tconstructor(private options: OTelTelemetryOptions = {}) {}\n\n\tonRequestStart(request: TelemetryRequest): TelemetryContext {\n\t\tconst { event, context: lambdaContext } = request;\n\n\t\t// Extract trace context from headers\n\t\tconst headers = normalizeHeaders(event.headers || {});\n\t\tconst parentContext = extractTraceContext(headers);\n\n\t\t// Build span attributes from event\n\t\tconst attrs = this.buildSpanAttributes(event, lambdaContext);\n\n\t\t// Create the span\n\t\tconst span = createHttpServerSpan(attrs, parentContext);\n\t\tconst otelContext = trace.setSpan(parentContext, span);\n\n\t\t// Add Lambda-specific attributes\n\t\tspan.setAttribute('faas.invocation_id', lambdaContext.awsRequestId);\n\t\tspan.setAttribute('faas.name', lambdaContext.functionName);\n\n\t\t// Record body if requested\n\t\tif (this.options.recordBody && event.body) {\n\t\t\tconst bodyStr =\n\t\t\t\ttypeof event.body === 'string'\n\t\t\t\t\t? event.body\n\t\t\t\t\t: JSON.stringify(event.body);\n\t\t\tspan.setAttribute(\n\t\t\t\t'http.request.body',\n\t\t\t\tbodyStr.length > 4096 ? `${bodyStr.slice(0, 4096)}...` : bodyStr,\n\t\t\t);\n\t\t}\n\n\t\treturn { span, otelContext } as OTelContext;\n\t}\n\n\tonRequestEnd(ctx: TelemetryContext, response: TelemetryResponse): void {\n\t\tconst { span } = ctx as OTelContext;\n\n\t\tif (this.options.recordResponseBody && response.body) {\n\t\t\tspan.setAttribute(\n\t\t\t\t'http.response.body',\n\t\t\t\tresponse.body.length > 4096\n\t\t\t\t\t? `${response.body.slice(0, 4096)}...`\n\t\t\t\t\t: response.body,\n\t\t\t);\n\t\t}\n\n\t\tendHttpSpan(span, { statusCode: response.statusCode });\n\t}\n\n\tonRequestError(ctx: TelemetryContext, error: Error): void {\n\t\tconst { span } = ctx as OTelContext;\n\t\tendHttpSpan(span, { statusCode: 500 }, error);\n\t}\n\n\t/**\n\t * Build span attributes from Lambda event\n\t */\n\tprivate buildSpanAttributes(\n\t\tevent: any,\n\t\tlambdaContext: any,\n\t): HttpSpanAttributes {\n\t\t// Detect event type (API Gateway v1, v2, ALB, or direct invoke)\n\t\tconst isV2 =\n\t\t\t'requestContext' in event && 'http' in (event.requestContext || {});\n\t\tconst isV1 =\n\t\t\t'requestContext' in event &&\n\t\t\t'httpMethod' in event &&\n\t\t\t!('http' in (event.requestContext || {}));\n\n\t\tlet method = 'INVOKE';\n\t\tlet path = '/';\n\t\tlet route: string | undefined;\n\t\tlet host: string | undefined;\n\t\tlet scheme: 'http' | 'https' | undefined;\n\t\tlet userAgent: string | undefined;\n\t\tlet clientIp: string | undefined;\n\t\tlet requestId: string | undefined;\n\n\t\tif (isV2) {\n\t\t\t// API Gateway v2 (HTTP API)\n\t\t\tconst http = event.requestContext.http;\n\t\t\tmethod = http.method;\n\t\t\tpath = event.rawPath || http.path;\n\t\t\troute = event.routeKey?.replace(/^[A-Z]+\\s+/, ''); // Remove HTTP method prefix\n\t\t\thost = event.headers?.host;\n\t\t\tscheme = 'https';\n\t\t\tuserAgent = http.userAgent;\n\t\t\tclientIp = http.sourceIp;\n\t\t\trequestId = event.requestContext.requestId;\n\t\t} else if (isV1) {\n\t\t\t// API Gateway v1 (REST API)\n\t\t\tmethod = event.httpMethod;\n\t\t\tpath = event.path;\n\t\t\troute = event.resource;\n\t\t\thost = event.headers?.Host || event.headers?.host;\n\t\t\tscheme = 'https';\n\t\t\tuserAgent =\n\t\t\t\tevent.headers?.['User-Agent'] || event.headers?.['user-agent'];\n\t\t\tclientIp = event.requestContext?.identity?.sourceIp;\n\t\t\trequestId = event.requestContext?.requestId;\n\t\t} else if ('httpMethod' in event) {\n\t\t\t// ALB event\n\t\t\tmethod = event.httpMethod;\n\t\t\tpath = event.path;\n\t\t\thost = event.headers?.host;\n\t\t\tuserAgent =\n\t\t\t\tevent.headers?.['user-agent'] || event.headers?.['User-Agent'];\n\t\t\tclientIp = event.headers?.['x-forwarded-for']?.split(',')[0]?.trim();\n\t\t}\n\n\t\tconst attrs: HttpSpanAttributes = {\n\t\t\tmethod,\n\t\t\tpath,\n\t\t\troute,\n\t\t\thost,\n\t\t\tscheme,\n\t\t\tuserAgent,\n\t\t\tclientIp,\n\t\t\trequestId: requestId || lambdaContext.awsRequestId,\n\t\t};\n\n\t\t// Add endpoint metadata if extractors provided\n\t\tif (this.options.getEndpointName || this.options.getOperationId) {\n\t\t\tattrs.endpoint = {\n\t\t\t\tname: this.options.getEndpointName?.(event),\n\t\t\t\toperationId: this.options.getOperationId?.(event),\n\t\t\t};\n\t\t}\n\n\t\t// Add user metadata if extractor provided\n\t\tif (this.options.getUserId) {\n\t\t\tconst userId = this.options.getUserId(event);\n\t\t\tif (userId) {\n\t\t\t\tattrs.user = { userId };\n\t\t\t}\n\t\t}\n\n\t\treturn attrs;\n\t}\n}\n\n/**\n * Normalize headers to lowercase keys\n */\nfunction normalizeHeaders(\n\theaders: Record<string, string | string[] | undefined>,\n): Record<string, string | string[] | undefined> {\n\tconst normalized: Record<string, string | string[] | undefined> = {};\n\tfor (const [key, value] of Object.entries(headers)) {\n\t\tnormalized[key.toLowerCase()] = value;\n\t}\n\treturn normalized;\n}\n"],"mappings":"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"}

package/src/Telescope.ts

@@ -1,561 +0,0 @@
-import { nanoid } from 'nanoid';
-import {
-	MetricsAggregator,
-	type MetricsAggregatorOptions,
-} from './metrics/MetricsAggregator';
-import { createRedactor, type Redactor } from './redact';
-import type {
-	EndpointDetails,
-	EndpointMetrics,
-	ExceptionEntry,
-	LogEntry,
-	MetricsQueryOptions,
-	MetricsSnapshot,
-	NormalizedTelescopeOptions,
-	QueryOptions,
-	RequestEntry,
-	RequestMetrics,
-	StackFrame,
-	StatusDistribution,
-	TelescopeEvent,
-	TelescopeOptions,
-	TelescopeStorage,
-} from './types';
-
-/**
- * Framework-agnostic Telescope class for debugging and monitoring applications.
- * Use framework-specific adapters (e.g., @geekmidas/telescope/hono) for integration.
- */
-export class Telescope {
-	private storage: TelescopeStorage;
-	private options: NormalizedTelescopeOptions;
-	private wsClients = new Set<WebSocket>();
-	private pruneInterval?: ReturnType<typeof setInterval>;
-	private metricsBroadcastInterval?: ReturnType<typeof setInterval>;
-	private redactor?: Redactor;
-	private metricsAggregator: MetricsAggregator;
-
-	constructor(
-		options: TelescopeOptions & { metrics?: MetricsAggregatorOptions },
-	) {
-		this.storage = options.storage;
-		this.options = this.normalizeOptions(options);
-		this.redactor = createRedactor(options.redact);
-		this.metricsAggregator = new MetricsAggregator(options.metrics);
-
-		// Set up auto-pruning if configured
-		if (this.options.pruneAfterHours) {
-			const intervalMs = 60 * 60 * 1000; // 1 hour
-			this.pruneInterval = setInterval(() => {
-				this.autoPrune().catch(console.error);
-			}, intervalMs);
-		}
-	}
-
-	// ============================================
-	// Public API - Recording
-	// ============================================
-
-	/**
-	 * Record a request entry
-	 */
-	async recordRequest(
-		entry: Omit<RequestEntry, 'id' | 'timestamp'>,
-	): Promise<string> {
-		if (!this.options.enabled) return '';
-
-		// Use injected request ID from context if available, otherwise generate one
-		const id = this.options.getRequestId?.() ?? nanoid();
-		let fullEntry: RequestEntry = {
-			...entry,
-			id,
-			timestamp: new Date(),
-		};
-
-		// Apply redaction if configured
-		if (this.redactor) {
-			fullEntry = this.redactor(fullEntry);
-		}
-
-		// Record metrics (before storage for real-time aggregation)
-		this.metricsAggregator.record(fullEntry);
-
-		await this.storage.saveRequest(fullEntry);
-		this.broadcast({
-			type: 'request',
-			payload: fullEntry,
-			timestamp: Date.now(),
-		});
-		return id;
-	}
-
-	/**
-	 * Log entry input for batch operations
-	 */
-	private async saveLogEntries(entries: LogEntry[]): Promise<void> {
-		if (this.storage.saveLogs) {
-			await this.storage.saveLogs(entries);
-		} else {
-			await Promise.all(entries.map((entry) => this.storage.saveLog(entry)));
-		}
-
-		for (const entry of entries) {
-			this.broadcast({ type: 'log', payload: entry, timestamp: Date.now() });
-		}
-	}
-
-	/**
-	 * Record log entries in batch.
-	 * More efficient than individual calls for database storage.
-	 *
-	 * @example
-	 * await telescope.log([
-	 *   { level: 'info', message: 'Request started' },
-	 *   { level: 'debug', message: 'Processing...', context: { step: 1 } },
-	 * ]);
-	 */
-	async log(
-		entries: Array<{
-			level: 'debug' | 'info' | 'warn' | 'error';
-			message: string;
-			context?: Record<string, unknown>;
-			requestId?: string;
-		}>,
-	): Promise<void> {
-		if (!this.options.enabled || entries.length === 0) return;
-
-		const timestamp = new Date();
-		const logEntries: LogEntry[] = entries.map((e) => {
-			const entry: LogEntry = {
-				id: nanoid(),
-				level: e.level,
-				message: e.message,
-				context: e.context,
-				requestId: e.requestId,
-				timestamp,
-			};
-			return this.redactor ? this.redactor(entry) : entry;
-		});
-
-		await this.saveLogEntries(logEntries);
-	}
-
-	/**
-	 * Log a debug message
-	 */
-	async debug(
-		message: string,
-		context?: Record<string, unknown>,
-		requestId?: string,
-	): Promise<void> {
-		return this.logSingle('debug', message, context, requestId);
-	}
-
-	/**
-	 * Log an info message
-	 */
-	async info(
-		message: string,
-		context?: Record<string, unknown>,
-		requestId?: string,
-	): Promise<void> {
-		return this.logSingle('info', message, context, requestId);
-	}
-
-	/**
-	 * Log a warning message
-	 */
-	async warn(
-		message: string,
-		context?: Record<string, unknown>,
-		requestId?: string,
-	): Promise<void> {
-		return this.logSingle('warn', message, context, requestId);
-	}
-
-	/**
-	 * Log an error message
-	 */
-	async error(
-		message: string,
-		context?: Record<string, unknown>,
-		requestId?: string,
-	): Promise<void> {
-		return this.logSingle('error', message, context, requestId);
-	}
-
-	private async logSingle(
-		level: LogEntry['level'],
-		message: string,
-		context?: Record<string, unknown>,
-		requestId?: string,
-	): Promise<void> {
-		if (!this.options.enabled) return;
-
-		let entry: LogEntry = {
-			id: nanoid(),
-			level,
-			message,
-			context,
-			requestId,
-			timestamp: new Date(),
-		};
-
-		if (this.redactor) {
-			entry = this.redactor(entry);
-		}
-
-		await this.storage.saveLog(entry);
-		this.broadcast({ type: 'log', payload: entry, timestamp: Date.now() });
-	}
-
-	/**
-	 * Record an exception
-	 */
-	async exception(error: Error, requestId?: string): Promise<void> {
-		if (!this.options.enabled) return;
-
-		const stack = this.parseStack(error.stack || '');
-
-		const entry: ExceptionEntry = {
-			id: nanoid(),
-			name: error.name,
-			message: error.message,
-			stack,
-			requestId,
-			timestamp: new Date(),
-			handled: false,
-		};
-
-		await this.storage.saveException(entry);
-		this.broadcast({
-			type: 'exception',
-			payload: entry,
-			timestamp: Date.now(),
-		});
-	}
-
-	// ============================================
-	// Public API - Data Access
-	// ============================================
-
-	/**
-	 * Get requests from storage
-	 */
-	async getRequests(options?: QueryOptions): Promise<RequestEntry[]> {
-		return this.storage.getRequests(options);
-	}
-
-	/**
-	 * Get a single request by ID
-	 */
-	async getRequest(id: string): Promise<RequestEntry | null> {
-		return this.storage.getRequest(id);
-	}
-
-	/**
-	 * Get exceptions from storage
-	 */
-	async getExceptions(options?: QueryOptions): Promise<ExceptionEntry[]> {
-		return this.storage.getExceptions(options);
-	}
-
-	/**
-	 * Get a single exception by ID
-	 */
-	async getException(id: string): Promise<ExceptionEntry | null> {
-		return this.storage.getException(id);
-	}
-
-	/**
-	 * Get logs from storage
-	 */
-	async getLogs(options?: QueryOptions): Promise<LogEntry[]> {
-		return this.storage.getLogs(options);
-	}
-
-	/**
-	 * Get storage statistics
-	 */
-	async getStats() {
-		return this.storage.getStats();
-	}
-
-	// ============================================
-	// Public API - Metrics
-	// ============================================
-
-	/**
-	 * Get aggregated request metrics
-	 */
-	getMetrics(options?: MetricsQueryOptions): RequestMetrics {
-		return this.metricsAggregator.getMetrics(options);
-	}
-
-	/**
-	 * Get metrics for individual endpoints
-	 */
-	getEndpointMetrics(options?: MetricsQueryOptions): EndpointMetrics[] {
-		return this.metricsAggregator.getEndpointMetrics(options);
-	}
-
-	/**
-	 * Get detailed metrics for a specific endpoint
-	 */
-	getEndpointDetails(
-		method: string,
-		path: string,
-		options?: MetricsQueryOptions,
-	): EndpointDetails | null {
-		return this.metricsAggregator.getEndpointDetails(method, path, options);
-	}
-
-	/**
-	 * Get status code distribution
-	 */
-	getStatusDistribution(options?: MetricsQueryOptions): StatusDistribution {
-		return this.metricsAggregator.getStatusDistribution(options);
-	}
-
-	/**
-	 * Reset metrics data
-	 */
-	resetMetrics(): void {
-		this.metricsAggregator.reset();
-	}
-
-	/**
-	 * Get a real-time metrics snapshot for broadcasting
-	 */
-	getMetricsSnapshot(): MetricsSnapshot {
-		const metrics = this.metricsAggregator.getMetrics();
-		const statusDist = this.metricsAggregator.getStatusDistribution();
-
-		return {
-			timestamp: Date.now(),
-			totalRequests: metrics.totalRequests,
-			requestsPerSecond: metrics.requestsPerSecond,
-			avgDuration: metrics.avgDuration,
-			errorRate: metrics.errorRate,
-			p50: metrics.p50Duration,
-			p95: metrics.p95Duration,
-			p99: metrics.p99Duration,
-			statusDistribution: statusDist,
-		};
-	}
-
-	/**
-	 * Start broadcasting metrics to WebSocket clients at a given interval.
-	 * Call this after setting up WebSocket to enable real-time metrics updates.
-	 *
-	 * @param intervalMs - Broadcast interval in milliseconds (default: 5000)
-	 */
-	startMetricsBroadcast(intervalMs = 5000): void {
-		if (this.metricsBroadcastInterval) {
-			return; // Already running
-		}
-
-		this.metricsBroadcastInterval = setInterval(() => {
-			if (this.wsClients.size > 0) {
-				const snapshot = this.getMetricsSnapshot();
-				this.broadcast({
-					type: 'metrics',
-					payload: snapshot,
-					timestamp: Date.now(),
-				});
-			}
-		}, intervalMs);
-	}
-
-	/**
-	 * Stop broadcasting metrics to WebSocket clients
-	 */
-	stopMetricsBroadcast(): void {
-		if (this.metricsBroadcastInterval) {
-			clearInterval(this.metricsBroadcastInterval);
-			this.metricsBroadcastInterval = undefined;
-		}
-	}
-
-	// ============================================
-	// Public API - WebSocket
-	// ============================================
-
-	/**
-	 * Add a WebSocket client for real-time updates
-	 */
-	addWsClient(ws: WebSocket): void {
-		this.wsClients.add(ws);
-		this.broadcast({
-			type: 'connected',
-			payload: { clientCount: this.wsClients.size },
-			timestamp: Date.now(),
-		});
-	}
-
-	/**
-	 * Remove a WebSocket client
-	 */
-	removeWsClient(ws: WebSocket): void {
-		this.wsClients.delete(ws);
-	}
-
-	/**
-	 * Broadcast an event to all connected WebSocket clients
-	 */
-	broadcast(event: TelescopeEvent): void {
-		const data = JSON.stringify(event);
-		for (const client of this.wsClients) {
-			try {
-				client.send(data);
-			} catch {
-				this.wsClients.delete(client);
-			}
-		}
-	}
-
-	// ============================================
-	// Public API - Lifecycle
-	// ============================================
-
-	/**
-	 * Manually prune old entries
-	 */
-	async prune(olderThan: Date): Promise<number> {
-		return this.storage.prune(olderThan);
-	}
-
-	/**
-	 * Clean up resources
-	 */
-	destroy(): void {
-		if (this.pruneInterval) {
-			clearInterval(this.pruneInterval);
-		}
-		this.stopMetricsBroadcast();
-		this.wsClients.clear();
-	}
-
-	// ============================================
-	// Public API - Configuration
-	// ============================================
-
-	/**
-	 * Get the telescope path
-	 */
-	get path(): string {
-		return this.options.path;
-	}
-
-	/**
-	 * Check if telescope is enabled
-	 */
-	get enabled(): boolean {
-		return this.options.enabled;
-	}
-
-	/**
-	 * Check if body recording is enabled
-	 */
-	get recordBody(): boolean {
-		return this.options.recordBody;
-	}
-
-	/**
-	 * Get max body size
-	 */
-	get maxBodySize(): number {
-		return this.options.maxBodySize;
-	}
-
-	/**
-	 * Check if a path should be ignored
-	 */
-	shouldIgnore(path: string): boolean {
-		// Always ignore telescope's own routes
-		if (path.startsWith(this.options.path)) {
-			return true;
-		}
-
-		return this.options.ignorePatterns.some((pattern) => {
-			if (pattern.includes('*')) {
-				const regex = new RegExp(
-					`^${pattern.replace(/\*/g, '.*').replace(/\?/g, '.')}$`,
-				);
-				return regex.test(path);
-			}
-			return path.startsWith(pattern);
-		});
-	}
-
-	// ============================================
-	// Private Methods
-	// ============================================
-
-	private normalizeOptions(
-		options: TelescopeOptions,
-	): NormalizedTelescopeOptions {
-		return {
-			storage: options.storage,
-			enabled: options.enabled ?? true,
-			path: options.path ?? '/__telescope',
-			recordBody: options.recordBody ?? true,
-			maxBodySize: options.maxBodySize ?? 64 * 1024, // 64KB
-			ignorePatterns: options.ignorePatterns ?? [],
-			pruneAfterHours: options.pruneAfterHours,
-			getRequestId: options.getRequestId,
-		};
-	}
-
-	private parseStack(stack: string): StackFrame[] {
-		const lines = stack.split('\n').slice(1);
-		const frames: StackFrame[] = [];
-
-		for (const line of lines) {
-			// Match: "    at functionName (file:line:column)"
-			// or: "    at file:line:column"
-			const match =
-				line.match(/at\s+(.+?)\s+\((.+):(\d+):(\d+)\)/) ||
-				line.match(/at\s+(.+):(\d+):(\d+)/);
-
-			if (match) {
-				if (
-					match.length === 5 &&
-					match[1] &&
-					match[2] &&
-					match[3] &&
-					match[4]
-				) {
-					// Has function name
-					frames.push({
-						function: match[1],
-						file: match[2],
-						line: parseInt(match[3], 10),
-						column: parseInt(match[4], 10),
-						isApp: !match[2].includes('node_modules'),
-					});
-				} else if (match.length === 4 && match[1] && match[2] && match[3]) {
-					// No function name
-					frames.push({
-						function: '<anonymous>',
-						file: match[1],
-						line: parseInt(match[2], 10),
-						column: parseInt(match[3], 10),
-						isApp: !match[1].includes('node_modules'),
-					});
-				}
-			}
-		}
-
-		return frames;
-	}
-
-	private async autoPrune(): Promise<void> {
-		if (!this.options.pruneAfterHours) return;
-
-		const olderThan = new Date(
-			Date.now() - this.options.pruneAfterHours * 60 * 60 * 1000,
-		);
-		await this.storage.prune(olderThan);
-	}
-}