observability-toolkit 2.0.0 → 2.1.1

package/dist/tools/query-metrics.test.js

@@ -1,36 +1,58 @@
 /**
  * Unit tests for query-metrics tool
  */
-import { describe, it, beforeEach, afterEach } from 'node:test';
+import { describe, it, beforeEach } from 'vitest';
 import assert from 'node:assert';
 import { queryMetrics, queryMetricsSchema } from './query-metrics.js';
 import { getMockOptions as getMockBackendOptions } from '../test-helpers/mock-backends.js';
-import { validateBackendSchema, validateLimitSchema, validateDateRangeSchema } from '../test-helpers/schema-validators.js';
-import { captureEnv, restoreEnv, clearSigNozEnv } from '../test-helpers/env-utils.js';
+import { validateLimitSchema, validateDateRangeSchema } from '../test-helpers/schema-validators.js';
+import { METRICS_DEFAULT_LIMIT } from '../lib/core/shared-schemas.js';
+import { DEFAULT_PAGE_SIZE } from '../lib/core/constants.js';
+import { ONE_MILLION, ROUND_4DP_FACTOR } from '../lib/core/units.js';
+// ---------------------------------------------------------------------------
+// Test fixture values
+// ---------------------------------------------------------------------------
+const CPU_VALUE_LOW = 40;
+const CPU_VALUE_MID = 50;
+const CPU_VALUE_HIGH = 60;
+const METRIC_INTERVAL_MS = 1000;
+const LARGE_METRIC_COUNT = 50;
+const EXPECTED_SUMMARY_GROUPS = 2;
+const EXPECTED_SPAN_COUNT = 2;
+// Cost metric test fixtures (2024-02-14 epoch ms)
+const EPOCH_MS_T0 = 1707900000000;
+const EPOCH_MS_T1 = 1707900060000;
+const EPOCH_NANOS_T0 = EPOCH_MS_T0 * ONE_MILLION;
+const EPOCH_NANOS_T1 = EPOCH_MS_T1 * ONE_MILLION;
+const INPUT_TOKENS_STD = 1000;
+const OUTPUT_TOKENS_STD = 500;
+const INPUT_TOKENS_LARGE = 2000;
+const OUTPUT_TOKENS_LARGE = 1000;
+const SONNET_TOTAL_INPUT_TOKENS = 1500;
+const SONNET_TOTAL_OUTPUT_TOKENS = 700;
+const HAIKU_INPUT_TOKENS = 2000;
+const HAIKU_OUTPUT_TOKENS = 1000;
+const INPUT_TOKENS_SMALL = 500;
+const OUTPUT_TOKENS_SMALL = 200;
 // Mock data storage
-const mockStore = { local: [], signoz: [] };
+const mockStore = { local: [] };
 // Options with mock backends
 function getMockOptions() {
     return getMockBackendOptions(mockStore, 'metrics');
 }
-// Capture original env values
-const originalEnv = captureEnv();
 // Pure schema validation (no setup/teardown needed)
-describe('queryMetricsSchema (pure validation)', () => {
-    validateBackendSchema(queryMetricsSchema, 'queryMetricsSchema');
-    validateLimitSchema(queryMetricsSchema, 'queryMetricsSchema', 100);
+void describe('queryMetricsSchema (pure validation)', () => {
+    validateLimitSchema(queryMetricsSchema, 'queryMetricsSchema', METRICS_DEFAULT_LIMIT);
     validateDateRangeSchema(queryMetricsSchema, 'queryMetricsSchema');
 });
-describe('queryMetrics', () => {
+void describe('queryMetrics', () => {
     beforeEach(() => {
         // Reset mock data before each test
         mockStore.local = [];
-        mockStore.signoz = [];
     });
-    describe('schema validation', () => {
-        it('should accept valid input with all parameters', () => {
+    void describe('schema validation', () => {
+        void it('should accept valid input with all parameters', () => {
             const input = {
-                backend: 'local',
                 metricName: 'http_requests',
                 aggregation: 'sum',
                 groupBy: ['service', 'method'],
@@ -41,11 +63,10 @@ describe('queryMetrics', () => {
             const result = queryMetricsSchema.safeParse(input);
             assert.strictEqual(result.success, true);
         });
-        it('should accept all aggregation types', () => {
+        void it('should accept all aggregation types', () => {
             const aggregations = ['sum', 'avg', 'min', 'max', 'count'];
             for (const agg of aggregations) {
                 const input = {
-                    backend: 'local',
                     aggregation: agg,
                 };
                 const result = queryMetricsSchema.safeParse(input);
@@ -53,11 +74,10 @@ describe('queryMetrics', () => {
                 assert.strictEqual(result.data?.aggregation, agg);
             }
         });
-        it('should accept percentile aggregation types (p50, p95, p99)', () => {
+        void it('should accept percentile aggregation types (p50, p95, p99)', () => {
             const percentileAggregations = ['p50', 'p95', 'p99'];
             for (const agg of percentileAggregations) {
                 const input = {
-                    backend: 'local',
                     aggregation: agg,
                 };
                 const result = queryMetricsSchema.safeParse(input);
@@ -65,32 +85,23 @@ describe('queryMetrics', () => {
                 assert.strictEqual(result.data?.aggregation, agg);
             }
         });
-        it('should accept rate aggregation type', () => {
+        void it('should accept rate aggregation type', () => {
             const input = {
-                backend: 'local',
                 aggregation: 'rate',
             };
             const result = queryMetricsSchema.safeParse(input);
             assert.strictEqual(result.success, true);
             assert.strictEqual(result.data?.aggregation, 'rate');
         });
-        it('should reject invalid aggregation', () => {
+        void it('should reject invalid aggregation', () => {
             const input = {
                 aggregation: 'invalid',
             };
             const result = queryMetricsSchema.safeParse(input);
             assert.strictEqual(result.success, false);
         });
-        it('should reject invalid backend', () => {
+        void it('should accept optional groupBy as array', () => {
             const input = {
-                backend: 'invalid',
-            };
-            const result = queryMetricsSchema.safeParse(input);
-            assert.strictEqual(result.success, false);
-        });
-        it('should accept optional groupBy as array', () => {
-            const input = {
-                backend: 'local',
                 groupBy: ['service', 'status_code', 'method'],
             };
             const result = queryMetricsSchema.safeParse(input);
@@ -98,28 +109,11 @@ describe('queryMetrics', () => {
             assert.deepStrictEqual(result.data?.groupBy, ['service', 'status_code', 'method']);
         });
     });
-    describe('auto backend selection', () => {
+    void describe('local backend queries', () => {
         beforeEach(() => {
             mockStore.local = [];
-            mockStore.signoz = [];
-            clearSigNozEnv();
-        });
-        afterEach(() => {
-            restoreEnv(originalEnv);
-        });
-        it('should use local backend when signoz not configured', async () => {
-            mockStore.local = [
-                {
-                    timestamp: '2026-01-28T00:00:00Z',
-                    name: 'http_requests',
-                    value: 100,
-                },
-            ];
-            const result = await queryMetrics({ backend: 'auto' }, getMockOptions());
-            assert.strictEqual(result.backend, 'local');
-            assert.strictEqual(result.count, 1);
         });
-        it('should return local metrics when available', async () => {
+        void it('should return local metrics when available', async () => {
             mockStore.local = [
                 {
                     timestamp: '2026-01-28T10:00:00Z',
@@ -132,52 +126,45 @@ describe('queryMetrics', () => {
                     value: 47.2,
                 },
             ];
-            const result = await queryMetrics({ backend: 'local' }, getMockOptions());
-            assert.strictEqual(result.backend, 'local');
-            assert.strictEqual(result.count, 2);
+            const result = await queryMetrics({}, getMockOptions());
+            assert.strictEqual(result.backend, 'mock-local');
+            assert.strictEqual(result.count, EXPECTED_SPAN_COUNT);
         });
-        it('should compute summary statistics for local backend', async () => {
+        void it('should compute summary statistics for local backend', async () => {
             mockStore.local = [
-                { timestamp: '2026-01-28T10:00:00Z', name: 'cpu_usage', value: 40 },
-                { timestamp: '2026-01-28T10:01:00Z', name: 'cpu_usage', value: 50 },
-                { timestamp: '2026-01-28T10:02:00Z', name: 'cpu_usage', value: 60 },
+                { timestamp: '2026-01-28T10:00:00Z', name: 'cpu_usage', value: CPU_VALUE_LOW },
+                { timestamp: '2026-01-28T10:01:00Z', name: 'cpu_usage', value: CPU_VALUE_MID },
+                { timestamp: '2026-01-28T10:02:00Z', name: 'cpu_usage', value: CPU_VALUE_HIGH },
             ];
-            const result = await queryMetrics({ backend: 'local' }, getMockOptions());
-            assert.strictEqual(result.backend, 'local');
+            const result = await queryMetrics({}, getMockOptions());
+            assert.strictEqual(result.backend, 'mock-local');
             assert.ok('summary' in result);
             const summary = result.summary;
             const cpuSummary = summary.find(s => s.name === 'cpu_usage');
             assert.ok(cpuSummary);
-            assert.strictEqual(cpuSummary.min, 40);
-            assert.strictEqual(cpuSummary.max, 60);
-            assert.strictEqual(cpuSummary.avg, 50);
+            assert.strictEqual(cpuSummary.min, CPU_VALUE_LOW);
+            assert.strictEqual(cpuSummary.max, CPU_VALUE_HIGH);
+            assert.strictEqual(cpuSummary.avg, CPU_VALUE_MID);
         });
-        it('should return empty result when no metrics found', async () => {
+        void it('should return empty result when no metrics found', async () => {
             mockStore.local = [];
-            const result = await queryMetrics({ backend: 'local' }, getMockOptions());
-            assert.strictEqual(result.backend, 'local');
+            const result = await queryMetrics({}, getMockOptions());
+            assert.strictEqual(result.backend, 'mock-local');
             assert.strictEqual(result.count, 0);
         });
     });
-    describe('local backend handling', () => {
-        it('should return local backend response structure', async () => {
-            const mockMetrics = [
-                { timestamp: '2026-01-28T10:00:00Z', name: 'cpu_usage', value: 45.5, attributes: {} },
-                { timestamp: '2026-01-28T10:01:00Z', name: 'cpu_usage', value: 47.2, attributes: {} },
-                { timestamp: '2026-01-28T10:02:00Z', name: 'memory_usage', value: 2048, attributes: {} },
-            ];
+    void describe('local backend handling', () => {
+        void it('should return local backend response structure', async () => {
             // Test the response structure when backend is local
             const input = {
-                backend: 'local',
                 metricName: 'cpu_usage',
-                limit: 100,
+                limit: METRICS_DEFAULT_LIMIT,
             };
             // Verify input gets passed correctly
-            assert.strictEqual(input.backend, 'local');
             assert.strictEqual(input.metricName, 'cpu_usage');
-            assert.strictEqual(input.limit, 100);
+            assert.strictEqual(input.limit, METRICS_DEFAULT_LIMIT);
         });
-        it('should calculate summary statistics correctly', async () => {
+        void it('should calculate summary statistics correctly', async () => {
             // Simulate summary calculation logic
             const metrics = [
                 { name: 'http_requests', value: 100, timestamp: '2026-01-28T10:00:00Z' },
@@ -202,7 +189,7 @@ describe('queryMetrics', () => {
                 max: stats.max,
                 avg: stats.sum / stats.count,
             }));
-            assert.strictEqual(summary.length, 2);
+            assert.strictEqual(summary.length, EXPECTED_SUMMARY_GROUPS);
             assert.deepStrictEqual(summary[0], {
                 name: 'http_requests',
                 count: 3,
@@ -218,7 +205,7 @@ describe('queryMetrics', () => {
                 avg: 5,
             });
         });
-        it('should handle empty metrics response', async () => {
+        void it('should handle empty metrics response', async () => {
             const metrics = [];
             const byName = new Map();
             for (const m of metrics) {
@@ -238,343 +225,281 @@ describe('queryMetrics', () => {
             }));
             assert.strictEqual(summary.length, 0);
         });
-        it('should limit dataPoints to 20 in response', async () => {
+        void it('should limit dataPoints to 20 in response', async () => {
             // Verify that local backend truncates dataPoints to 20
-            const metrics = Array.from({ length: 50 }, (_, i) => ({
-                timestamp: new Date(Date.now() - i * 1000).toISOString(),
+            const metrics = Array.from({ length: LARGE_METRIC_COUNT }, (_, i) => ({
+                timestamp: new Date(Date.now() - i * METRIC_INTERVAL_MS).toISOString(),
                 name: 'test_metric',
                 value: i,
             }));
-            const dataPoints = metrics.slice(0, 20);
-            assert.strictEqual(dataPoints.length, 20);
+            const dataPoints = metrics.slice(0, DEFAULT_PAGE_SIZE);
+            assert.strictEqual(dataPoints.length, DEFAULT_PAGE_SIZE);
         });
     });
-    describe('signoz backend handling', () => {
-        beforeEach(() => {
-            process.env.SIGNOZ_URL = 'http://localhost:3301';
-            process.env.SIGNOZ_API_KEY = 'test-key';
-        });
-        it('should return error when metricName is missing for SigNoz', async () => {
-            const result = await queryMetrics({ backend: 'signoz' }, getMockOptions());
-            assert.strictEqual(result.backend, 'signoz');
-            assert.strictEqual(result.error, 'metricName is required for SigNoz queries');
-        });
-        it('should query SigNoz backend with metricName', async () => {
-            mockStore.signoz = [
-                { timestamp: '2026-01-28T10:00:00Z', name: 'http_requests', value: 1000 },
-                { timestamp: '2026-01-28T10:01:00Z', name: 'http_requests', value: 1050 },
+    void describe('cost metric derivation', () => {
+        function makeCostBackend(traces) {
+            const backend = {
+                name: 'mock-local',
+                queryTraces: async () => traces,
+                queryLogs: async () => [],
+                queryMetrics: async () => [],
+                healthCheck: async () => ({ status: 'ok' }),
+            };
+            return { localBackend: backend };
+        }
+        function makeSpan(overrides) {
+            return {
+                traceId: 'trace-1',
+                spanId: 'span-1',
+                name: 'llm.call',
+                startTimeUnixNano: Date.now() * ONE_MILLION,
+                ...overrides,
+            };
+        }
+        void it('should compute cost from spans with token attributes', async () => {
+            const traces = [
+                makeSpan({
+                    spanId: 'span-1',
+                    startTimeUnixNano: EPOCH_NANOS_T0,
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_STD,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_STD,
+                        'gen_ai.request.model': 'claude-sonnet-4-20250514',
+                    },
+                }),
+                makeSpan({
+                    spanId: 'span-2',
+                    startTimeUnixNano: EPOCH_NANOS_T1,
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_LARGE,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_LARGE,
+                        'gen_ai.request.model': 'claude-sonnet-4-20250514',
+                    },
+                }),
             ];
-            const result = await queryMetrics({ backend: 'signoz', metricName: 'http_requests' }, getMockOptions());
-            assert.strictEqual(result.backend, 'signoz');
-            assert.strictEqual(result.count, 2);
-            assert.strictEqual(result.metricName, 'http_requests');
-            assert.ok('dataPoints' in result);
-        });
-        it('should pass all parameters to SigNoz backend', async () => {
-            mockStore.signoz = [
-                { timestamp: '2026-01-28T10:00:00Z', name: 'http_requests', value: 500 },
+            const result = await queryMetrics({ metricName: 'cost' }, makeCostBackend(traces));
+            assert.strictEqual(result.backend, 'mock-local');
+            assert.strictEqual(result.metricName, 'cost');
+            assert.strictEqual(result.count, EXPECTED_SPAN_COUNT);
+            assert.ok(result.totalCost > 0);
+            assert.ok(result.avgCostPerRequest > 0);
+            assert.ok(result.dataPoints.length === EXPECTED_SPAN_COUNT);
+            assert.strictEqual(result.coverage.spansWithTokens, EXPECTED_SPAN_COUNT);
+            assert.strictEqual(result.coverage.spansWithoutTokens, 0);
+        });
+        void it('should use fallback pricing for unknown models without error', async () => {
+            const traces = [
+                makeSpan({
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_STD,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_STD,
+                        'gen_ai.request.model': 'unknown-model-xyz',
+                    },
+                }),
             ];
-            const result = await queryMetrics({
-                backend: 'signoz',
-                metricName: 'http_requests',
-                aggregation: 'sum',
-                groupBy: ['service', 'method'],
-                startDate: '2026-01-01',
-                endDate: '2026-01-28',
-                limit: 50,
-            }, getMockOptions());
-            assert.strictEqual(result.backend, 'signoz');
+            const result = await queryMetrics({ metricName: 'cost' }, makeCostBackend(traces));
             assert.strictEqual(result.count, 1);
-            assert.strictEqual(result.metricName, 'http_requests');
+            assert.ok(result.totalCost > 0);
+            // Fallback pricing flag present on data points
+            const dp = result.dataPoints[0];
+            assert.strictEqual(dp.attributes.usedFallbackPricing, true);
+        });
+        void it('should skip spans without token attributes and report coverage', async () => {
+            const traces = [
+                makeSpan({
+                    spanId: 'span-with-tokens',
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_STD,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_STD,
+                        'gen_ai.request.model': 'claude-sonnet-4-20250514',
+                    },
+                }),
+                makeSpan({
+                    spanId: 'span-no-tokens',
+                    attributes: { 'http.method': 'GET' },
+                }),
+                makeSpan({
+                    spanId: 'span-no-attrs',
+                }),
+            ];
+            const result = await queryMetrics({ metricName: 'cost' }, makeCostBackend(traces));
+            assert.strictEqual(result.count, 1);
+            assert.strictEqual(result.coverage.spansWithTokens, 1);
+            assert.strictEqual(result.coverage.spansWithoutTokens, EXPECTED_SUMMARY_GROUPS);
         });
-        it('should return empty dataPoints when no metrics found', async () => {
-            mockStore.signoz = [];
-            const result = await queryMetrics({ backend: 'signoz', metricName: 'nonexistent_metric' }, getMockOptions());
-            assert.strictEqual(result.backend, 'signoz');
+        void it('should return zero cost for empty traces', async () => {
+            const result = await queryMetrics({ metricName: 'cost' }, makeCostBackend([]));
             assert.strictEqual(result.count, 0);
-            const dataPoints = result.dataPoints;
-            assert.deepStrictEqual(dataPoints, []);
-        });
-    });
-    describe('aggregation handling', () => {
-        it('should process sum aggregation', async () => {
-            const input = {
-                backend: 'local',
-                aggregation: 'sum',
-                limit: 100,
-            };
-            assert.strictEqual(input.aggregation, 'sum');
-        });
-        it('should process avg aggregation', async () => {
-            const input = {
-                backend: 'local',
-                aggregation: 'avg',
-                limit: 100,
-            };
-            assert.strictEqual(input.aggregation, 'avg');
-        });
-        it('should process min aggregation', async () => {
-            const input = {
-                backend: 'local',
-                aggregation: 'min',
-                limit: 100,
-            };
-            assert.strictEqual(input.aggregation, 'min');
-        });
-        it('should process max aggregation', async () => {
-            const input = {
-                backend: 'local',
-                aggregation: 'max',
-                limit: 100,
-            };
-            assert.strictEqual(input.aggregation, 'max');
-        });
-        it('should process count aggregation', async () => {
-            const input = {
-                backend: 'local',
-                aggregation: 'count',
-                limit: 100,
-            };
-            assert.strictEqual(input.aggregation, 'count');
-        });
-    });
-    describe('groupBy handling', () => {
-        it('should accept single groupBy attribute', async () => {
-            const input = {
-                backend: 'local',
-                groupBy: ['service'],
-                limit: 100,
-            };
-            assert.deepStrictEqual(input.groupBy, ['service']);
-        });
-        it('should accept multiple groupBy attributes', async () => {
-            const input = {
-                backend: 'local',
-                groupBy: ['service', 'method', 'status_code'],
-                limit: 100,
-            };
-            assert.deepStrictEqual(input.groupBy, ['service', 'method', 'status_code']);
-        });
-        it('should handle empty groupBy array', async () => {
-            const input = {
-                backend: 'local',
-                groupBy: [],
-                limit: 100,
-            };
-            assert.deepStrictEqual(input.groupBy, []);
-        });
-        it('should be optional', async () => {
-            const input = {
-                backend: 'local',
-                limit: 100,
-            };
-            assert.strictEqual(input.groupBy, undefined);
-        });
-    });
-    describe('date range handling', () => {
-        it('should accept startDate only', async () => {
-            const input = {
-                backend: 'local',
-                startDate: '2026-01-01',
-                limit: 100,
-            };
-            assert.strictEqual(input.startDate, '2026-01-01');
-            assert.strictEqual(input.endDate, undefined);
-        });
-        it('should accept endDate only', async () => {
-            const input = {
-                backend: 'local',
-                endDate: '2026-01-28',
-                limit: 100,
-            };
-            assert.strictEqual(input.startDate, undefined);
-            assert.strictEqual(input.endDate, '2026-01-28');
-        });
-        it('should accept both startDate and endDate', async () => {
-            const input = {
-                backend: 'local',
-                startDate: '2026-01-01',
-                endDate: '2026-01-28',
-                limit: 100,
-            };
-            assert.strictEqual(input.startDate, '2026-01-01');
-            assert.strictEqual(input.endDate, '2026-01-28');
-        });
-        it('should be optional', async () => {
-            const input = {
-                backend: 'local',
-                limit: 100,
-            };
-            assert.strictEqual(input.startDate, undefined);
-            assert.strictEqual(input.endDate, undefined);
-        });
-        it('should validate date format in schema', () => {
-            const validInput = {
-                backend: 'local',
-                startDate: '2026-01-28',
-            };
-            const result = queryMetricsSchema.safeParse(validInput);
-            assert.strictEqual(result.success, true);
-        });
-    });
-    describe('limit handling', () => {
-        it('should use default limit of 100', () => {
-            const input = {
-                backend: 'local',
-            };
-            const result = queryMetricsSchema.safeParse(input);
-            assert.strictEqual(result.data?.limit, 100);
-        });
-        it('should accept custom limit', () => {
-            const input = {
-                backend: 'local',
-                limit: 50,
-            };
-            assert.strictEqual(input.limit, 50);
-        });
-        it('should accept max limit value of 1000', () => {
-            const input = {
-                backend: 'local',
-                limit: 1000,
-            };
-            const result = queryMetricsSchema.safeParse(input);
-            assert.strictEqual(result.success, true);
-        });
-        it('should reject limit values over 1000', () => {
-            const result = queryMetricsSchema.safeParse({
-                backend: 'local',
-                limit: 1001,
-            });
-            assert.strictEqual(result.success, false);
-        });
-        it('should accept limit of 1', () => {
-            const input = {
-                backend: 'local',
-                limit: 1,
-            };
-            assert.strictEqual(input.limit, 1);
-        });
-    });
-    describe('metricName filtering', () => {
-        it('should be optional', () => {
-            const input = {
-                backend: 'local',
-                limit: 100,
-            };
-            assert.strictEqual(input.metricName, undefined);
-        });
-        it('should accept metric name strings', () => {
-            const input = {
-                backend: 'local',
-                metricName: 'http_requests_total',
-                limit: 100,
-            };
-            assert.strictEqual(input.metricName, 'http_requests_total');
-        });
-        it('should accept metric names with underscores', () => {
-            const input = {
-                backend: 'local',
-                metricName: 'process_cpu_usage_percentage',
-                limit: 100,
-            };
-            assert.strictEqual(input.metricName, 'process_cpu_usage_percentage');
-        });
-        it('should accept metric names with dots', () => {
-            const input = {
-                backend: 'local',
-                metricName: 'system.cpu.usage',
-                limit: 100,
-            };
-            assert.strictEqual(input.metricName, 'system.cpu.usage');
-        });
-    });
-    describe('error handling', () => {
-        it('should handle no backend available scenario', async () => {
-            const response = {
-                backend: 'none',
-                count: 0,
-                error: 'No backend available',
-            };
-            assert.strictEqual(response.error, 'No backend available');
-            assert.strictEqual(response.count, 0);
-        });
-        it('should structure error responses properly', async () => {
-            const errorResponse = {
-                backend: 'signoz',
-                error: 'metricName is required for SigNoz queries',
-            };
-            assert.ok('error' in errorResponse);
-            assert.strictEqual(errorResponse.backend, 'signoz');
-        });
-    });
-    describe('combined parameter scenarios', () => {
-        it('should handle aggregation with groupBy', async () => {
-            const input = {
-                backend: 'local',
-                aggregation: 'sum',
-                groupBy: ['service', 'method'],
-                limit: 100,
-            };
-            assert.strictEqual(input.aggregation, 'sum');
-            assert.deepStrictEqual(input.groupBy, ['service', 'method']);
-        });
-        it('should handle date range with aggregation', async () => {
-            const input = {
-                backend: 'local',
-                startDate: '2026-01-01',
-                endDate: '2026-01-28',
-                aggregation: 'avg',
-                limit: 100,
-            };
-            assert.strictEqual(input.startDate, '2026-01-01');
-            assert.strictEqual(input.endDate, '2026-01-28');
-            assert.strictEqual(input.aggregation, 'avg');
-        });
-        it('should handle all SigNoz parameters together', async () => {
-            const input = {
-                backend: 'signoz',
-                metricName: 'http_requests',
-                aggregation: 'sum',
-                groupBy: ['status_code'],
-                startDate: '2026-01-01',
-                endDate: '2026-01-28',
-                limit: 100,
-            };
-            assert.strictEqual(input.backend, 'signoz');
-            assert.strictEqual(input.metricName, 'http_requests');
-            assert.strictEqual(input.aggregation, 'sum');
-            assert.deepStrictEqual(input.groupBy, ['status_code']);
-            assert.strictEqual(input.startDate, '2026-01-01');
-            assert.strictEqual(input.endDate, '2026-01-28');
-            assert.strictEqual(input.limit, 100);
-        });
-        it('should handle minimal local backend query', async () => {
-            const input = {
-                backend: 'local',
-            };
-            assert.strictEqual(input.backend, 'local');
-            assert.strictEqual(input.metricName, undefined);
-            assert.strictEqual(input.aggregation, undefined);
+            assert.strictEqual(result.totalCost, 0);
+            assert.strictEqual(result.avgCostPerRequest, 0);
+            assert.deepStrictEqual(result.byModel, {});
+            assert.deepStrictEqual(result.dataPoints, []);
+        });
+        void it('should produce correct by-model breakdown', async () => {
+            const traces = [
+                makeSpan({
+                    spanId: 'span-1',
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_STD,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_STD,
+                        'gen_ai.request.model': 'claude-sonnet-4-20250514',
+                    },
+                }),
+                makeSpan({
+                    spanId: 'span-2',
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_LARGE,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_LARGE,
+                        'gen_ai.request.model': 'claude-haiku-3-5-20241022',
+                    },
+                }),
+                makeSpan({
+                    spanId: 'span-3',
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_SMALL,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_SMALL,
+                        'gen_ai.request.model': 'claude-sonnet-4-20250514',
+                    },
+                }),
+            ];
+            const result = await queryMetrics({ metricName: 'cost' }, makeCostBackend(traces));
+            const byModel = result.byModel;
+            assert.ok(byModel['claude-sonnet-4-20250514']);
+            assert.ok(byModel['claude-haiku-3-5-20241022']);
+            assert.strictEqual(byModel['claude-sonnet-4-20250514'].requests, EXPECTED_SPAN_COUNT);
+            assert.strictEqual(byModel['claude-sonnet-4-20250514'].inputTokens, SONNET_TOTAL_INPUT_TOKENS);
+            assert.strictEqual(byModel['claude-sonnet-4-20250514'].outputTokens, SONNET_TOTAL_OUTPUT_TOKENS);
+            assert.strictEqual(byModel['claude-haiku-3-5-20241022'].requests, 1);
+            assert.strictEqual(byModel['claude-haiku-3-5-20241022'].inputTokens, HAIKU_INPUT_TOKENS);
+            assert.strictEqual(byModel['claude-haiku-3-5-20241022'].outputTokens, HAIKU_OUTPUT_TOKENS);
+        });
+        void it('should use gen_ai.response.model as fallback for model', async () => {
+            const traces = [
+                makeSpan({
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_STD,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_STD,
+                        'gen_ai.response.model': 'claude-sonnet-4-20250514',
+                    },
+                }),
+            ];
+            const result = await queryMetrics({ metricName: 'cost' }, makeCostBackend(traces));
+            assert.strictEqual(result.count, 1);
+            const byModel = result.byModel;
+            assert.ok(byModel['claude-sonnet-4-20250514']);
+        });
+        void it('should populate fallbackPricing summary for unknown models', async () => {
+            const traces = [
+                makeSpan({
+                    spanId: 'span-unknown-1',
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_STD,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_STD,
+                        'gen_ai.request.model': 'totally-unknown-model',
+                    },
+                }),
+                makeSpan({
+                    spanId: 'span-unknown-2',
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_SMALL,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_SMALL,
+                        'gen_ai.request.model': 'another-unknown-model',
+                    },
+                }),
+            ];
+            const result = await queryMetrics({ metricName: 'cost' }, makeCostBackend(traces));
+            const typed = result;
+            assert.ok(typed.fallbackPricing, 'fallbackPricing summary should be present');
+            assert.strictEqual(typed.fallbackPricing.count, EXPECTED_SPAN_COUNT);
+            assert.ok(typed.fallbackPricing.warning.includes('fallback pricing'));
+        });
+        void it('should skip spans where model attribute is non-string', async () => {
+            const traces = [
+                makeSpan({
+                    spanId: 'span-bad-model',
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_STD,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_STD,
+                        'gen_ai.request.model': 12345,
+                    },
+                }),
+            ];
+            const result = await queryMetrics({ metricName: 'cost' }, makeCostBackend(traces));
+            const typed = result;
+            assert.strictEqual(typed.count, 0);
+            assert.strictEqual(typed.coverage.spansWithoutTokens, 1);
+            assert.strictEqual(typed.totalCost, 0);
+        });
+        void it('should sum totalCost correctly across multiple models', async () => {
+            const traces = [
+                makeSpan({
+                    spanId: 'span-1',
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_STD,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_STD,
+                        'gen_ai.request.model': 'claude-sonnet-4-20250514',
+                    },
+                }),
+                makeSpan({
+                    spanId: 'span-2',
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_LARGE,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_LARGE,
+                        'gen_ai.request.model': 'claude-haiku-3-5-20241022',
+                    },
+                }),
+            ];
+            const result = await queryMetrics({ metricName: 'cost' }, makeCostBackend(traces));
+            const typed = result;
+            const sumOfModelCosts = Object.values(typed.byModel).reduce((sum, m) => sum + m.cost, 0);
+            // Both should be rounded to 4dp, so compare within small epsilon
+            assert.ok(Math.abs(typed.totalCost - sumOfModelCosts) < 1 / ROUND_4DP_FACTOR, `totalCost ${typed.totalCost} should equal sum of model costs ${sumOfModelCosts}`);
+        });
+        void it('should compute avgCostPerRequest as totalCost / count', async () => {
+            const traces = [
+                makeSpan({
+                    spanId: 'span-1',
+                    startTimeUnixNano: EPOCH_NANOS_T0,
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_STD,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_STD,
+                        'gen_ai.request.model': 'claude-sonnet-4-20250514',
+                    },
+                }),
+                makeSpan({
+                    spanId: 'span-2',
+                    startTimeUnixNano: EPOCH_NANOS_T1,
+                    attributes: {
+                        'gen_ai.usage.input_tokens': INPUT_TOKENS_LARGE,
+                        'gen_ai.usage.output_tokens': OUTPUT_TOKENS_LARGE,
+                        'gen_ai.request.model': 'claude-sonnet-4-20250514',
+                    },
+                }),
+            ];
+            const result = await queryMetrics({ metricName: 'cost' }, makeCostBackend(traces));
+            const typed = result;
+            const expectedAvg = Math.round((typed.totalCost / typed.count) * ROUND_4DP_FACTOR) / ROUND_4DP_FACTOR;
+            assert.strictEqual(typed.avgCostPerRequest, expectedAvg);
         });
     });
-    describe('tool definition', () => {
-        it('should export tool configuration', async () => {
+    void describe('tool definition', () => {
+        void it('should export tool configuration', async () => {
             const { queryMetricsTool } = await import('./query-metrics.js');
             assert.strictEqual(queryMetricsTool.name, 'obs_query_metrics');
             assert.ok(queryMetricsTool.description);
             assert.ok(queryMetricsTool.inputSchema);
             assert.strictEqual(typeof queryMetricsTool.handler, 'function');
         });
-        it('should have correct tool name', async () => {
+        void it('should have correct tool name', async () => {
             const { queryMetricsTool } = await import('./query-metrics.js');
             assert.strictEqual(queryMetricsTool.name, 'obs_query_metrics');
         });
-        it('should have descriptive description', async () => {
+        void it('should have descriptive description', async () => {
             const { queryMetricsTool } = await import('./query-metrics.js');
             assert.ok(queryMetricsTool.description.length > 0);
             assert.ok(queryMetricsTool.description.includes('metrics'));
         });
-        it('should have queryMetrics as handler', async () => {
+        void it('should have queryMetrics as handler', async () => {
             const { queryMetricsTool, queryMetrics: handler } = await import('./query-metrics.js');
             assert.strictEqual(queryMetricsTool.handler, handler);
         });