@geekmidas/telescope 10.0.0-alpha.99 → 10.0.0

package/src/logger/console.ts

@@ -0,0 +1,230 @@
+import type { Telescope } from '../Telescope';
+
+/**
+ * Logger interface matching @geekmidas/logger
+ */
+export interface Logger {
+	debug: LogFn;
+	info: LogFn;
+	warn: LogFn;
+	error: LogFn;
+	fatal: LogFn;
+	trace: LogFn;
+	child: (obj: object) => Logger;
+}
+
+export type LogFn = {
+	<T extends object>(obj: T, msg?: string, ...args: any[]): void;
+	(msg: string): void;
+};
+
+export interface TelescopeLoggerOptions {
+	/**
+	 * The Telescope instance to send logs to
+	 */
+	telescope: Telescope;
+	/**
+	 * Optional underlying logger to also forward logs to.
+	 * If not provided, logs will only go to Telescope.
+	 */
+	logger?: Logger;
+	/**
+	 * Request ID to associate logs with a specific request.
+	 */
+	requestId?: string;
+	/**
+	 * Initial context data to include in all log messages
+	 */
+	context?: Record<string, unknown>;
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * A logger that sends logs to both Telescope and an optional underlying logger.
+ * Implements the Logger interface from @geekmidas/logger.
+ *
+ * @example
+ * ```typescript
+ * import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
+ * import { TelescopeLogger } from '@geekmidas/telescope/logger/console';
+ * import { ConsoleLogger } from '@geekmidas/logger/console';
+ *
+ * const telescope = new Telescope({ storage: new InMemoryStorage() });
+ *
+ * // With underlying logger (logs to both console and Telescope)
+ * const logger = new TelescopeLogger({
+ *   telescope,
+ *   logger: new ConsoleLogger({ app: 'myApp' }),
+ * });
+ *
+ * // Without underlying logger (logs only to Telescope)
+ * const telescopeOnly = new TelescopeLogger({ telescope });
+ *
+ * // Usage
+ * logger.info({ userId: '123' }, 'User logged in');
+ * logger.error({ error: 'Something failed' }, 'Operation failed');
+ * ```
+ */
+export class TelescopeLogger implements Logger {
+	private telescope: Telescope;
+	private logger?: Logger;
+	private requestId?: string;
+	private context: Record<string, unknown>;
+
+	constructor(options: TelescopeLoggerOptions) {
+		this.telescope = options.telescope;
+		this.logger = options.logger;
+		this.requestId = options.requestId;
+		this.context = options.context ?? {};
+	}
+
+	private createLogFn(level: LogLevel): LogFn {
+		const fn = <T extends object>(
+			objOrMsg: T | string,
+			msg?: string,
+			...args: any[]
+		): void => {
+			let context: Record<string, unknown>;
+			let message: string;
+
+			if (typeof objOrMsg === 'string') {
+				context = { ...this.context };
+				message = objOrMsg;
+			} else {
+				context = { ...this.context, ...objOrMsg };
+				message = msg ?? '';
+			}
+
+			// Forward to underlying logger if present
+			if (this.logger) {
+				if (typeof objOrMsg === 'string') {
+					this.logger[level](objOrMsg);
+				} else {
+					this.logger[level](objOrMsg as any, msg, ...args);
+				}
+			}
+
+			// Send to Telescope (fire and forget)
+			this.telescope[level](message, context, this.requestId).catch(() => {});
+		};
+
+		return fn as LogFn;
+	}
+
+	debug: LogFn = this.createLogFn('debug');
+	info: LogFn = this.createLogFn('info');
+	warn: LogFn = this.createLogFn('warn');
+	error: LogFn = this.createLogFn('error');
+
+	// Map fatal and trace to error and debug for Telescope
+	fatal: LogFn = ((
+		objOrMsg: object | string,
+		msg?: string,
+		...args: any[]
+	): void => {
+		// Forward to underlying logger if present
+		if (this.logger) {
+			if (typeof objOrMsg === 'string') {
+				this.logger.fatal(objOrMsg);
+			} else {
+				this.logger.fatal(objOrMsg as any, msg, ...args);
+			}
+		}
+
+		// Send to Telescope as error level
+		let context: Record<string, unknown>;
+		let message: string;
+
+		if (typeof objOrMsg === 'string') {
+			context = { ...this.context, level: 'fatal' };
+			message = objOrMsg;
+		} else {
+			context = { ...this.context, ...objOrMsg, level: 'fatal' };
+			message = msg ?? '';
+		}
+
+		this.telescope.error(message, context, this.requestId).catch(() => {});
+	}) as LogFn;
+
+	trace: LogFn = ((
+		objOrMsg: object | string,
+		msg?: string,
+		...args: any[]
+	): void => {
+		// Forward to underlying logger if present
+		if (this.logger) {
+			if (typeof objOrMsg === 'string') {
+				this.logger.trace(objOrMsg);
+			} else {
+				this.logger.trace(objOrMsg as any, msg, ...args);
+			}
+		}
+
+		// Send to Telescope as debug level
+		let context: Record<string, unknown>;
+		let message: string;
+
+		if (typeof objOrMsg === 'string') {
+			context = { ...this.context, level: 'trace' };
+			message = objOrMsg;
+		} else {
+			context = { ...this.context, ...objOrMsg, level: 'trace' };
+			message = msg ?? '';
+		}
+
+		this.telescope.debug(message, context, this.requestId).catch(() => {});
+	}) as LogFn;
+
+	/**
+	 * Creates a child logger with additional context.
+	 * The child logger inherits all context from the parent.
+	 */
+	child(obj: object): Logger {
+		return new TelescopeLogger({
+			telescope: this.telescope,
+			logger: this.logger?.child(obj),
+			requestId: this.requestId,
+			context: { ...this.context, ...obj },
+		});
+	}
+
+	/**
+	 * Create a child logger bound to a specific request ID.
+	 * Useful for correlating logs with HTTP requests.
+	 */
+	withRequestId(requestId: string): TelescopeLogger {
+		return new TelescopeLogger({
+			telescope: this.telescope,
+			logger: this.logger,
+			requestId,
+			context: this.context,
+		});
+	}
+}
+
+/**
+ * Create a logger that sends logs to Telescope.
+ * Convenience function for creating a TelescopeLogger.
+ *
+ * @example
+ * ```typescript
+ * import { createTelescopeLogger } from '@geekmidas/telescope/logger/console';
+ * import { ConsoleLogger } from '@geekmidas/logger/console';
+ *
+ * const telescope = new Telescope({ storage: new InMemoryStorage() });
+ * const baseLogger = new ConsoleLogger({ app: 'myApp' });
+ *
+ * const logger = createTelescopeLogger(telescope, baseLogger);
+ * logger.info({ action: 'startup' }, 'Application started');
+ * ```
+ */
+export function createTelescopeLogger(
+	telescope: Telescope,
+	logger?: Logger,
+	context?: Record<string, unknown>,
+): TelescopeLogger {
+	return new TelescopeLogger({ telescope, logger, context });
+}
+
+export type { Telescope };

package/src/logger/pino.ts

@@ -0,0 +1,201 @@
+import build from 'pino-abstract-transport';
+import type { Telescope } from '../Telescope';
+
+/**
+ * Pino log object structure after parsing
+ */
+export interface PinoLogObject {
+	level: number | string;
+	time: number;
+	pid?: number;
+	hostname?: string;
+	msg?: string;
+	[key: string]: unknown;
+}
+
+export interface TelescopePinoTransportOptions {
+	/**
+	 * The Telescope instance to send logs to
+	 */
+	telescope: Telescope;
+	/**
+	 * Request ID to associate logs with a specific request.
+	 * Can be a static string or a function that extracts the ID from log data.
+	 */
+	requestId?: string | ((data: PinoLogObject) => string | undefined);
+	/**
+	 * Batch size before flushing to Telescope (default: 100)
+	 */
+	batchSize?: number;
+	/**
+	 * Flush interval in milliseconds (default: 1000ms)
+	 */
+	flushIntervalMs?: number;
+}
+
+type TelescopeLogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+interface LogBatch {
+	level: TelescopeLogLevel;
+	message: string;
+	context: Record<string, unknown>;
+	requestId?: string;
+}
+
+/**
+ * Map Pino levels to Telescope log levels.
+ * Handles both numeric levels (default pino) and string levels (custom formatters).
+ */
+function mapPinoLevel(level: number | string): TelescopeLogLevel {
+	// Handle string levels (from custom formatters like `level: label => ({ level: label.toUpperCase() })`)
+	if (typeof level === 'string') {
+		const normalized = level.toLowerCase();
+		if (normalized === 'trace' || normalized === 'debug') return 'debug';
+		if (normalized === 'info') return 'info';
+		if (normalized === 'warn' || normalized === 'warning') return 'warn';
+		return 'error'; // error, fatal, or unknown
+	}
+
+	// Pino numeric levels: trace=10, debug=20, info=30, warn=40, error=50, fatal=60
+	if (level <= 20) return 'debug'; // trace, debug
+	if (level <= 30) return 'info';
+	if (level <= 40) return 'warn';
+	return 'error'; // error, fatal
+}
+
+/**
+ * Create a Pino transport that sends logs to Telescope.
+ *
+ * Uses pino-abstract-transport for proper async iteration and backpressure handling.
+ * Logs are batched for performance and flushed either when the batch is full
+ * or after the flush interval.
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino';
+ * import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
+ * import { createPinoTransport } from '@geekmidas/telescope/logger/pino';
+ *
+ * const telescope = new Telescope({ storage: new InMemoryStorage() });
+ *
+ * // Use with pino.multistream to log to both stdout and Telescope
+ * const logger = pino(
+ *   { level: 'debug' },
+ *   pino.multistream([
+ *     { stream: process.stdout },
+ *     { stream: createPinoTransport({ telescope }) }
+ *   ])
+ * );
+ *
+ * logger.info({ userId: '123' }, 'User logged in');
+ * ```
+ */
+export function createPinoTransport(options: TelescopePinoTransportOptions) {
+	const {
+		telescope,
+		requestId,
+		batchSize = 100,
+		flushIntervalMs = 1000,
+	} = options;
+
+	const batch: LogBatch[] = [];
+	let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+	async function flush(): Promise<void> {
+		if (batch.length === 0) return;
+
+		const toFlush = batch.splice(0, batch.length);
+
+		// Use batch insert for better performance
+		try {
+			await telescope.log(toFlush);
+		} catch {
+			// Silently ignore errors to not break logging
+		}
+	}
+
+	function scheduleFlush(): void {
+		if (flushTimer === null) {
+			flushTimer = setTimeout(() => {
+				flushTimer = null;
+				flush().catch(() => {
+					// Silently ignore flush errors
+				});
+			}, flushIntervalMs);
+		}
+	}
+
+	function clearFlushTimer(): void {
+		if (flushTimer !== null) {
+			clearTimeout(flushTimer);
+			flushTimer = null;
+		}
+	}
+
+	return build(
+		async (source) => {
+			for await (const obj of source) {
+				const data = obj as PinoLogObject;
+				const { level, msg, time, pid, hostname, ...context } = data;
+
+				const telescopeLevel = mapPinoLevel(level);
+
+				// Extract request ID
+				let reqId: string | undefined;
+				if (typeof requestId === 'function') {
+					reqId = requestId(data);
+				} else if (typeof requestId === 'string') {
+					reqId = requestId;
+				} else if (typeof context.requestId === 'string') {
+					reqId = context.requestId;
+					delete context.requestId;
+				}
+
+				batch.push({
+					level: telescopeLevel,
+					message: msg || '',
+					context,
+					requestId: reqId,
+				});
+
+				if (batch.length >= batchSize) {
+					clearFlushTimer();
+					await flush();
+				} else {
+					scheduleFlush();
+				}
+			}
+		},
+		{
+			async close() {
+				clearFlushTimer();
+				await flush();
+			},
+		},
+	);
+}
+
+/**
+ * Create a Pino destination that sends logs to Telescope.
+ * Alias for createPinoTransport for API compatibility.
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino';
+ * import { createPinoDestination } from '@geekmidas/telescope/logger/pino';
+ *
+ * const telescope = new Telescope({ storage: new InMemoryStorage() });
+ *
+ * // Use with pino.multistream to log to both stdout and Telescope
+ * const logger = pino(
+ *   { level: 'debug' },
+ *   pino.multistream([
+ *     { stream: process.stdout },
+ *     { stream: createPinoDestination({ telescope }) }
+ *   ])
+ * );
+ * ```
+ */
+export const createPinoDestination = createPinoTransport;
+
+export type { Telescope };