@comprehend/telemetry-node 0.1.3 → 0.2.0

package/src/ComprehendDevSpanProcessor.test.ts

@@ -0,0 +1,626 @@
+import { SpanKind, SpanStatusCode } from '@opentelemetry/api';
+import { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { ComprehendDevSpanProcessor, matchSpanRule } from './ComprehendDevSpanProcessor';
+import { WebSocketConnection } from './WebSocketConnection';
+import {
+    NewObservedServiceMessage,
+    NewObservedHttpRouteMessage,
+    NewObservedDatabaseMessage,
+    NewObservedHttpServiceMessage,
+    NewObservedHttpRequestMessage,
+    NewObservedDatabaseConnectionMessage,
+    ObservationMessage,
+    HttpServerObservation,
+    HttpClientObservation,
+    DatabaseQueryMessage,
+    TraceSpansMessage,
+    CustomObservation,
+    ObservationInputMessage,
+    SpanMatcherRule,
+} from './wire-protocol';
+
+// Mock the WebSocketConnection
+jest.mock('./WebSocketConnection');
+
+const MockedWebSocketConnection = WebSocketConnection as jest.MockedClass<typeof WebSocketConnection>;
+
+describe('ComprehendDevSpanProcessor', () => {
+    let processor: ComprehendDevSpanProcessor;
+    let mockConnection: jest.Mocked<WebSocketConnection>;
+    let sentMessages: any[];
+    let seqCounter: number;
+
+    beforeEach(() => {
+        MockedWebSocketConnection.mockClear();
+        sentMessages = [];
+        seqCounter = 1;
+
+        mockConnection = {
+            sendMessage: jest.fn((message: any) => {
+                sentMessages.push(message);
+            }),
+            setProcessContext: jest.fn(),
+            nextSeq: jest.fn(() => seqCounter++),
+            close: jest.fn()
+        } as any;
+
+        processor = new ComprehendDevSpanProcessor(mockConnection);
+    });
+
+    afterEach(() => {
+        processor.shutdown();
+    });
+
+    function createMockSpan(options: {
+        name?: string;
+        kind?: SpanKind;
+        attributes?: Record<string, any>;
+        resourceAttributes?: Record<string, any>;
+        status?: { code: SpanStatusCode; message?: string };
+        events?: Array<{ name: string; attributes?: Record<string, any> }>;
+        startTime?: [number, number];
+        duration?: [number, number];
+        traceId?: string;
+        spanId?: string;
+        parentSpanId?: string;
+    } = {}): ReadableSpan {
+        const {
+            name = 'test-span',
+            kind = SpanKind.INTERNAL,
+            attributes = {},
+            resourceAttributes = { 'service.name': 'test-service' },
+            status = { code: SpanStatusCode.OK },
+            events = [],
+            startTime = [1700000000, 123456789],
+            duration = [0, 100000000],
+            traceId = 'abc123trace',
+            spanId = 'def456span',
+            parentSpanId,
+        } = options;
+
+        return {
+            name,
+            kind,
+            attributes,
+            resource: {
+                attributes: resourceAttributes
+            } as any,
+            status,
+            events: events.map(e => ({
+                name: e.name,
+                attributes: e.attributes || {},
+                time: startTime
+            })),
+            startTime,
+            duration,
+            spanContext: () => ({ traceId, spanId, traceFlags: 1 }),
+            parentSpanContext: parentSpanId ? { spanId: parentSpanId, traceId: '', traceFlags: 0 } : undefined,
+        } as any;
+    }
+
+    describe('Service Discovery', () => {
+        it('should register a new service and send NewObservedServiceMessage', () => {
+            const span = createMockSpan({
+                resourceAttributes: {
+                    'service.name': 'my-api',
+                    'service.namespace': 'production',
+                    'deployment.environment': 'prod'
+                }
+            });
+
+            processor.onEnd(span);
+
+            const serviceMsg = sentMessages.find(m => m.event === 'new-entity' && m.type === 'service');
+            expect(serviceMsg).toMatchObject({
+                event: 'new-entity',
+                type: 'service',
+                name: 'my-api',
+                namespace: 'production',
+                environment: 'prod'
+            });
+            expect(serviceMsg.hash).toBeDefined();
+        });
+
+        it('should not duplicate service registrations', () => {
+            const span1 = createMockSpan({ resourceAttributes: { 'service.name': 'my-api' } });
+            const span2 = createMockSpan({ resourceAttributes: { 'service.name': 'my-api' } });
+
+            processor.onEnd(span1);
+            processor.onEnd(span2);
+
+            const serviceMessages = sentMessages.filter(m => m.event === 'new-entity' && m.type === 'service');
+            expect(serviceMessages).toHaveLength(1);
+        });
+
+        it('should handle service without namespace and environment', () => {
+            const span = createMockSpan({ resourceAttributes: { 'service.name': 'simple-service' } });
+
+            processor.onEnd(span);
+
+            const serviceMsg = sentMessages.find(m => m.type === 'service');
+            expect(serviceMsg).toMatchObject({ name: 'simple-service' });
+            expect(serviceMsg).not.toHaveProperty('namespace');
+            expect(serviceMsg).not.toHaveProperty('environment');
+        });
+
+        it('should ignore spans without service.name', () => {
+            const span = createMockSpan({ resourceAttributes: {} });
+
+            processor.onEnd(span);
+
+            expect(sentMessages).toHaveLength(0);
+        });
+
+        it('should set process context on first service discovery', () => {
+            const span = createMockSpan({
+                resourceAttributes: {
+                    'service.name': 'my-api',
+                    'deployment.environment': 'prod',
+                }
+            });
+
+            processor.onEnd(span);
+
+            expect(mockConnection.setProcessContext).toHaveBeenCalledTimes(1);
+            const [hash, resources] = mockConnection.setProcessContext.mock.calls[0];
+            expect(hash).toBeDefined();
+            expect(resources['service.name']).toBe('my-api');
+            expect(resources['deployment.environment']).toBe('prod');
+        });
+
+        it('should only set process context once', () => {
+            const span1 = createMockSpan({ resourceAttributes: { 'service.name': 'svc1' } });
+            const span2 = createMockSpan({ resourceAttributes: { 'service.name': 'svc2' } });
+
+            processor.onEnd(span1);
+            processor.onEnd(span2);
+
+            expect(mockConnection.setProcessContext).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('HTTP Route Processing', () => {
+        it('should process HTTP server spans with V2 observations (spanId, traceId)', () => {
+            const span = createMockSpan({
+                kind: SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/users/{id}',
+                    'http.method': 'GET',
+                    'http.target': '/api/users/123',
+                    'http.status_code': 200
+                },
+                traceId: 'trace-abc',
+                spanId: 'span-123',
+            });
+
+            processor.onEnd(span);
+
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            const observation = observationMessage.observations[0] as HttpServerObservation;
+            expect(observation).toMatchObject({
+                type: 'http-server',
+                path: '/api/users/123',
+                status: 200,
+                spanId: 'span-123',
+                traceId: 'trace-abc',
+            });
+        });
+
+        it('should not duplicate route registrations', () => {
+            const span1 = createMockSpan({
+                kind: SpanKind.SERVER,
+                attributes: { 'http.route': '/api/users', 'http.method': 'GET', 'http.status_code': 200 }
+            });
+            const span2 = createMockSpan({
+                kind: SpanKind.SERVER,
+                attributes: { 'http.route': '/api/users', 'http.method': 'GET', 'http.status_code': 200 }
+            });
+
+            processor.onEnd(span1);
+            processor.onEnd(span2);
+
+            const routeMessages = sentMessages.filter(m => m.type === 'http-route');
+            expect(routeMessages).toHaveLength(1);
+        });
+    });
+
+    describe('HTTP Client Processing', () => {
+        it('should process HTTP client spans with V2 observations', () => {
+            const span = createMockSpan({
+                kind: SpanKind.CLIENT,
+                attributes: {
+                    'http.url': 'https://api.external.com/v1/data',
+                    'http.method': 'GET',
+                    'http.status_code': 200
+                },
+                traceId: 'trace-xyz',
+                spanId: 'span-456',
+            });
+
+            processor.onEnd(span);
+
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            const observation = observationMessage.observations[0] as HttpClientObservation;
+            expect(observation).toMatchObject({
+                type: 'http-client',
+                path: '/v1/data',
+                method: 'GET',
+                status: 200,
+                spanId: 'span-456',
+                traceId: 'trace-xyz',
+            });
+        });
+    });
+
+    describe('Database Processing', () => {
+        it('should send DatabaseQueryMessage for SQL queries (server-side analysis)', () => {
+            const span = createMockSpan({
+                attributes: {
+                    'db.system': 'postgresql',
+                    'db.statement': 'SELECT * FROM users WHERE id = $1',
+                    'db.name': 'myapp',
+                    'net.peer.name': 'localhost',
+                    'db.response.returned_rows': 1
+                }
+            });
+
+            processor.onEnd(span);
+
+            const dbQueryMsg = sentMessages.find(m => m.event === 'db-query') as DatabaseQueryMessage;
+            expect(dbQueryMsg).toMatchObject({
+                event: 'db-query',
+                query: 'SELECT * FROM users WHERE id = $1',
+                returnedRows: 1,
+            });
+            expect(dbQueryMsg.from).toBeDefined();
+            expect(dbQueryMsg.to).toBeDefined();
+            expect(dbQueryMsg.seq).toBeDefined();
+        });
+
+        it('should create database entity and connection interaction', () => {
+            const span = createMockSpan({
+                attributes: {
+                    'db.system': 'postgresql',
+                    'db.name': 'myapp',
+                    'net.peer.name': 'db.example.com',
+                    'net.peer.port': 5432
+                }
+            });
+
+            processor.onEnd(span);
+
+            const databaseMessage = sentMessages.find(m => m.type === 'database');
+            expect(databaseMessage).toMatchObject({
+                event: 'new-entity',
+                type: 'database',
+                system: 'postgresql',
+                name: 'myapp',
+                host: 'db.example.com',
+                port: 5432
+            });
+
+            const connectionMessage = sentMessages.find(m => m.type === 'db-connection');
+            expect(connectionMessage).toMatchObject({
+                event: 'new-interaction',
+                type: 'db-connection',
+            });
+        });
+
+        it('should not send db-query for non-SQL database systems', () => {
+            const span = createMockSpan({
+                attributes: {
+                    'db.system': 'mongodb',
+                    'db.statement': 'db.users.find({})',
+                    'db.name': 'myapp'
+                }
+            });
+
+            processor.onEnd(span);
+
+            const dbQueryMessages = sentMessages.filter(m => m.event === 'db-query');
+            expect(dbQueryMessages).toHaveLength(0);
+        });
+    });
+
+    describe('Trace Span Reporting', () => {
+        it('should send TraceSpansMessage for every span', () => {
+            const span = createMockSpan({
+                name: 'GET /api/users',
+                kind: SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/users',
+                    'http.method': 'GET',
+                    'http.status_code': 200,
+                },
+                traceId: 'trace-001',
+                spanId: 'span-001',
+                parentSpanId: 'span-000',
+            });
+
+            processor.onEnd(span);
+
+            const traceSpanMsg = sentMessages.find(m => m.event === 'tracespans') as TraceSpansMessage;
+            expect(traceSpanMsg).toBeDefined();
+            expect(traceSpanMsg.data).toHaveLength(1);
+            expect(traceSpanMsg.data[0]).toMatchObject({
+                trace: 'trace-001',
+                span: 'span-001',
+                parent: 'span-000',
+                name: 'GET /api/users',
+            });
+        });
+
+        it('should use empty string for parent when no parentSpanId', () => {
+            const span = createMockSpan({
+                traceId: 'trace-root',
+                spanId: 'span-root',
+                // no parentSpanId
+            });
+
+            processor.onEnd(span);
+
+            const traceSpanMsg = sentMessages.find(m => m.event === 'tracespans') as TraceSpansMessage;
+            expect(traceSpanMsg.data[0].parent).toBe('');
+        });
+
+        it('should send trace span even for internal spans with no http/db attributes', () => {
+            const span = createMockSpan({
+                name: 'internal-operation',
+                kind: SpanKind.INTERNAL,
+            });
+
+            processor.onEnd(span);
+
+            const traceSpanMsg = sentMessages.find(m => m.event === 'tracespans');
+            expect(traceSpanMsg).toBeDefined();
+        });
+    });
+
+    describe('Custom Span Observation Matching', () => {
+        it('should match spans by type rule', () => {
+            processor.updateCustomMetrics([{
+                type: 'span',
+                rule: { kind: 'type', value: 'server' },
+                subject: 'custom-server-obs',
+            }]);
+
+            const span = createMockSpan({
+                kind: SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/test',
+                    'http.method': 'GET',
+                    'http.status_code': 200,
+                },
+            });
+
+            processor.onEnd(span);
+
+            const customObs = sentMessages
+                .filter(m => m.event === 'observations')
+                .flatMap((m: ObservationMessage) => m.observations)
+                .find((o: any) => o.type === 'custom') as CustomObservation;
+
+            expect(customObs).toBeDefined();
+            expect(customObs.subject).toBe('custom-server-obs');
+            expect(customObs.id).toBe('custom-server-obs');
+            expect(customObs.attributes).toBeDefined();
+        });
+
+        it('should match spans by attribute-present rule', () => {
+            processor.updateCustomMetrics([{
+                type: 'span',
+                rule: { kind: 'attribute-present', key: 'custom.attr' },
+                subject: 'has-custom-attr',
+            }]);
+
+            const spanWith = createMockSpan({ attributes: { 'custom.attr': 'value' } });
+            const spanWithout = createMockSpan({ attributes: {} });
+
+            processor.onEnd(spanWith);
+            processor.onEnd(spanWithout);
+
+            const customObs = sentMessages
+                .filter(m => m.event === 'observations')
+                .flatMap((m: ObservationMessage) => m.observations)
+                .filter((o: any) => o.type === 'custom');
+
+            expect(customObs).toHaveLength(1);
+        });
+
+        it('should match spans by compound all rule', () => {
+            processor.updateCustomMetrics([{
+                type: 'span',
+                rule: {
+                    kind: 'all',
+                    rules: [
+                        { kind: 'type', value: 'client' },
+                        { kind: 'attribute-equals', key: 'rpc.system', value: 'grpc' },
+                    ]
+                },
+                subject: 'grpc-client',
+            }]);
+
+            const matchingSpan = createMockSpan({
+                kind: SpanKind.CLIENT,
+                attributes: { 'rpc.system': 'grpc', 'http.url': 'http://x' },
+            });
+            const nonMatchingSpan = createMockSpan({
+                kind: SpanKind.CLIENT,
+                attributes: { 'rpc.system': 'thrift' },
+            });
+
+            processor.onEnd(matchingSpan);
+            processor.onEnd(nonMatchingSpan);
+
+            const customObs = sentMessages
+                .filter(m => m.event === 'observations')
+                .flatMap((m: ObservationMessage) => m.observations)
+                .filter((o: any) => o.type === 'custom');
+
+            expect(customObs).toHaveLength(1);
+            expect(customObs[0].subject).toBe('grpc-client');
+        });
+
+        it('should not create custom observations when no specs match', () => {
+            processor.updateCustomMetrics([{
+                type: 'span',
+                rule: { kind: 'type', value: 'internal' },
+                subject: 'internal-only',
+            }]);
+
+            const span = createMockSpan({ kind: SpanKind.SERVER });
+            processor.onEnd(span);
+
+            const customObs = sentMessages
+                .filter(m => m.event === 'observations')
+                .flatMap((m: ObservationMessage) => m.observations)
+                .filter((o: any) => o.type === 'custom');
+
+            expect(customObs).toHaveLength(0);
+        });
+    });
+
+    describe('Error Handling', () => {
+        it('should extract error information from exception events', () => {
+            const span = createMockSpan({
+                kind: SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/error',
+                    'http.method': 'GET',
+                    'http.status_code': 500
+                },
+                events: [{
+                    name: 'exception',
+                    attributes: {
+                        'exception.message': 'Database connection failed',
+                        'exception.type': 'ConnectionError',
+                        'exception.stacktrace': 'Error at line 42\n  at method()'
+                    }
+                }],
+                status: { code: SpanStatusCode.ERROR, message: 'Internal server error' }
+            });
+
+            processor.onEnd(span);
+
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            const observation = observationMessage.observations[0];
+            expect(observation).toMatchObject({
+                errorMessage: 'Database connection failed',
+                errorType: 'ConnectionError',
+                stack: 'Error at line 42\n  at method()'
+            });
+        });
+    });
+
+    describe('Sequence Numbers', () => {
+        it('should use connection.nextSeq() for observation messages', () => {
+            const span1 = createMockSpan({
+                kind: SpanKind.SERVER,
+                attributes: { 'http.route': '/api/test1', 'http.method': 'GET', 'http.status_code': 200 }
+            });
+            const span2 = createMockSpan({
+                kind: SpanKind.SERVER,
+                attributes: { 'http.route': '/api/test2', 'http.method': 'GET', 'http.status_code': 200 }
+            });
+
+            processor.onEnd(span1);
+            processor.onEnd(span2);
+
+            // nextSeq is called for observations AND tracespans
+            expect(mockConnection.nextSeq).toHaveBeenCalled();
+
+            const observationMessages = sentMessages.filter(m => m.event === 'observations');
+            // Each should have a unique seq
+            const seqs = observationMessages.map((m: any) => m.seq);
+            expect(new Set(seqs).size).toBe(seqs.length);
+        });
+    });
+
+    describe('Processor Lifecycle', () => {
+        it('should handle forceFlush without error', async () => {
+            await expect(processor.forceFlush()).resolves.toBeUndefined();
+        });
+
+        it('onStart should be a no-op', () => {
+            expect(() => processor.onStart({} as any, {} as any)).not.toThrow();
+        });
+    });
+});
+
+describe('matchSpanRule', () => {
+    function createSpan(kind: SpanKind, attributes: Record<string, any> = {}): ReadableSpan {
+        return {
+            kind,
+            attributes,
+            name: 'test',
+            spanContext: () => ({ traceId: '', spanId: '', traceFlags: 0 }),
+        } as any;
+    }
+
+    it('should match type rule', () => {
+        expect(matchSpanRule(createSpan(SpanKind.SERVER), { kind: 'type', value: 'server' })).toBe(true);
+        expect(matchSpanRule(createSpan(SpanKind.CLIENT), { kind: 'type', value: 'server' })).toBe(false);
+        expect(matchSpanRule(createSpan(SpanKind.INTERNAL), { kind: 'type', value: 'internal' })).toBe(true);
+    });
+
+    it('should match attribute-present rule', () => {
+        expect(matchSpanRule(createSpan(SpanKind.INTERNAL, { 'foo': 'bar' }), { kind: 'attribute-present', key: 'foo' })).toBe(true);
+        expect(matchSpanRule(createSpan(SpanKind.INTERNAL, {}), { kind: 'attribute-present', key: 'foo' })).toBe(false);
+    });
+
+    it('should match attribute-absent rule', () => {
+        expect(matchSpanRule(createSpan(SpanKind.INTERNAL, {}), { kind: 'attribute-absent', key: 'foo' })).toBe(true);
+        expect(matchSpanRule(createSpan(SpanKind.INTERNAL, { 'foo': 'bar' }), { kind: 'attribute-absent', key: 'foo' })).toBe(false);
+    });
+
+    it('should match attribute-equals rule', () => {
+        expect(matchSpanRule(createSpan(SpanKind.INTERNAL, { 'k': 'v' }), { kind: 'attribute-equals', key: 'k', value: 'v' })).toBe(true);
+        expect(matchSpanRule(createSpan(SpanKind.INTERNAL, { 'k': 'other' }), { kind: 'attribute-equals', key: 'k', value: 'v' })).toBe(false);
+    });
+
+    it('should match attribute-not-equals rule', () => {
+        expect(matchSpanRule(createSpan(SpanKind.INTERNAL, { 'k': 'other' }), { kind: 'attribute-not-equals', key: 'k', value: 'v' })).toBe(true);
+        expect(matchSpanRule(createSpan(SpanKind.INTERNAL, { 'k': 'v' }), { kind: 'attribute-not-equals', key: 'k', value: 'v' })).toBe(false);
+    });
+
+    it('should match all rule', () => {
+        const rule: SpanMatcherRule = {
+            kind: 'all',
+            rules: [
+                { kind: 'type', value: 'server' },
+                { kind: 'attribute-present', key: 'http.route' },
+            ]
+        };
+        expect(matchSpanRule(createSpan(SpanKind.SERVER, { 'http.route': '/api' }), rule)).toBe(true);
+        expect(matchSpanRule(createSpan(SpanKind.SERVER, {}), rule)).toBe(false);
+        expect(matchSpanRule(createSpan(SpanKind.CLIENT, { 'http.route': '/api' }), rule)).toBe(false);
+    });
+
+    it('should match any rule', () => {
+        const rule: SpanMatcherRule = {
+            kind: 'any',
+            rules: [
+                { kind: 'type', value: 'server' },
+                { kind: 'type', value: 'client' },
+            ]
+        };
+        expect(matchSpanRule(createSpan(SpanKind.SERVER), rule)).toBe(true);
+        expect(matchSpanRule(createSpan(SpanKind.CLIENT), rule)).toBe(true);
+        expect(matchSpanRule(createSpan(SpanKind.INTERNAL), rule)).toBe(false);
+    });
+
+    it('should handle nested rules', () => {
+        const rule: SpanMatcherRule = {
+            kind: 'all',
+            rules: [
+                { kind: 'any', rules: [
+                    { kind: 'type', value: 'server' },
+                    { kind: 'type', value: 'client' },
+                ]},
+                { kind: 'attribute-equals', key: 'rpc.system', value: 'grpc' },
+            ]
+        };
+        expect(matchSpanRule(createSpan(SpanKind.SERVER, { 'rpc.system': 'grpc' }), rule)).toBe(true);
+        expect(matchSpanRule(createSpan(SpanKind.INTERNAL, { 'rpc.system': 'grpc' }), rule)).toBe(false);
+    });
+});