@comprehend/telemetry-node 0.1.3 → 0.1.4

package/dist/ComprehendDevSpanProcessor.test.js

@@ -0,0 +1,674 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const api_1 = require("@opentelemetry/api");
+const ComprehendDevSpanProcessor_1 = require("./ComprehendDevSpanProcessor");
+const WebSocketConnection_1 = require("./WebSocketConnection");
+// Mock the WebSocketConnection
+jest.mock('./WebSocketConnection');
+// Mock the SQL analyzer
+jest.mock('./sql-analyzer', () => ({
+    analyzeSQL: jest.fn()
+}));
+const sql_analyzer_1 = require("./sql-analyzer");
+const mockedAnalyzeSQL = sql_analyzer_1.analyzeSQL;
+const MockedWebSocketConnection = WebSocketConnection_1.WebSocketConnection;
+describe('ComprehendDevSpanProcessor', () => {
+    let processor;
+    let mockConnection;
+    let sentMessages;
+    beforeEach(() => {
+        // Reset mocks
+        MockedWebSocketConnection.mockClear();
+        mockedAnalyzeSQL.mockClear();
+        sentMessages = [];
+        // Create mock connection instance
+        mockConnection = {
+            sendMessage: jest.fn((message) => {
+                sentMessages.push(message);
+            }),
+            close: jest.fn()
+        };
+        MockedWebSocketConnection.mockImplementation(() => mockConnection);
+        // Create processor instance
+        processor = new ComprehendDevSpanProcessor_1.ComprehendDevSpanProcessor({
+            organization: 'test-org',
+            token: 'test-token'
+        });
+    });
+    afterEach(() => {
+        processor.shutdown();
+    });
+    // Helper function to create a mock span
+    function createMockSpan(options = {}) {
+        const { name = 'test-span', kind = api_1.SpanKind.INTERNAL, attributes = {}, resourceAttributes = { 'service.name': 'test-service' }, status = { code: api_1.SpanStatusCode.OK }, events = [], startTime = [1700000000, 123456789], duration = [0, 100000000] // 100ms
+         } = options;
+        return {
+            name,
+            kind,
+            attributes,
+            resource: {
+                attributes: resourceAttributes
+            },
+            status,
+            events: events.map(e => ({
+                name: e.name,
+                attributes: e.attributes || {},
+                time: startTime
+            })),
+            startTime,
+            duration
+        };
+    }
+    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);
+            expect(sentMessages).toHaveLength(1);
+            expect(sentMessages[0]).toMatchObject({
+                event: 'new-entity',
+                type: 'service',
+                name: 'my-api',
+                namespace: 'production',
+                environment: 'prod'
+            });
+            expect(sentMessages[0].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);
+            // Should only send one service registration
+            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);
+            expect(sentMessages[0]).toMatchObject({
+                event: 'new-entity',
+                type: 'service',
+                name: 'simple-service'
+            });
+            expect(sentMessages[0]).not.toHaveProperty('namespace');
+            expect(sentMessages[0]).not.toHaveProperty('environment');
+        });
+        it('should ignore spans without service.name', () => {
+            const span = createMockSpan({
+                resourceAttributes: {}
+            });
+            processor.onEnd(span);
+            expect(sentMessages).toHaveLength(0);
+        });
+    });
+    describe('HTTP Route Processing', () => {
+        it('should process HTTP server spans and create route entities', () => {
+            const span = createMockSpan({
+                kind: api_1.SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/users/{id}',
+                    'http.method': 'GET',
+                    'http.target': '/api/users/123',
+                    'http.status_code': 200
+                }
+            });
+            processor.onEnd(span);
+            // Should have service + route messages
+            expect(sentMessages).toHaveLength(3); // service, route, observation
+            const routeMessage = sentMessages.find(m => m.type === 'http-route');
+            expect(routeMessage).toMatchObject({
+                event: 'new-entity',
+                type: 'http-route',
+                method: 'GET',
+                route: '/api/users/{id}'
+            });
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            expect(observationMessage.observations).toHaveLength(1);
+            const observation = observationMessage.observations[0];
+            expect(observation).toMatchObject({
+                type: 'http-server',
+                path: '/api/users/123',
+                status: 200
+            });
+        });
+        it('should extract path from http.url when http.target is not available', () => {
+            const span = createMockSpan({
+                kind: api_1.SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/test',
+                    'http.method': 'POST',
+                    'http.url': 'https://example.com/api/test?param=value',
+                    'http.status_code': 201
+                }
+            });
+            processor.onEnd(span);
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            const observation = observationMessage.observations[0];
+            expect(observation.path).toBe('/api/test');
+        });
+        it('should handle relative URLs in http.target', () => {
+            const span = createMockSpan({
+                kind: api_1.SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/test',
+                    'http.method': 'GET',
+                    'http.target': 'invalid-url',
+                    'http.status_code': 400
+                }
+            });
+            processor.onEnd(span);
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            const observation = observationMessage.observations[0];
+            // When used with placeholder base, 'invalid-url' becomes '/invalid-url'
+            expect(observation.path).toBe('/invalid-url');
+        });
+        it('should include optional HTTP attributes when present', () => {
+            const span = createMockSpan({
+                kind: api_1.SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/upload',
+                    'http.method': 'POST',
+                    'http.target': '/api/upload',
+                    'http.status_code': 200,
+                    'http.flavor': '1.1',
+                    'http.user_agent': 'Mozilla/5.0',
+                    'http.request_content_length': 1024,
+                    'http.response_content_length': 256
+                }
+            });
+            processor.onEnd(span);
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            const observation = observationMessage.observations[0];
+            expect(observation).toMatchObject({
+                httpVersion: '1.1',
+                userAgent: 'Mozilla/5.0',
+                requestBytes: 1024,
+                responseBytes: 256
+            });
+        });
+        it('should not duplicate route registrations', () => {
+            const span1 = createMockSpan({
+                kind: api_1.SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/users',
+                    'http.method': 'GET',
+                    'http.status_code': 200
+                }
+            });
+            const span2 = createMockSpan({
+                kind: api_1.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 and create service entities and interactions', () => {
+            const span = createMockSpan({
+                kind: api_1.SpanKind.CLIENT,
+                attributes: {
+                    'http.url': 'https://api.external.com/v1/data',
+                    'http.method': 'GET',
+                    'http.status_code': 200
+                }
+            });
+            processor.onEnd(span);
+            // Should have service + http-service + http-request + observation
+            expect(sentMessages).toHaveLength(4);
+            const httpServiceMessage = sentMessages.find(m => m.type === 'http-service');
+            expect(httpServiceMessage).toMatchObject({
+                event: 'new-entity',
+                type: 'http-service',
+                protocol: 'https',
+                host: 'api.external.com',
+                port: 443
+            });
+            const httpRequestMessage = sentMessages.find(m => m.type === 'http-request');
+            expect(httpRequestMessage).toMatchObject({
+                event: 'new-interaction',
+                type: 'http-request'
+            });
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            const observation = observationMessage.observations[0];
+            expect(observation).toMatchObject({
+                type: 'http-client',
+                path: '/v1/data',
+                method: 'GET',
+                status: 200
+            });
+        });
+        it('should handle HTTP on port 80 and HTTPS on port 443 correctly', () => {
+            const httpSpan = createMockSpan({
+                kind: api_1.SpanKind.CLIENT,
+                attributes: {
+                    'http.url': 'http://api.example.com/test',
+                    'http.method': 'GET'
+                }
+            });
+            processor.onEnd(httpSpan);
+            const httpServiceMessage = sentMessages.find(m => m.type === 'http-service');
+            expect(httpServiceMessage).toMatchObject({
+                protocol: 'http',
+                host: 'api.example.com',
+                port: 80
+            });
+        });
+        it('should handle custom ports', () => {
+            const span = createMockSpan({
+                kind: api_1.SpanKind.CLIENT,
+                attributes: {
+                    'http.url': 'https://api.example.com:8443/test',
+                    'http.method': 'POST'
+                }
+            });
+            processor.onEnd(span);
+            const httpServiceMessage = sentMessages.find(m => m.type === 'http-service');
+            expect(httpServiceMessage).toMatchObject({
+                protocol: 'https',
+                host: 'api.example.com',
+                port: 8443
+            });
+        });
+        it('should not process client spans without http.method', () => {
+            const span = createMockSpan({
+                kind: api_1.SpanKind.CLIENT,
+                attributes: {
+                    'http.url': 'https://api.example.com/test'
+                    // Missing http.method
+                }
+            });
+            processor.onEnd(span);
+            // Should still create service and interaction, but no observation
+            const observationMessages = sentMessages.filter(m => m.event === 'observations');
+            expect(observationMessages).toHaveLength(0);
+        });
+    });
+    describe('Database Processing', () => {
+        beforeEach(() => {
+            // Setup SQL analyzer mock
+            mockedAnalyzeSQL.mockReturnValue({
+                tableOperations: { users: ['SELECT'] },
+                normalizedQuery: 'SELECT * FROM users',
+                presentableQuery: 'SELECT * FROM users'
+            });
+        });
+        it('should process database spans and create database entities', () => {
+            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
+            });
+        });
+        it('should process database connection strings', () => {
+            const span = createMockSpan({
+                attributes: {
+                    'db.system': 'postgresql',
+                    'db.connection_string': 'postgresql://user:password@localhost:5432/testdb'
+                }
+            });
+            processor.onEnd(span);
+            const databaseMessage = sentMessages.find(m => m.type === 'database');
+            expect(databaseMessage).toMatchObject({
+                system: 'postgresql',
+                host: 'localhost',
+                port: 5432,
+                name: 'testdb'
+            });
+            const connectionMessage = sentMessages.find(m => m.type === 'db-connection');
+            expect(connectionMessage).toMatchObject({
+                event: 'new-interaction',
+                type: 'db-connection',
+                user: 'user'
+            });
+        });
+        it('should process SQL queries and create query interactions', () => {
+            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);
+            expect(mockedAnalyzeSQL).toHaveBeenCalledWith('SELECT * FROM users WHERE id = $1');
+            const queryMessage = sentMessages.find(m => m.type === 'db-query');
+            expect(queryMessage).toMatchObject({
+                event: 'new-interaction',
+                type: 'db-query',
+                query: 'SELECT * FROM users',
+                selects: ['users']
+            });
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            const observation = observationMessage.observations[0];
+            expect(observation).toMatchObject({
+                type: 'db-query',
+                returnedRows: 1
+            });
+        });
+        it('should handle multiple table operations in SQL', () => {
+            mockedAnalyzeSQL.mockReturnValue({
+                tableOperations: {
+                    users: ['SELECT'],
+                    orders: ['INSERT'],
+                    products: ['UPDATE']
+                },
+                normalizedQuery: 'INSERT INTO orders SELECT * FROM users UPDATE products',
+                presentableQuery: 'INSERT INTO orders SELECT * FROM users UPDATE products'
+            });
+            const span = createMockSpan({
+                attributes: {
+                    'db.system': 'mysql',
+                    'db.statement': 'INSERT INTO orders SELECT * FROM users; UPDATE products SET stock = 0',
+                    'db.name': 'ecommerce'
+                }
+            });
+            processor.onEnd(span);
+            const queryMessage = sentMessages.find(m => m.type === 'db-query');
+            expect(queryMessage).toMatchObject({
+                selects: ['users'],
+                inserts: ['orders'],
+                updates: ['products']
+            });
+        });
+        it('should not process SQL for non-SQL database systems', () => {
+            const span = createMockSpan({
+                attributes: {
+                    'db.system': 'mongodb',
+                    'db.statement': 'db.users.find({_id: ObjectId("...")}))',
+                    'db.name': 'myapp'
+                }
+            });
+            processor.onEnd(span);
+            expect(mockedAnalyzeSQL).not.toHaveBeenCalled();
+            // Should still create database and connection, but no query interaction
+            const queryMessages = sentMessages.filter(m => m.type === 'db-query');
+            expect(queryMessages).toHaveLength(0);
+        });
+        it('should handle alternative database connection string formats', () => {
+            const span = createMockSpan({
+                attributes: {
+                    'db.system': 'mssql',
+                    'db.connection_string': 'Server=localhost;Database=TestDB;User Id=sa;Password=secret;'
+                }
+            });
+            processor.onEnd(span);
+            const databaseMessage = sentMessages.find(m => m.type === 'database');
+            expect(databaseMessage).toMatchObject({
+                system: 'mssql',
+                host: 'localhost',
+                name: 'TestDB'
+            });
+            const connectionMessage = sentMessages.find(m => m.type === 'db-connection');
+            expect(connectionMessage).toMatchObject({
+                user: 'sa'
+            });
+        });
+    });
+    describe('Error Handling', () => {
+        it('should extract error information from exception events', () => {
+            const span = createMockSpan({
+                kind: api_1.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: api_1.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()'
+            });
+        });
+        it('should fallback to span attributes for error information', () => {
+            const span = createMockSpan({
+                kind: api_1.SpanKind.CLIENT,
+                attributes: {
+                    'http.url': 'https://api.example.com/fail',
+                    'http.method': 'POST',
+                    'http.status_code': 404,
+                    'exception.message': 'Not found',
+                    'exception.type': 'HttpError'
+                },
+                status: { code: api_1.SpanStatusCode.ERROR }
+            });
+            processor.onEnd(span);
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            const observation = observationMessage.observations[0];
+            expect(observation).toMatchObject({
+                errorMessage: 'Not found',
+                errorType: 'HttpError'
+            });
+        });
+        it('should handle spans with error status but no explicit error attributes', () => {
+            const span = createMockSpan({
+                kind: api_1.SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/timeout',
+                    'http.method': 'GET',
+                    'http.status_code': 500
+                },
+                status: { code: api_1.SpanStatusCode.ERROR, message: 'Request timeout' }
+            });
+            processor.onEnd(span);
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            const observation = observationMessage.observations[0];
+            expect(observation.errorMessage).toBe('Request timeout');
+        });
+    });
+    describe('Sequence Numbers and Batching', () => {
+        it('should increment sequence numbers for observation messages', () => {
+            const span1 = createMockSpan({
+                kind: api_1.SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/test1',
+                    'http.method': 'GET',
+                    'http.status_code': 200
+                }
+            });
+            const span2 = createMockSpan({
+                kind: api_1.SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/test2',
+                    'http.method': 'GET',
+                    'http.status_code': 200
+                }
+            });
+            processor.onEnd(span1);
+            processor.onEnd(span2);
+            const observationMessages = sentMessages.filter(m => m.event === 'observations');
+            expect(observationMessages).toHaveLength(2);
+            expect(observationMessages[0].seq).toBe(1);
+            expect(observationMessages[1].seq).toBe(2);
+        });
+    });
+    describe('Processor Lifecycle', () => {
+        it('should construct with debug logging', () => {
+            const mockLogger = jest.fn();
+            const debugProcessor = new ComprehendDevSpanProcessor_1.ComprehendDevSpanProcessor({
+                organization: 'test-org',
+                token: 'test-token',
+                debug: mockLogger
+            });
+            expect(MockedWebSocketConnection).toHaveBeenCalledWith('test-org', 'test-token', mockLogger);
+            debugProcessor.shutdown();
+        });
+        it('should construct with debug enabled as boolean', () => {
+            const debugProcessor = new ComprehendDevSpanProcessor_1.ComprehendDevSpanProcessor({
+                organization: 'test-org',
+                token: 'test-token',
+                debug: true
+            });
+            expect(MockedWebSocketConnection).toHaveBeenCalledWith('test-org', 'test-token', console.log);
+            debugProcessor.shutdown();
+        });
+        it('should construct with debug disabled', () => {
+            const noDebugProcessor = new ComprehendDevSpanProcessor_1.ComprehendDevSpanProcessor({
+                organization: 'test-org',
+                token: 'test-token',
+                debug: false
+            });
+            expect(MockedWebSocketConnection).toHaveBeenCalledWith('test-org', 'test-token', undefined);
+            noDebugProcessor.shutdown();
+        });
+        it('should call connection.close() on shutdown', async () => {
+            await processor.shutdown();
+            expect(mockConnection.close).toHaveBeenCalled();
+        });
+        it('should handle forceFlush without error', async () => {
+            await expect(processor.forceFlush()).resolves.toBeUndefined();
+        });
+        it('onStart should be a no-op', () => {
+            expect(() => processor.onStart({}, {})).not.toThrow();
+        });
+    });
+    describe('Integration Tests', () => {
+        it('should handle a complete HTTP server request flow', () => {
+            const span = createMockSpan({
+                kind: api_1.SpanKind.SERVER,
+                attributes: {
+                    'http.route': '/api/users/{id}',
+                    'http.method': 'GET',
+                    'http.target': '/api/users/123?include=profile',
+                    'http.status_code': 200,
+                    'http.user_agent': 'test-client/1.0',
+                    'http.request_content_length': 0,
+                    'http.response_content_length': 456
+                },
+                resourceAttributes: {
+                    'service.name': 'user-api',
+                    'service.namespace': 'backend',
+                    'deployment.environment': 'staging'
+                },
+                startTime: [1700000000, 500000000],
+                duration: [0, 50000000] // 50ms
+            });
+            processor.onEnd(span);
+            // Verify all expected messages
+            expect(sentMessages).toHaveLength(3);
+            const serviceMessage = sentMessages[0];
+            expect(serviceMessage).toMatchObject({
+                event: 'new-entity',
+                type: 'service',
+                name: 'user-api',
+                namespace: 'backend',
+                environment: 'staging'
+            });
+            const routeMessage = sentMessages[1];
+            expect(routeMessage).toMatchObject({
+                event: 'new-entity',
+                type: 'http-route',
+                parent: serviceMessage.hash,
+                method: 'GET',
+                route: '/api/users/{id}'
+            });
+            const observationMessage = sentMessages[2];
+            expect(observationMessage.seq).toBe(1);
+            expect(observationMessage.observations).toHaveLength(1);
+            const observation = observationMessage.observations[0];
+            expect(observation).toMatchObject({
+                type: 'http-server',
+                subject: routeMessage.hash,
+                timestamp: [1700000000, 500000000],
+                path: '/api/users/123',
+                status: 200,
+                duration: [0, 50000000],
+                userAgent: 'test-client/1.0',
+                requestBytes: 0,
+                responseBytes: 456
+            });
+        });
+        it('should handle a complete database operation flow', () => {
+            mockedAnalyzeSQL.mockReturnValue({
+                tableOperations: { users: ['SELECT'], orders: ['INSERT'] },
+                normalizedQuery: 'INSERT INTO orders SELECT FROM users WHERE active = true',
+                presentableQuery: 'INSERT INTO orders SELECT FROM users WHERE active = true'
+            });
+            const span = createMockSpan({
+                attributes: {
+                    'db.system': 'postgresql',
+                    'db.connection_string': 'postgresql://app_user:secret@db.prod.com:5432/ecommerce',
+                    'db.statement': 'INSERT INTO orders SELECT FROM users WHERE active = true',
+                    'db.response.returned_rows': 5
+                },
+                startTime: [1700000000, 0],
+                duration: [0, 25000000] // 25ms
+            });
+            processor.onEnd(span);
+            // Verify all expected messages: service, database, connection, query, observation
+            expect(sentMessages).toHaveLength(5);
+            const databaseMessage = sentMessages.find(m => m.type === 'database');
+            expect(databaseMessage).toMatchObject({
+                system: 'postgresql',
+                host: 'db.prod.com',
+                port: 5432,
+                name: 'ecommerce'
+            });
+            const connectionMessage = sentMessages.find(m => m.type === 'db-connection');
+            expect(connectionMessage).toMatchObject({
+                user: 'app_user'
+            });
+            const queryMessage = sentMessages.find(m => m.type === 'db-query');
+            expect(queryMessage).toMatchObject({
+                query: 'INSERT INTO orders SELECT FROM users WHERE active = true',
+                selects: ['users'],
+                inserts: ['orders']
+            });
+            const observationMessage = sentMessages.find(m => m.event === 'observations');
+            const observation = observationMessage.observations[0];
+            expect(observation).toMatchObject({
+                type: 'db-query',
+                subject: queryMessage.hash,
+                timestamp: [1700000000, 0],
+                duration: [0, 25000000],
+                returnedRows: 5
+            });
+        });
+    });
+});

package/dist/WebSocketConnection.test.d.ts

@@ -0,0 +1 @@
+export {};