@geekmidas/telescope 10.0.0-alpha.99 → 10.0.0

package/src/instrumentation/__tests__/otel.spec.ts

@@ -0,0 +1,291 @@
+import { trace } from '@opentelemetry/api';
+import {
+	BasicTracerProvider,
+	InMemorySpanExporter,
+	SimpleSpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import type { Context } from 'aws-lambda';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { OTelTelemetry } from '../otel';
+
+describe('OTelTelemetry', () => {
+	let exporter: InMemorySpanExporter;
+	let provider: BasicTracerProvider;
+
+	const mockLambdaContext: Context = {
+		awsRequestId: 'test-request-id',
+		functionName: 'test-function',
+		functionVersion: '1',
+		invokedFunctionArn: 'arn:aws:lambda:us-east-1:123456789:function:test',
+		memoryLimitInMB: '128',
+		logGroupName: '/aws/lambda/test',
+		logStreamName: '2024/01/01/[$LATEST]abc123',
+		callbackWaitsForEmptyEventLoop: true,
+		getRemainingTimeInMillis: () => 30000,
+		done: () => {},
+		fail: () => {},
+		succeed: () => {},
+	};
+
+	beforeEach(() => {
+		exporter = new InMemorySpanExporter();
+		provider = new BasicTracerProvider();
+		provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+		provider.register();
+	});
+
+	afterEach(async () => {
+		exporter.reset();
+		await provider.shutdown();
+		trace.disable();
+	});
+
+	describe('API Gateway v2 events', () => {
+		it('should create span for API Gateway v2 request', () => {
+			const telemetry = new OTelTelemetry();
+
+			const event = {
+				requestContext: {
+					http: {
+						method: 'GET',
+						path: '/api/users',
+						sourceIp: '192.168.1.1',
+						userAgent: 'test-agent',
+					},
+					requestId: 'apigw-request-id',
+				},
+				rawPath: '/api/users',
+				rawQueryString: 'page=1',
+				headers: { host: 'api.example.com' },
+			};
+
+			const ctx = telemetry.onRequestStart({
+				event,
+				context: mockLambdaContext,
+			});
+
+			telemetry.onRequestEnd(ctx, { statusCode: 200 });
+
+			const spans = exporter.getFinishedSpans();
+			expect(spans).toHaveLength(1);
+			expect(spans[0].name).toBe('GET /api/users');
+			expect(spans[0].attributes['http.request.method']).toBe('GET');
+			expect(spans[0].attributes['url.path']).toBe('/api/users');
+			expect(spans[0].attributes['faas.invocation_id']).toBe('test-request-id');
+			expect(spans[0].attributes['faas.name']).toBe('test-function');
+		});
+
+		it('should record error on request failure', () => {
+			const telemetry = new OTelTelemetry();
+
+			const event = {
+				requestContext: {
+					http: { method: 'POST', path: '/api/users', sourceIp: '10.0.0.1' },
+					requestId: 'req-123',
+				},
+				rawPath: '/api/users',
+				headers: {},
+			};
+
+			const ctx = telemetry.onRequestStart({
+				event,
+				context: mockLambdaContext,
+			});
+
+			telemetry.onRequestError(ctx, new Error('Database connection failed'));
+
+			const spans = exporter.getFinishedSpans();
+			expect(spans).toHaveLength(1);
+			expect(spans[0].status.code).toBe(2); // SpanStatusCode.ERROR
+			expect(spans[0].events).toHaveLength(1);
+			expect(spans[0].events[0].name).toBe('exception');
+		});
+	});
+
+	describe('API Gateway v1 events', () => {
+		it('should create span for API Gateway v1 request', () => {
+			const telemetry = new OTelTelemetry();
+
+			const event = {
+				httpMethod: 'POST',
+				path: '/api/orders',
+				resource: '/api/orders',
+				requestContext: {
+					requestId: 'v1-request-id',
+					identity: { sourceIp: '10.0.0.1' },
+				},
+				headers: {
+					Host: 'api.example.com',
+					'User-Agent': 'test-client',
+				},
+			};
+
+			const ctx = telemetry.onRequestStart({
+				event,
+				context: mockLambdaContext,
+			});
+
+			telemetry.onRequestEnd(ctx, { statusCode: 201 });
+
+			const spans = exporter.getFinishedSpans();
+			expect(spans).toHaveLength(1);
+			expect(spans[0].attributes['http.request.method']).toBe('POST');
+			expect(spans[0].attributes['url.path']).toBe('/api/orders');
+			expect(spans[0].attributes['http.route']).toBe('/api/orders');
+		});
+	});
+
+	describe('options', () => {
+		it('should record request body when recordBody is true', () => {
+			const telemetry = new OTelTelemetry({ recordBody: true });
+
+			const event = {
+				requestContext: {
+					http: { method: 'POST', path: '/api/users', sourceIp: '10.0.0.1' },
+					requestId: 'req-123',
+				},
+				rawPath: '/api/users',
+				headers: {},
+				body: JSON.stringify({ name: 'John', email: 'john@example.com' }),
+			};
+
+			const ctx = telemetry.onRequestStart({
+				event,
+				context: mockLambdaContext,
+			});
+
+			telemetry.onRequestEnd(ctx, { statusCode: 200 });
+
+			const spans = exporter.getFinishedSpans();
+			expect(spans[0].attributes['http.request.body']).toContain('John');
+		});
+
+		it('should record response body when recordResponseBody is true', () => {
+			const telemetry = new OTelTelemetry({ recordResponseBody: true });
+
+			const event = {
+				requestContext: {
+					http: { method: 'GET', path: '/api/users', sourceIp: '10.0.0.1' },
+					requestId: 'req-123',
+				},
+				rawPath: '/api/users',
+				headers: {},
+			};
+
+			const ctx = telemetry.onRequestStart({
+				event,
+				context: mockLambdaContext,
+			});
+
+			telemetry.onRequestEnd(ctx, {
+				statusCode: 200,
+				body: JSON.stringify({ users: [{ id: '1', name: 'John' }] }),
+			});
+
+			const spans = exporter.getFinishedSpans();
+			expect(spans[0].attributes['http.response.body']).toContain('John');
+		});
+
+		it('should extract user ID using custom function', () => {
+			const telemetry = new OTelTelemetry({
+				getUserId: (event) => event.requestContext?.authorizer?.userId,
+			});
+
+			const event = {
+				requestContext: {
+					http: { method: 'GET', path: '/api/profile', sourceIp: '10.0.0.1' },
+					requestId: 'req-123',
+					authorizer: { userId: 'user-456' },
+				},
+				rawPath: '/api/profile',
+				headers: {},
+			};
+
+			const ctx = telemetry.onRequestStart({
+				event,
+				context: mockLambdaContext,
+			});
+
+			telemetry.onRequestEnd(ctx, { statusCode: 200 });
+
+			const spans = exporter.getFinishedSpans();
+			expect(spans[0].attributes['enduser.id']).toBe('user-456');
+		});
+
+		it('should extract endpoint name using custom function', () => {
+			const telemetry = new OTelTelemetry({
+				getEndpointName: (event) => event.endpointName,
+			});
+
+			const event = {
+				requestContext: {
+					http: { method: 'GET', path: '/api/users', sourceIp: '10.0.0.1' },
+					requestId: 'req-123',
+				},
+				rawPath: '/api/users',
+				headers: {},
+				endpointName: 'ListUsers',
+			};
+
+			const ctx = telemetry.onRequestStart({
+				event,
+				context: mockLambdaContext,
+			});
+
+			telemetry.onRequestEnd(ctx, { statusCode: 200 });
+
+			const spans = exporter.getFinishedSpans();
+			expect(spans[0].attributes['endpoint.name']).toBe('ListUsers');
+		});
+	});
+
+	describe('ALB events', () => {
+		it('should create span for ALB request', () => {
+			const telemetry = new OTelTelemetry();
+
+			const event = {
+				httpMethod: 'GET',
+				path: '/health',
+				headers: {
+					host: 'alb.example.com',
+					'user-agent': 'ALB-HealthChecker',
+					'x-forwarded-for': '10.0.0.1, 10.0.0.2',
+				},
+			};
+
+			const ctx = telemetry.onRequestStart({
+				event,
+				context: mockLambdaContext,
+			});
+
+			telemetry.onRequestEnd(ctx, { statusCode: 200 });
+
+			const spans = exporter.getFinishedSpans();
+			expect(spans).toHaveLength(1);
+			expect(spans[0].attributes['http.request.method']).toBe('GET');
+			expect(spans[0].attributes['url.path']).toBe('/health');
+		});
+	});
+
+	describe('direct Lambda invocation', () => {
+		it('should create span for direct invocation', () => {
+			const telemetry = new OTelTelemetry();
+
+			const event = {
+				action: 'processJob',
+				data: { jobId: '123' },
+			};
+
+			const ctx = telemetry.onRequestStart({
+				event,
+				context: mockLambdaContext,
+			});
+
+			telemetry.onRequestEnd(ctx, { statusCode: 200 });
+
+			const spans = exporter.getFinishedSpans();
+			expect(spans).toHaveLength(1);
+			expect(spans[0].attributes['http.request.method']).toBe('INVOKE');
+		});
+	});
+});

package/src/instrumentation/__tests__/tracing.spec.ts

@@ -0,0 +1,208 @@
+import { trace } from '@opentelemetry/api';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import {
+	addSpanEvent,
+	createSpan,
+	getActiveSpan,
+	getSpanId,
+	getTraceId,
+	recordException,
+	setSpanAttributes,
+	withSpan,
+	withSpanSync,
+} from '../tracing';
+
+describe('Tracing Utilities', () => {
+	let provider: NodeTracerProvider;
+
+	beforeAll(() => {
+		// Register a real tracer provider for tests
+		provider = new NodeTracerProvider();
+		provider.register();
+	});
+
+	afterAll(async () => {
+		await provider.shutdown();
+		// Reset to default noop provider
+		trace.disable();
+	});
+	describe('createSpan', () => {
+		it('should create a new span', () => {
+			const span = createSpan('test-span');
+			expect(span).toBeDefined();
+			expect(span.spanContext().spanId).toBeDefined();
+			span.end();
+		});
+
+		it('should create span with attributes', () => {
+			const span = createSpan('test-span-attrs', { 'test.attr': 'value' });
+			expect(span).toBeDefined();
+			span.end();
+		});
+	});
+
+	describe('withSpan', () => {
+		it('should execute function within span context', async () => {
+			const result = await withSpan('async-operation', async (span) => {
+				expect(span).toBeDefined();
+				expect(span.spanContext().spanId).toBeDefined();
+				return 'result';
+			});
+
+			expect(result).toBe('result');
+		});
+
+		it('should propagate errors', async () => {
+			await expect(
+				withSpan('error-span', async () => {
+					throw new Error('Test error');
+				}),
+			).rejects.toThrow('Test error');
+		});
+
+		it('should pass attributes to span', async () => {
+			let spanReceived = false;
+			await withSpan(
+				'attr-span',
+				async (span) => {
+					spanReceived = true;
+					expect(span).toBeDefined();
+					return 'done';
+				},
+				{ 'custom.attr': 123 },
+			);
+			expect(spanReceived).toBe(true);
+		});
+	});
+
+	describe('withSpanSync', () => {
+		it('should execute synchronous function within span context', () => {
+			const result = withSpanSync('sync-operation', (span) => {
+				expect(span).toBeDefined();
+				return 42;
+			});
+
+			expect(result).toBe(42);
+		});
+
+		it('should handle errors in sync functions', () => {
+			expect(() =>
+				withSpanSync('sync-error', () => {
+					throw new Error('Sync error');
+				}),
+			).toThrow('Sync error');
+		});
+	});
+
+	describe('getActiveSpan', () => {
+		it('should return active span within withSpan', async () => {
+			await withSpan('active-span', async () => {
+				const active = getActiveSpan();
+				expect(active).toBeDefined();
+			});
+		});
+	});
+
+	describe('getTraceId and getSpanId', () => {
+		it('should return trace and span IDs within span context', async () => {
+			let traceId: string | undefined;
+			let spanId: string | undefined;
+
+			await withSpan('id-span', async (span) => {
+				traceId = getTraceId();
+				spanId = getSpanId();
+				// Verify they match the span we're in
+				expect(traceId).toBe(span.spanContext().traceId);
+				expect(spanId).toBe(span.spanContext().spanId);
+			});
+
+			expect(traceId).toBeDefined();
+			expect(traceId?.length).toBe(32); // 16 bytes hex
+			expect(spanId).toBeDefined();
+			expect(spanId?.length).toBe(16); // 8 bytes hex
+		});
+
+		it('should return undefined outside span context', () => {
+			// Outside of any span context
+			const traceId = getTraceId();
+			const spanId = getSpanId();
+			// These may be undefined if no span is active
+			expect(traceId === undefined || typeof traceId === 'string').toBe(true);
+			expect(spanId === undefined || typeof spanId === 'string').toBe(true);
+		});
+	});
+
+	describe('setSpanAttributes', () => {
+		it('should set attributes on active span', async () => {
+			await withSpan('attrs-span', async (span) => {
+				setSpanAttributes({ 'custom.key': 'custom-value', 'custom.num': 42 });
+				// Span should still be valid
+				expect(span.isRecording()).toBe(true);
+			});
+		});
+
+		it('should not throw when no active span', () => {
+			// Should not throw even when called outside span context
+			expect(() => {
+				setSpanAttributes({ key: 'value' });
+			}).not.toThrow();
+		});
+	});
+
+	describe('recordException', () => {
+		it('should record exception on active span', async () => {
+			await withSpan('exception-span', async () => {
+				const error = new Error('Test exception');
+				recordException(error);
+				// Should not throw
+			});
+		});
+
+		it('should not throw when no active span', () => {
+			expect(() => {
+				recordException(new Error('No span error'));
+			}).not.toThrow();
+		});
+	});
+
+	describe('addSpanEvent', () => {
+		it('should add event to active span', async () => {
+			await withSpan('event-span', async () => {
+				addSpanEvent('test.event', { detail: 'some detail' });
+				// Should not throw
+			});
+		});
+
+		it('should add event without attributes', async () => {
+			await withSpan('event-span-simple', async () => {
+				addSpanEvent('simple.event');
+				// Should not throw
+			});
+		});
+
+		it('should not throw when no active span', () => {
+			expect(() => {
+				addSpanEvent('orphan.event', { data: 123 });
+			}).not.toThrow();
+		});
+	});
+
+	describe('error handling edge cases', () => {
+		it('should handle non-Error exceptions in withSpan', async () => {
+			await expect(
+				withSpan('string-error-span', async () => {
+					throw 'string error'; // Non-Error exception
+				}),
+			).rejects.toBe('string error');
+		});
+
+		it('should handle non-Error exceptions in withSpanSync', () => {
+			expect(() =>
+				withSpanSync('sync-string-error', () => {
+					throw 'sync string error';
+				}),
+			).toThrow();
+		});
+	});
+});