@comprehend/telemetry-node 0.1.4 → 0.2.1

package/src/ComprehendMetricsExporter.test.ts

@@ -0,0 +1,334 @@
+import { ExportResultCode } from '@opentelemetry/core';
+import {
+    AggregationTemporality,
+    DataPointType,
+    InstrumentType,
+    ResourceMetrics,
+} from '@opentelemetry/sdk-metrics';
+import { ComprehendMetricsExporter } from './ComprehendMetricsExporter';
+import { WebSocketConnection } from './WebSocketConnection';
+import {
+    CumulativeMetricsMessage,
+    TimeSeriesMetricsMessage,
+    CustomMetricSpecification,
+} from './wire-protocol';
+
+jest.mock('./WebSocketConnection');
+
+describe('ComprehendMetricsExporter', () => {
+    let exporter: ComprehendMetricsExporter;
+    let mockConnection: jest.Mocked<WebSocketConnection>;
+    let sentMessages: any[];
+    let seqCounter: number;
+
+    beforeEach(() => {
+        sentMessages = [];
+        seqCounter = 1;
+
+        mockConnection = {
+            sendMessage: jest.fn((message: any) => {
+                sentMessages.push(message);
+            }),
+            nextSeq: jest.fn(() => seqCounter++),
+            close: jest.fn(),
+            setProcessContext: jest.fn(),
+        } as any;
+
+        exporter = new ComprehendMetricsExporter(mockConnection);
+    });
+
+    function createResourceMetrics(metrics: Array<{
+        name: string;
+        unit?: string;
+        dataPointType: DataPointType;
+        dataPoints: Array<{
+            startTime?: [number, number];
+            endTime: [number, number];
+            attributes: Record<string, any>;
+            value: any;
+        }>;
+        isMonotonic?: boolean;
+    }>, resourceAttributes: Record<string, any> = { 'service.name': 'test-service' }): ResourceMetrics {
+        return ({
+            resource: { attributes: resourceAttributes } as any,
+            scopeMetrics: [{
+                scope: { name: 'test-scope' } as any,
+                metrics: metrics.map(m => ({
+                    descriptor: {
+                        name: m.name,
+                        description: '',
+                        unit: m.unit ?? '',
+                        valueType: 0,
+                    },
+                    dataPointType: m.dataPointType,
+                    dataPoints: m.dataPoints.map(dp => ({
+                        startTime: dp.startTime ?? [0, 0],
+                        endTime: dp.endTime,
+                        attributes: dp.attributes,
+                        value: dp.value,
+                    })),
+                    ...(m.isMonotonic !== undefined ? { isMonotonic: m.isMonotonic } : {}),
+                    aggregationTemporality: AggregationTemporality.CUMULATIVE,
+                })),
+            }],
+        }) as ResourceMetrics;
+    }
+
+    describe('Standard Gauge Metrics', () => {
+        it('should forward known gauge metrics as timeseries', () => {
+            const rm = createResourceMetrics([{
+                name: 'process.runtime.nodejs.memory.heap.used',
+                unit: 'By',
+                dataPointType: DataPointType.GAUGE,
+                dataPoints: [{
+                    endTime: [1700000000, 0],
+                    attributes: {},
+                    value: 52428800,
+                }],
+            }]);
+
+            const callback = jest.fn();
+            exporter.export(rm, callback);
+
+            expect(callback).toHaveBeenCalledWith({ code: ExportResultCode.SUCCESS });
+
+            const tsMsg = sentMessages.find(m => m.event === 'timeseries') as TimeSeriesMetricsMessage;
+            expect(tsMsg).toBeDefined();
+            expect(tsMsg.data).toHaveLength(1);
+            expect(tsMsg.data[0]).toMatchObject({
+                type: 'process.runtime.nodejs.memory.heap.used',
+                value: 52428800,
+                unit: 'By',
+            });
+        });
+
+        it('should forward multiple known gauge metrics', () => {
+            const rm = createResourceMetrics([
+                {
+                    name: 'process.runtime.nodejs.memory.heap.total',
+                    unit: 'By',
+                    dataPointType: DataPointType.GAUGE,
+                    dataPoints: [{ endTime: [1700000000, 0], attributes: {}, value: 104857600 }],
+                },
+                {
+                    name: 'nodejs.eventloop.delay.mean',
+                    unit: 'ms',
+                    dataPointType: DataPointType.GAUGE,
+                    dataPoints: [{ endTime: [1700000000, 0], attributes: {}, value: 1.5 }],
+                },
+            ]);
+
+            const callback = jest.fn();
+            exporter.export(rm, callback);
+
+            const tsMessages = sentMessages.filter(m => m.event === 'timeseries');
+            expect(tsMessages).toHaveLength(2);
+        });
+    });
+
+    describe('Unknown Metrics', () => {
+        it('should ignore unknown metric names', () => {
+            const rm = createResourceMetrics([{
+                name: 'some.unknown.metric',
+                dataPointType: DataPointType.GAUGE,
+                dataPoints: [{ endTime: [0, 0], attributes: {}, value: 42 }],
+            }]);
+
+            const callback = jest.fn();
+            exporter.export(rm, callback);
+
+            expect(sentMessages).toHaveLength(0);
+            expect(callback).toHaveBeenCalledWith({ code: ExportResultCode.SUCCESS });
+        });
+    });
+
+    describe('Histogram Metrics', () => {
+        it('should skip histogram data point types', () => {
+            const rm = createResourceMetrics([{
+                name: 'process.runtime.nodejs.memory.heap.used',
+                dataPointType: DataPointType.HISTOGRAM,
+                dataPoints: [{ endTime: [0, 0], attributes: {}, value: { buckets: {} } }],
+            }]);
+
+            const callback = jest.fn();
+            exporter.export(rm, callback);
+
+            expect(sentMessages).toHaveLength(0);
+        });
+
+        it('should skip exponential histogram data point types', () => {
+            const rm = createResourceMetrics([{
+                name: 'process.runtime.nodejs.memory.heap.used',
+                dataPointType: DataPointType.EXPONENTIAL_HISTOGRAM,
+                dataPoints: [{ endTime: [0, 0], attributes: {}, value: {} }],
+            }]);
+
+            const callback = jest.fn();
+            exporter.export(rm, callback);
+
+            expect(sentMessages).toHaveLength(0);
+        });
+    });
+
+    describe('Custom Metrics', () => {
+        it('should forward custom cumulative metrics', () => {
+            exporter.updateCustomMetrics([
+                { type: 'cumulative', id: 'app.requests.total', attributes: ['method', 'status'], subject: 'custom-sub' },
+            ]);
+
+            const rm = createResourceMetrics([{
+                name: 'app.requests.total',
+                unit: '1',
+                dataPointType: DataPointType.SUM,
+                dataPoints: [{
+                    endTime: [1700000000, 0],
+                    attributes: { method: 'GET', status: '200', ignored: 'yes' },
+                    value: 150,
+                }],
+            }]);
+
+            const callback = jest.fn();
+            exporter.export(rm, callback);
+
+            const cumMsg = sentMessages.find(m => m.event === 'cumulative') as CumulativeMetricsMessage;
+            expect(cumMsg).toBeDefined();
+            expect(cumMsg.data[0]).toMatchObject({
+                subject: 'custom-sub',
+                type: 'app.requests.total',
+                value: 150,
+            });
+            // Should only include filtered attributes
+            expect(cumMsg.data[0].attributes).toEqual({ method: 'GET', status: '200' });
+        });
+
+        it('should forward custom timeseries metrics', () => {
+            exporter.updateCustomMetrics([
+                { type: 'timeseries', id: 'app.cpu.usage', attributes: ['core'], subject: 'cpu-sub' },
+            ]);
+
+            const rm = createResourceMetrics([{
+                name: 'app.cpu.usage',
+                unit: '%',
+                dataPointType: DataPointType.GAUGE,
+                dataPoints: [{
+                    endTime: [1700000000, 0],
+                    attributes: { core: '0' },
+                    value: 45.2,
+                }],
+            }]);
+
+            const callback = jest.fn();
+            exporter.export(rm, callback);
+
+            const tsMsg = sentMessages.find(m => m.event === 'timeseries') as TimeSeriesMetricsMessage;
+            expect(tsMsg).toBeDefined();
+            expect(tsMsg.data[0]).toMatchObject({
+                subject: 'cpu-sub',
+                type: 'app.cpu.usage',
+                value: 45.2,
+            });
+        });
+
+        it('should update custom metric specs when updateCustomMetrics is called', () => {
+            exporter.updateCustomMetrics([
+                { type: 'cumulative', id: 'old.metric', attributes: [], subject: 's1' },
+            ]);
+
+            // Replace with new specs
+            exporter.updateCustomMetrics([
+                { type: 'timeseries', id: 'new.metric', attributes: [], subject: 's2' },
+            ]);
+
+            const rmOld = createResourceMetrics([{
+                name: 'old.metric',
+                dataPointType: DataPointType.SUM,
+                dataPoints: [{ endTime: [0, 0], attributes: {}, value: 1 }],
+            }]);
+            const rmNew = createResourceMetrics([{
+                name: 'new.metric',
+                dataPointType: DataPointType.GAUGE,
+                dataPoints: [{ endTime: [0, 0], attributes: {}, value: 2 }],
+            }]);
+
+            const callback = jest.fn();
+            exporter.export(rmOld, callback);
+            expect(sentMessages).toHaveLength(0); // old spec no longer active
+
+            exporter.export(rmNew, callback);
+            expect(sentMessages).toHaveLength(1);
+        });
+    });
+
+    describe('Service Subject Hashing', () => {
+        it('should derive service subject from resource attributes', () => {
+            const rm = createResourceMetrics([{
+                name: 'process.runtime.nodejs.memory.heap.used',
+                unit: 'By',
+                dataPointType: DataPointType.GAUGE,
+                dataPoints: [{ endTime: [0, 0], attributes: {}, value: 100 }],
+            }], {
+                'service.name': 'my-svc',
+                'service.namespace': 'ns',
+                'deployment.environment': 'prod',
+            });
+
+            const callback = jest.fn();
+            exporter.export(rm, callback);
+
+            const tsMsg = sentMessages.find(m => m.event === 'timeseries');
+            expect(tsMsg.data[0].subject).toBeDefined();
+            expect(typeof tsMsg.data[0].subject).toBe('string');
+            expect(tsMsg.data[0].subject.length).toBe(64); // SHA256 hex
+        });
+
+        it('should skip known metrics when no service.name in resource', () => {
+            const rm = createResourceMetrics([{
+                name: 'process.runtime.nodejs.memory.heap.used',
+                dataPointType: DataPointType.GAUGE,
+                dataPoints: [{ endTime: [0, 0], attributes: {}, value: 100 }],
+            }], {}); // No service.name
+
+            const callback = jest.fn();
+            exporter.export(rm, callback);
+
+            expect(sentMessages).toHaveLength(0);
+        });
+    });
+
+    describe('Aggregation Temporality', () => {
+        it('should return DELTA for COUNTER', () => {
+            expect(exporter.selectAggregationTemporality(InstrumentType.COUNTER))
+                .toBe(AggregationTemporality.DELTA);
+        });
+
+        it('should return DELTA for HISTOGRAM', () => {
+            expect(exporter.selectAggregationTemporality(InstrumentType.HISTOGRAM))
+                .toBe(AggregationTemporality.DELTA);
+        });
+
+        it('should return CUMULATIVE for OBSERVABLE_GAUGE', () => {
+            expect(exporter.selectAggregationTemporality(InstrumentType.OBSERVABLE_GAUGE))
+                .toBe(AggregationTemporality.CUMULATIVE);
+        });
+
+        it('should return CUMULATIVE for OBSERVABLE_COUNTER', () => {
+            expect(exporter.selectAggregationTemporality(InstrumentType.OBSERVABLE_COUNTER))
+                .toBe(AggregationTemporality.CUMULATIVE);
+        });
+
+        it('should return CUMULATIVE for GAUGE', () => {
+            expect(exporter.selectAggregationTemporality(InstrumentType.GAUGE))
+                .toBe(AggregationTemporality.CUMULATIVE);
+        });
+    });
+
+    describe('Lifecycle', () => {
+        it('should resolve forceFlush', async () => {
+            await expect(exporter.forceFlush()).resolves.toBeUndefined();
+        });
+
+        it('should resolve shutdown', async () => {
+            await expect(exporter.shutdown()).resolves.toBeUndefined();
+        });
+    });
+});

package/src/ComprehendMetricsExporter.ts

@@ -0,0 +1,225 @@
+import { ExportResult, ExportResultCode } from '@opentelemetry/core';
+import {
+    AggregationTemporality,
+    DataPointType,
+    InstrumentType,
+    PushMetricExporter,
+    ResourceMetrics,
+} from '@opentelemetry/sdk-metrics';
+import { sha256 } from '@noble/hashes/sha2';
+import { utf8ToBytes } from '@noble/hashes/utils';
+import {
+    AttributeType,
+    CumulativeDataPoint,
+    CustomCumulativeMetricSpecification,
+    CustomMetricSpecification,
+    CustomTimeSeriesMetricSpecification,
+    HrTime,
+    TimeSeriesDataPoint,
+} from './wire-protocol';
+import { WebSocketConnection } from './WebSocketConnection';
+
+/**
+ * Well-known Node.js runtime metric names that we forward as timeseries (gauge) metrics.
+ * Sources:
+ *  - @opentelemetry/instrumentation-runtime-node (process.runtime.nodejs.*, nodejs.*)
+ *  - OTel semconv: process metrics (process.cpu.utilization, process.uptime)
+ *  - OTel semconv: V8 JS metrics (v8js.memory.heap.*)
+ */
+const KNOWN_GAUGE_METRICS = new Set([
+    // Node.js runtime instrumentation metrics (@opentelemetry/instrumentation-runtime-node)
+    'process.runtime.nodejs.memory.heap.total',
+    'process.runtime.nodejs.memory.heap.used',
+    'process.runtime.nodejs.memory.rss',
+    'process.runtime.nodejs.memory.array_buffers',
+    'process.runtime.nodejs.memory.external',
+    'nodejs.eventloop.delay.min',
+    'nodejs.eventloop.delay.max',
+    'nodejs.eventloop.delay.mean',
+    'nodejs.eventloop.delay.p50',
+    'nodejs.eventloop.delay.p99',
+    'nodejs.eventloop.utilization',
+    'nodejs.active_handles.total',
+    // OTel semconv process metrics
+    'process.cpu.utilization',
+    'process.uptime',
+    // OTel semconv V8 JS runtime metrics
+    'v8js.memory.heap.limit',
+    'v8js.memory.heap.used',
+    'v8js.memory.heap.space.available_size',
+    'v8js.memory.heap.space.physical_size',
+    // Host metrics (@opentelemetry/host-metrics)
+    'process.memory.usage',
+]);
+
+/** Well-known counter/cumulative metrics. */
+const KNOWN_CUMULATIVE_METRICS = new Set([
+    'process.cpu.time',
+    'process.memory.virtual',
+]);
+
+export class ComprehendMetricsExporter implements PushMetricExporter {
+    private readonly connection: WebSocketConnection;
+    private customCumulativeSpecs: CustomCumulativeMetricSpecification[] = [];
+    private customTimeSeriesSpecs: CustomTimeSeriesMetricSpecification[] = [];
+
+    constructor(connection: WebSocketConnection) {
+        this.connection = connection;
+    }
+
+    updateCustomMetrics(specs: CustomMetricSpecification[]): void {
+        this.customCumulativeSpecs = specs.filter(
+            (s): s is CustomCumulativeMetricSpecification => s.type === 'cumulative'
+        );
+        this.customTimeSeriesSpecs = specs.filter(
+            (s): s is CustomTimeSeriesMetricSpecification => s.type === 'timeseries'
+        );
+    }
+
+    export(metrics: ResourceMetrics, resultCallback: (result: ExportResult) => void): void {
+        try {
+            const serviceSubject = this.getServiceSubject(metrics);
+            for (const scopeMetrics of metrics.scopeMetrics) {
+                for (const metric of scopeMetrics.metrics) {
+                    const name = metric.descriptor.name;
+                    const unit = metric.descriptor.unit;
+
+                    // Skip histogram types entirely
+                    if (metric.dataPointType === DataPointType.HISTOGRAM ||
+                        metric.dataPointType === DataPointType.EXPONENTIAL_HISTOGRAM) {
+                        continue;
+                    }
+
+                    // Check standard well-known metrics
+                    if (KNOWN_GAUGE_METRICS.has(name) && serviceSubject) {
+                        this.sendTimeSeriesData(serviceSubject, name, unit, metric);
+                        continue;
+                    }
+                    if (KNOWN_CUMULATIVE_METRICS.has(name) && serviceSubject) {
+                        this.sendCumulativeData(serviceSubject, name, unit, metric);
+                        continue;
+                    }
+
+                    // Check custom metric specs
+                    const cumulativeSpec = this.customCumulativeSpecs.find(s => s.id === name);
+                    if (cumulativeSpec) {
+                        this.sendCumulativeData(cumulativeSpec.subject, name, unit, metric, cumulativeSpec.attributes);
+                        continue;
+                    }
+
+                    const timeSeriesSpec = this.customTimeSeriesSpecs.find(s => s.id === name);
+                    if (timeSeriesSpec) {
+                        this.sendTimeSeriesData(timeSeriesSpec.subject, name, unit, metric, timeSeriesSpec.attributes);
+                    }
+                }
+            }
+            resultCallback({ code: ExportResultCode.SUCCESS });
+        } catch {
+            resultCallback({ code: ExportResultCode.FAILED });
+        }
+    }
+
+    private sendTimeSeriesData(
+        subject: string,
+        name: string,
+        unit: string,
+        metric: { dataPointType: DataPointType, dataPoints: any[] },
+        filterAttributes?: string[],
+    ): void {
+        const data: TimeSeriesDataPoint[] = [];
+        for (const dp of metric.dataPoints) {
+            data.push({
+                subject,
+                type: name,
+                timestamp: hrTimeFromOtel(dp.endTime),
+                value: dp.value as number,
+                unit,
+                attributes: extractAttributes(dp.attributes, filterAttributes),
+            });
+        }
+        if (data.length > 0) {
+            this.connection.sendMessage({
+                event: 'timeseries',
+                seq: this.connection.nextSeq(),
+                data,
+            });
+        }
+    }
+
+    private sendCumulativeData(
+        subject: string,
+        name: string,
+        unit: string,
+        metric: { dataPointType: DataPointType, dataPoints: any[] },
+        filterAttributes?: string[],
+    ): void {
+        const data: CumulativeDataPoint[] = [];
+        for (const dp of metric.dataPoints) {
+            data.push({
+                subject,
+                type: name,
+                timestamp: hrTimeFromOtel(dp.endTime),
+                value: dp.value as number,
+                unit,
+                attributes: extractAttributes(dp.attributes, filterAttributes),
+            });
+        }
+        if (data.length > 0) {
+            this.connection.sendMessage({
+                event: 'cumulative',
+                seq: this.connection.nextSeq(),
+                data,
+            });
+        }
+    }
+
+    private getServiceSubject(metrics: ResourceMetrics): string | null {
+        const attrs = metrics.resource.attributes;
+        const name = attrs['service.name'] as string | undefined;
+        if (!name) return null;
+        const namespace = attrs['service.namespace'] as string | undefined;
+        const environment = attrs['deployment.environment'] as string | undefined;
+        const idString = `service:${name}:${namespace ?? ''}:${environment ?? ''}`;
+        return hashIdString(idString);
+    }
+
+    selectAggregationTemporality(instrumentType: InstrumentType): AggregationTemporality {
+        switch (instrumentType) {
+            case InstrumentType.COUNTER:
+            case InstrumentType.HISTOGRAM:
+                return AggregationTemporality.DELTA;
+            default:
+                return AggregationTemporality.CUMULATIVE;
+        }
+    }
+
+    async forceFlush(): Promise<void> {
+    }
+
+    async shutdown(): Promise<void> {
+    }
+}
+
+function hashIdString(idString: string) {
+    return Array.from(sha256(utf8ToBytes(idString)))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+
+function extractAttributes(
+    attrs: Record<string, any>,
+    filterKeys?: string[],
+): Record<string, AttributeType> {
+    const result: Record<string, AttributeType> = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value === undefined) continue;
+        if (filterKeys && !filterKeys.includes(key)) continue;
+        result[key] = value as AttributeType;
+    }
+    return result;
+}
+
+/** Convert OTel HrTime to our wire protocol HrTime (same format: [seconds, nanoseconds]). */
+function hrTimeFromOtel(time: [number, number]): HrTime {
+    return time;
+}