@geekmidas/telescope 1.1.1 → 10.0.0-alpha.0

package/src/metrics/storage/MetricsStorage.ts

@@ -1,74 +0,0 @@
-import type {
-	MetricBucket,
-	MetricPoint,
-	MetricQuery,
-	MetricResult,
-	MetricsStorageConfig,
-	PartitionInfo,
-	RollupOptions,
-} from './types';
-
-/**
- * Interface for metrics storage backends.
- *
- * Implementations can use different storage technologies:
- * - In-memory (development/testing)
- * - PostgreSQL with TimescaleDB
- * - ClickHouse
- * - InfluxDB
- */
-export interface MetricsStorage {
-	/**
-	 * Write raw metric points to storage.
-	 * Points are typically buffered and flushed in batches.
-	 */
-	write(points: MetricPoint[]): Promise<void>;
-
-	/**
-	 * Query metrics with aggregation.
-	 * Returns time series data with statistics.
-	 */
-	query(query: MetricQuery): Promise<MetricResult[]>;
-
-	/**
-	 * Get a single aggregated bucket for a specific time range.
-	 * Useful for dashboards showing current values.
-	 */
-	getBucket(
-		projectId: string,
-		name: string,
-		bucket: Date,
-	): Promise<MetricBucket | null>;
-
-	/**
-	 * Roll up data from one tier to another.
-	 * Aggregates fine-grained data into coarser buckets.
-	 */
-	rollup(options: RollupOptions): Promise<number>;
-
-	/**
-	 * Prune old data based on retention policies.
-	 * Returns the number of records deleted.
-	 */
-	prune(): Promise<number>;
-
-	/**
-	 * List partitions for management and monitoring.
-	 */
-	listPartitions(tier?: string): Promise<PartitionInfo[]>;
-
-	/**
-	 * Get storage configuration.
-	 */
-	getConfig(): MetricsStorageConfig;
-
-	/**
-	 * Flush any buffered data to storage.
-	 */
-	flush(): Promise<void>;
-
-	/**
-	 * Close the storage connection and clean up resources.
-	 */
-	close(): Promise<void>;
-}

package/src/metrics/storage/index.ts

@@ -1,3 +0,0 @@
-export * from './InMemoryMetricsStorage';
-export * from './MetricsStorage';
-export * from './types';

package/src/metrics/storage/types.ts

@@ -1,243 +0,0 @@
-/**
- * Metric types supported by the storage system
- */
-export type MetricType = 'counter' | 'gauge' | 'histogram';
-
-/**
- * Labels/dimensions for metric filtering and grouping
- */
-export type MetricLabels = Record<string, string>;
-
-/**
- * A single metric data point
- */
-export interface MetricPoint {
-	/** Timestamp of the metric */
-	timestamp: Date;
-	/** Project/app identifier for multi-tenant isolation */
-	projectId: string;
-	/** Service name (e.g., 'api', 'worker', 'cron') */
-	service: string;
-	/** Environment (e.g., 'development', 'staging', 'production') */
-	environment: string;
-	/** Metric name (e.g., 'http.request.duration', 'orders.created') */
-	name: string;
-	/** Metric type */
-	type: MetricType;
-	/** Numeric value */
-	value: number;
-	/** Dimensions for filtering/grouping */
-	labels: MetricLabels;
-}
-
-/**
- * Aggregated metric bucket (pre-computed for efficient queries)
- */
-export interface MetricBucket {
-	/** Bucket start timestamp */
-	bucket: Date;
-	/** Project identifier */
-	projectId: string;
-	/** Service name */
-	service: string;
-	/** Environment */
-	environment: string;
-	/** Metric name */
-	name: string;
-	/** Hash of labels for grouping */
-	labelsHash: string;
-	/** Original labels */
-	labels: MetricLabels;
-	/** Number of data points in bucket */
-	count: number;
-	/** Sum of values */
-	sum: number;
-	/** Minimum value */
-	min: number;
-	/** Maximum value */
-	max: number;
-	/** T-Digest sketch for percentile calculations (serialized) */
-	sketch?: TDigestData;
-}
-
-/**
- * Serialized T-Digest data structure for percentile calculations
- * Stores centroids (mean, weight) that can be merged across buckets
- */
-export interface TDigestData {
-	/** Centroids: [mean, weight][] */
-	centroids: [number, number][];
-	/** Compression factor (higher = more accuracy, more memory) */
-	compression: number;
-	/** Total count of values */
-	count: number;
-	/** Minimum value seen */
-	min: number;
-	/** Maximum value seen */
-	max: number;
-}
-
-/**
- * Time range for queries
- */
-export interface TimeRange {
-	start: Date;
-	end: Date;
-}
-
-/**
- * Aggregation granularity
- */
-export type AggregationInterval = '1m' | '5m' | '15m' | '1h' | '6h' | '1d';
-
-/**
- * Query parameters for retrieving metrics
- */
-export interface MetricQuery {
-	/** Project filter (required for multi-tenant) */
-	projectId: string;
-	/** Optional service filter */
-	service?: string;
-	/** Optional environment filter */
-	environment?: string;
-	/** Metric name pattern (supports wildcards like 'http.*') */
-	name?: string;
-	/** Label filters */
-	labels?: MetricLabels;
-	/** Time range */
-	range: TimeRange;
-	/** Aggregation interval */
-	interval?: AggregationInterval;
-	/** Group by these label keys */
-	groupBy?: string[];
-	/** Maximum number of results */
-	limit?: number;
-}
-
-/**
- * Query result with aggregated values
- */
-export interface MetricResult {
-	/** Metric name */
-	name: string;
-	/** Labels (grouped by keys if specified) */
-	labels: MetricLabels;
-	/** Time series data points */
-	timeSeries: MetricTimeSeriesPoint[];
-	/** Overall statistics for the query range */
-	stats: {
-		count: number;
-		sum: number;
-		avg: number;
-		min: number;
-		max: number;
-		p50: number;
-		p95: number;
-		p99: number;
-	};
-}
-
-/**
- * Single point in a time series result
- */
-export interface MetricTimeSeriesPoint {
-	timestamp: Date;
-	count: number;
-	sum: number;
-	avg: number;
-	min: number;
-	max: number;
-	p50?: number;
-	p95?: number;
-	p99?: number;
-}
-
-/**
- * Storage tier configuration
- */
-export interface StorageTier {
-	/** Table/collection name for this tier */
-	name: string;
-	/** Bucket interval for aggregation */
-	interval: AggregationInterval;
-	/** Retention duration in milliseconds (0 = forever) */
-	retention: number;
-	/** Partition interval for efficient pruning */
-	partitionInterval: 'hourly' | 'daily' | 'weekly' | 'monthly';
-}
-
-/**
- * Metrics storage configuration
- */
-export interface MetricsStorageConfig {
-	/** Storage tiers (raw, minute, hourly, etc.) */
-	tiers: StorageTier[];
-	/** Flush interval in milliseconds */
-	flushInterval: number;
-	/** Maximum batch size for writes */
-	maxBatchSize: number;
-	/** Enable automatic rollup between tiers */
-	autoRollup: boolean;
-	/** T-Digest compression factor (default: 100) */
-	tdigestCompression: number;
-}
-
-/**
- * Default configuration with hybrid storage strategy
- */
-export const DEFAULT_METRICS_CONFIG: MetricsStorageConfig = {
-	tiers: [
-		{
-			name: 'raw',
-			interval: '1m',
-			retention: 60 * 60 * 1000, // 1 hour
-			partitionInterval: 'hourly',
-		},
-		{
-			name: '1m',
-			interval: '1m',
-			retention: 7 * 24 * 60 * 60 * 1000, // 7 days
-			partitionInterval: 'daily',
-		},
-		{
-			name: '1h',
-			interval: '1h',
-			retention: 0, // Forever
-			partitionInterval: 'monthly',
-		},
-	],
-	flushInterval: 10_000, // 10 seconds
-	maxBatchSize: 1000,
-	autoRollup: true,
-	tdigestCompression: 100,
-};
-
-/**
- * Rollup options for aggregating data between tiers
- */
-export interface RollupOptions {
-	/** Source tier */
-	from: string;
-	/** Target tier */
-	to: string;
-	/** Only rollup data older than this */
-	olderThan: Date;
-}
-
-/**
- * Partition info for management
- */
-export interface PartitionInfo {
-	/** Partition name */
-	name: string;
-	/** Tier this partition belongs to */
-	tier: string;
-	/** Partition start time */
-	start: Date;
-	/** Partition end time */
-	end: Date;
-	/** Approximate row count */
-	rowCount?: number;
-	/** Size in bytes */
-	sizeBytes?: number;
-}

package/src/otlp/__tests__/receiver.spec.ts

@@ -1,367 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { InMemoryStorage } from '../../storage/memory';
-import { Telescope } from '../../Telescope';
-import { OTLPReceiver } from '../receiver';
-import {
-	type ExportLogsServiceRequest,
-	type ExportMetricsServiceRequest,
-	type ExportTraceServiceRequest,
-	SeverityNumber,
-	SpanKind,
-	SpanStatusCode,
-} from '../types';
-
-describe('OTLPReceiver', () => {
-	let telescope: Telescope;
-	let storage: InMemoryStorage;
-	let receiver: OTLPReceiver;
-
-	beforeEach(() => {
-		storage = new InMemoryStorage();
-		telescope = new Telescope({ storage });
-		receiver = new OTLPReceiver({ telescope });
-	});
-
-	afterEach(() => {
-		telescope.destroy();
-	});
-
-	describe('receiveTraces', () => {
-		it('should record HTTP server spans as requests', async () => {
-			const request: ExportTraceServiceRequest = {
-				resourceSpans: [
-					{
-						resource: {
-							attributes: [
-								{ key: 'service.name', value: { stringValue: 'test-api' } },
-							],
-						},
-						scopeSpans: [
-							{
-								spans: [
-									{
-										traceId: 'abc123',
-										spanId: 'def456',
-										name: 'GET /users',
-										kind: SpanKind.SPAN_KIND_SERVER,
-										startTimeUnixNano: '1704067200000000000',
-										endTimeUnixNano: '1704067200050000000',
-										attributes: [
-											{ key: 'http.method', value: { stringValue: 'GET' } },
-											{ key: 'http.target', value: { stringValue: '/users' } },
-											{ key: 'http.status_code', value: { intValue: '200' } },
-										],
-										status: { code: SpanStatusCode.STATUS_CODE_OK },
-									},
-								],
-							},
-						],
-					},
-				],
-			};
-
-			const response = await receiver.receiveTraces(request);
-
-			expect(response.partialSuccess).toBeUndefined();
-
-			const requests = await telescope.getRequests();
-			expect(requests).toHaveLength(1);
-			expect(requests[0].method).toBe('GET');
-			expect(requests[0].path).toBe('/users');
-			expect(requests[0].status).toBe(200);
-		});
-
-		it('should handle multiple spans', async () => {
-			const request: ExportTraceServiceRequest = {
-				resourceSpans: [
-					{
-						scopeSpans: [
-							{
-								spans: [
-									{
-										traceId: 'abc123',
-										spanId: 'span1',
-										name: 'GET /users',
-										kind: SpanKind.SPAN_KIND_SERVER,
-										startTimeUnixNano: '1704067200000000000',
-										endTimeUnixNano: '1704067200050000000',
-										attributes: [
-											{ key: 'http.method', value: { stringValue: 'GET' } },
-											{ key: 'http.target', value: { stringValue: '/users' } },
-											{ key: 'http.status_code', value: { intValue: '200' } },
-										],
-									},
-									{
-										traceId: 'abc123',
-										spanId: 'span2',
-										name: 'POST /users',
-										kind: SpanKind.SPAN_KIND_SERVER,
-										startTimeUnixNano: '1704067200100000000',
-										endTimeUnixNano: '1704067200200000000',
-										attributes: [
-											{ key: 'http.method', value: { stringValue: 'POST' } },
-											{ key: 'http.target', value: { stringValue: '/users' } },
-											{ key: 'http.status_code', value: { intValue: '201' } },
-										],
-									},
-								],
-							},
-						],
-					},
-				],
-			};
-
-			await receiver.receiveTraces(request);
-
-			const requests = await telescope.getRequests();
-			expect(requests).toHaveLength(2);
-		});
-
-		it('should return empty response for empty request', async () => {
-			const response = await receiver.receiveTraces({});
-			expect(response).toEqual({});
-		});
-	});
-
-	describe('receiveLogs', () => {
-		it('should record log entries', async () => {
-			const request: ExportLogsServiceRequest = {
-				resourceLogs: [
-					{
-						scopeLogs: [
-							{
-								logRecords: [
-									{
-										observedTimeUnixNano: '1704067200000000000',
-										severityNumber: SeverityNumber.SEVERITY_NUMBER_INFO,
-										body: { stringValue: 'User logged in' },
-										attributes: [
-											{ key: 'userId', value: { stringValue: '123' } },
-										],
-									},
-								],
-							},
-						],
-					},
-				],
-			};
-
-			const response = await receiver.receiveLogs(request);
-
-			expect(response.partialSuccess).toBeUndefined();
-
-			const logs = await telescope.getLogs();
-			expect(logs).toHaveLength(1);
-			expect(logs[0].level).toBe('info');
-			expect(logs[0].message).toBe('User logged in');
-		});
-
-		it('should batch multiple log records', async () => {
-			const request: ExportLogsServiceRequest = {
-				resourceLogs: [
-					{
-						scopeLogs: [
-							{
-								logRecords: [
-									{
-										observedTimeUnixNano: '1704067200000000000',
-										severityNumber: SeverityNumber.SEVERITY_NUMBER_INFO,
-										body: { stringValue: 'Log 1' },
-									},
-									{
-										observedTimeUnixNano: '1704067200001000000',
-										severityNumber: SeverityNumber.SEVERITY_NUMBER_DEBUG,
-										body: { stringValue: 'Log 2' },
-									},
-									{
-										observedTimeUnixNano: '1704067200002000000',
-										severityNumber: SeverityNumber.SEVERITY_NUMBER_WARN,
-										body: { stringValue: 'Log 3' },
-									},
-								],
-							},
-						],
-					},
-				],
-			};
-
-			await receiver.receiveLogs(request);
-
-			const logs = await telescope.getLogs();
-			expect(logs).toHaveLength(3);
-		});
-
-		it('should return empty response for empty request', async () => {
-			const response = await receiver.receiveLogs({});
-			expect(response).toEqual({});
-		});
-	});
-
-	describe('receiveMetrics', () => {
-		it('should call onMetrics handler', async () => {
-			const onMetrics = vi.fn();
-			const receiverWithHandler = new OTLPReceiver({
-				telescope,
-				onMetrics,
-			});
-
-			const request: ExportMetricsServiceRequest = {
-				resourceMetrics: [
-					{
-						scopeMetrics: [
-							{
-								metrics: [
-									{
-										name: 'http_requests_total',
-										sum: {
-											dataPoints: [
-												{
-													timeUnixNano: '1704067200000000000',
-													asInt: '100',
-												},
-											],
-											aggregationTemporality: 2,
-										},
-									},
-								],
-							},
-						],
-					},
-				],
-			};
-
-			const response = await receiverWithHandler.receiveMetrics(request);
-
-			expect(response.partialSuccess).toBeUndefined();
-			expect(onMetrics).toHaveBeenCalledTimes(1);
-			expect(onMetrics).toHaveBeenCalledWith(
-				expect.arrayContaining([
-					expect.objectContaining({
-						name: 'http_requests_total',
-						value: 100,
-						type: 'sum',
-					}),
-				]),
-			);
-		});
-
-		it('should log metrics when logMetrics is enabled', async () => {
-			const receiverWithLogging = new OTLPReceiver({
-				telescope,
-				logMetrics: true,
-			});
-
-			const request: ExportMetricsServiceRequest = {
-				resourceMetrics: [
-					{
-						scopeMetrics: [
-							{
-								metrics: [
-									{
-										name: 'cpu_usage',
-										gauge: {
-											dataPoints: [
-												{
-													timeUnixNano: '1704067200000000000',
-													asDouble: 45.5,
-												},
-											],
-										},
-									},
-								],
-							},
-						],
-					},
-				],
-			};
-
-			await receiverWithLogging.receiveMetrics(request);
-
-			const logs = await telescope.getLogs();
-			expect(logs).toHaveLength(1);
-			expect(logs[0].message).toBe('OTLP Metric: cpu_usage');
-			expect(logs[0].level).toBe('debug');
-		});
-
-		it('should return empty response when no handler', async () => {
-			const response = await receiver.receiveMetrics({});
-			expect(response).toEqual({});
-		});
-
-		it('should report partial success on handler error', async () => {
-			const onMetrics = vi.fn().mockRejectedValue(new Error('Handler failed'));
-			const receiverWithHandler = new OTLPReceiver({
-				telescope,
-				onMetrics,
-			});
-
-			const request: ExportMetricsServiceRequest = {
-				resourceMetrics: [
-					{
-						scopeMetrics: [
-							{
-								metrics: [
-									{
-										name: 'test_metric',
-										gauge: {
-											dataPoints: [
-												{
-													timeUnixNano: '1704067200000000000',
-													asDouble: 1,
-												},
-											],
-										},
-									},
-								],
-							},
-						],
-					},
-				],
-			};
-
-			const response = await receiverWithHandler.receiveMetrics(request);
-
-			expect(response.partialSuccess).toBeDefined();
-			expect(response.partialSuccess?.rejectedDataPoints).toBe('1');
-		});
-	});
-
-	describe('integration with Telescope', () => {
-		it('should update metrics aggregator via recordRequest', async () => {
-			const request: ExportTraceServiceRequest = {
-				resourceSpans: [
-					{
-						scopeSpans: [
-							{
-								spans: [
-									{
-										traceId: 'abc123',
-										spanId: 'def456',
-										name: 'GET /api/test',
-										kind: SpanKind.SPAN_KIND_SERVER,
-										startTimeUnixNano: '1704067200000000000',
-										endTimeUnixNano: '1704067200100000000',
-										attributes: [
-											{ key: 'http.method', value: { stringValue: 'GET' } },
-											{
-												key: 'http.target',
-												value: { stringValue: '/api/test' },
-											},
-											{ key: 'http.status_code', value: { intValue: '200' } },
-										],
-									},
-								],
-							},
-						],
-					},
-				],
-			};
-
-			await receiver.receiveTraces(request);
-
-			// The Telescope's metrics aggregator should have the request
-			const metrics = telescope.getMetrics();
-			expect(metrics.totalRequests).toBe(1);
-		});
-	});
-});