@agentuity/runtime 0.0.42 → 0.0.44

package/src/logger/console.ts

@@ -1,12 +1,114 @@
+import type { LogLevel } from '@agentuity/core';
 import { __originalConsole } from '../otel/logger';
 import type { Logger } from './logger';
 import { formatMessage } from './util';
 
-const yellow = '\x1b[33m';
-const green = '\x1b[32m';
-const red = '\x1b[31m';
-const black = '\x1b[1;30m';
-const reset = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+// Helper to convert hex color to ANSI 24-bit color code
+function hexToAnsi(hex: string): string {
+	const r = parseInt(hex.slice(1, 3), 16);
+	const g = parseInt(hex.slice(3, 5), 16);
+	const b = parseInt(hex.slice(5, 7), 16);
+	return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+interface LogColors {
+	level: string;
+	message: string;
+}
+
+function shouldUseColors(): boolean {
+	// Check for NO_COLOR environment variable (any non-empty value disables colors)
+	if (process.env.NO_COLOR) {
+		return false;
+	}
+
+	// Check for TERM=dumb
+	if (process.env.TERM === 'dumb') {
+		return false;
+	}
+
+	// Check if stdout is a TTY
+	if (!process.stdout || typeof process.stdout.isTTY === 'undefined') {
+		return false;
+	}
+
+	if (process.stdout && typeof process.stdout.isTTY !== 'undefined' && !process.stdout.isTTY) {
+		return false;
+	}
+
+	return true;
+}
+
+type ColorScheme = 'light' | 'dark';
+
+function getLogColors(scheme: ColorScheme): Record<LogLevel, LogColors> {
+	if (scheme === 'light') {
+		// Darker, high-contrast colors for light backgrounds
+		return {
+			trace: {
+				level: hexToAnsi('#008B8B') + BOLD, // Dark cyan
+				message: hexToAnsi('#4B4B4B'), // Dark gray
+			},
+			debug: {
+				level: hexToAnsi('#0000CD') + BOLD, // Medium blue
+				message: hexToAnsi('#006400'), // Dark green
+			},
+			info: {
+				level: hexToAnsi('#FF8C00') + BOLD, // Dark orange
+				message: hexToAnsi('#0066CC') + BOLD, // Strong blue
+			},
+			warn: {
+				level: hexToAnsi('#9400D3') + BOLD, // Dark violet
+				message: hexToAnsi('#8B008B'), // Dark magenta
+			},
+			error: {
+				level: hexToAnsi('#DC143C') + BOLD, // Crimson
+				message: hexToAnsi('#8B0000') + BOLD, // Dark red
+			},
+		};
+	}
+
+	// Dark mode colors (brighter for dark backgrounds)
+	return {
+		trace: {
+			level: hexToAnsi('#00FFFF') + BOLD, // Cyan
+			message: hexToAnsi('#A0A0A0'), // Light gray
+		},
+		debug: {
+			level: hexToAnsi('#5C9CFF') + BOLD, // Blue
+			message: hexToAnsi('#90EE90'), // Light green
+		},
+		info: {
+			level: hexToAnsi('#FFD700') + BOLD, // Gold/Yellow
+			message: hexToAnsi('#FFFFFF') + BOLD, // White
+		},
+		warn: {
+			level: hexToAnsi('#FF00FF') + BOLD, // Magenta
+			message: hexToAnsi('#FF00FF'), // Magenta
+		},
+		error: {
+			level: hexToAnsi('#FF4444') + BOLD, // Red
+			message: hexToAnsi('#FF4444'), // Red
+		},
+	};
+}
+
+// Detect color scheme from environment
+function detectColorScheme(): ColorScheme {
+	const scheme = process.env.COLOR_SCHEME?.toLowerCase();
+	if (scheme === 'light' || scheme === 'dark') {
+		return scheme;
+	}
+	if (process.env.CI) {
+		return 'light';
+	}
+	return 'dark'; // Default to dark mode
+}
+
+const NOCOLORS = Object.freeze({ level: '', reset: '', message: '' });
 
 /**
  * Console implementation of the Logger interface
@@ -14,15 +116,68 @@ const reset = '\x1b[0m';
 export default class ConsoleLogger implements Logger {
 	private context: Record<string, unknown>;
 	private formatContext: boolean;
+	private logLevel: LogLevel;
+	private colors: Record<LogLevel, LogColors>;
+	private detectedTraceLoopLog: boolean | undefined;
+	private useColors: boolean;
 
 	/**
 	 * Creates a new console logger
 	 *
 	 * @param context - Initial context for the logger
 	 */
-	constructor(context: Record<string, unknown> = {}, formatContext = true) {
+	constructor(
+		context: Record<string, unknown> = {},
+		formatContext = true,
+		logLevel: LogLevel = 'info'
+	) {
 		this.context = context;
 		this.formatContext = formatContext;
+		this.logLevel = logLevel;
+		this.useColors = shouldUseColors();
+		this.colors = this.useColors
+			? getLogColors(detectColorScheme())
+			: ({} as Record<LogLevel, LogColors>);
+	}
+
+	private shouldLog(level: LogLevel): boolean {
+		switch (this.logLevel) {
+			case 'trace':
+				return true;
+			case 'debug':
+				return level === 'debug' || level === 'info' || level === 'warn' || level === 'error';
+			case 'info':
+				return level === 'info' || level === 'warn' || level === 'error';
+			case 'warn':
+				return level === 'warn' || level === 'error';
+			case 'error':
+				return level === 'error';
+		}
+		return false;
+	}
+
+	/**
+	 * Log a trace message (most verbose)
+	 *
+	 * @param message - The message to log
+	 * @param args - Additional arguments to log
+	 */
+	trace(message: unknown, ...args: unknown[]): void {
+		if (!this.shouldLog('trace')) {
+			return;
+		}
+		try {
+			const colors = this.useColors ? this.colors.trace : NOCOLORS;
+			const formattedMessage = formatMessage(this.formatContext, this.context, message, args);
+			__originalConsole.debug(
+				`${colors.level}[TRACE]${RESET} ${colors.message}${formattedMessage}${RESET}`
+			);
+		} catch (err) {
+			// Fallback to direct logging if formatting fails
+			const colors = this.colors.trace;
+			__originalConsole.debug(`${colors.level}[TRACE]${RESET} ${message}`, ...args);
+			__originalConsole.error('Error formatting log message:', err);
+		}
 	}
 
 	/**
@@ -32,12 +187,19 @@ export default class ConsoleLogger implements Logger {
 	 * @param args - Additional arguments to log
 	 */
 	debug(message: unknown, ...args: unknown[]): void {
+		if (!this.shouldLog('debug')) {
+			return;
+		}
 		try {
+			const colors = this.useColors ? this.colors.debug : NOCOLORS;
 			const formattedMessage = formatMessage(this.formatContext, this.context, message, args);
-			__originalConsole.debug(`${black}[DEBUG]${reset} ${formattedMessage}`);
+			__originalConsole.debug(
+				`${colors.level}[DEBUG]${RESET} ${colors.message}${formattedMessage}${RESET}`
+			);
 		} catch (err) {
 			// Fallback to direct logging if formatting fails
-			__originalConsole.debug(`${black}[DEBUG]${reset} ${message}`, ...args);
+			const colors = this.colors.debug;
+			__originalConsole.debug(`${colors.level}[DEBUG]${RESET} ${message}`, ...args);
 			__originalConsole.error('Error formatting log message:', err);
 		}
 	}
@@ -49,12 +211,31 @@ export default class ConsoleLogger implements Logger {
 	 * @param args - Additional arguments to log
 	 */
 	info(message: unknown, ...args: unknown[]): void {
+		if (!this.shouldLog('info')) {
+			return;
+		}
+		// suppress the default traceloop message at info level
+		if (
+			!this.detectedTraceLoopLog &&
+			typeof message === 'string' &&
+			message.includes('Traceloop exporting traces to')
+		) {
+			this.detectedTraceLoopLog = true;
+			if (this.shouldLog('debug')) {
+				this.debug(message, ...args);
+			}
+			return;
+		}
 		try {
+			const colors = this.useColors ? this.colors.info : NOCOLORS;
 			const formattedMessage = formatMessage(this.formatContext, this.context, message, args);
-			__originalConsole.info(`${green}[INFO]${reset}  ${formattedMessage}`);
+			__originalConsole.info(
+				`${colors.level}[INFO]${RESET} ${colors.message}${formattedMessage}${RESET}`
+			);
 		} catch (err) {
 			// Fallback to direct logging if formatting fails
-			__originalConsole.info(`${green}[INFO]${reset}  ${message}`, ...args);
+			const colors = this.colors.info;
+			__originalConsole.info(`${colors.level}[INFO]${RESET} ${message}`, ...args);
 			__originalConsole.error('Error formatting log message:', err);
 		}
 	}
@@ -66,12 +247,19 @@ export default class ConsoleLogger implements Logger {
 	 * @param args - Additional arguments to log
 	 */
 	warn(message: unknown, ...args: unknown[]): void {
+		if (!this.shouldLog('warn')) {
+			return;
+		}
 		try {
+			const colors = this.useColors ? this.colors.warn : NOCOLORS;
 			const formattedMessage = formatMessage(this.formatContext, this.context, message, args);
-			__originalConsole.warn(`${yellow}[WARN]${reset}  ${formattedMessage}`);
+			__originalConsole.warn(
+				`${colors.level}[WARN]${RESET}  ${colors.message}${formattedMessage}${RESET}`
+			);
 		} catch (err) {
 			// Fallback to direct logging if formatting fails
-			__originalConsole.warn(`${yellow}[WARN]${reset}  ${message}`, ...args);
+			const colors = this.colors.warn;
+			__originalConsole.warn(`${colors.level}[WARN]${RESET}  ${message}`, ...args);
 			__originalConsole.error('Error formatting log message:', err);
 		}
 	}
@@ -83,16 +271,34 @@ export default class ConsoleLogger implements Logger {
 	 * @param args - Additional arguments to log
 	 */
 	error(message: unknown, ...args: unknown[]): void {
+		if (!this.shouldLog('error')) {
+			return;
+		}
 		try {
+			const colors = this.useColors ? this.colors.error : NOCOLORS;
 			const formattedMessage = formatMessage(this.formatContext, this.context, message, args);
-			__originalConsole.error(`${red}[ERROR]${reset} ${formattedMessage}`);
+			__originalConsole.error(
+				`${colors.level}[ERROR]${RESET} ${colors.message}${formattedMessage}${RESET}`
+			);
 		} catch (err) {
 			// Fallback to direct logging if formatting fails
-			__originalConsole.error(`${red}[ERROR]${reset} ${message}`, ...args);
+			const colors = this.colors.error;
+			__originalConsole.error(`${colors.level}[ERROR]${RESET} ${message}`, ...args);
 			__originalConsole.error('Error formatting log message:', err);
 		}
 	}
 
+	/**
+	 * Log a fatal error message and exit the process
+	 *
+	 * @param message - The message to log
+	 * @param args - Additional arguments to log
+	 */
+	fatal(message: unknown, ...args: unknown[]): never {
+		this.error(message, ...args);
+		process.exit(1);
+	}
+
 	/**
 	 * Create a child logger with additional context
 	 *
@@ -105,7 +311,8 @@ export default class ConsoleLogger implements Logger {
 				...this.context,
 				...opts,
 			},
-			this.formatContext
+			this.formatContext,
+			this.logLevel
 		);
 	}
 }

package/src/logger/index.ts

@@ -1,3 +1,2 @@
 export { internal } from './internal';
-export * from './logger';
 export { type Logger, logger } from './user';

package/src/logger/user.ts

@@ -1,11 +1,15 @@
-import ConsoleLogger from './console';
-import type { Logger } from './logger';
+import { type ColorScheme, createLogger } from '@agentuity/server';
+import type { LogLevel, Logger } from '@agentuity/core';
 
 /**
  * User-facing logger instance
  * This is the logger that SDK consumers should use
  */
-export const logger: Logger = new ConsoleLogger(undefined, false);
+export const logger: Logger = createLogger(
+	(process.env.AGENTUITY_LOG_LEVEL || 'info') as LogLevel,
+	false,
+	(process.env.COLOR_SCHEME ?? 'dark') as ColorScheme
+);
 
 // Re-export the Logger type for convenience
-export type { Logger } from './logger';
+export type { Logger } from '@agentuity/core';

package/src/otel/config.ts

@@ -1,13 +1,8 @@
-import { createResource, createUserLoggerProvider, registerOtel } from './otel';
-import { resourceFromAttributes } from '@opentelemetry/resources';
-import { OtelLogger } from '../otel/logger';
-import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
-import type { LoggerProvider } from '@opentelemetry/sdk-logs';
-import type { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
-import type { LogRecordProcessor } from '@opentelemetry/sdk-logs';
-import type { OtelResponse, OtelConfig } from './otel';
+import type { LogLevel } from '@agentuity/core';
 import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
 import * as runtimeConfig from '../_config';
+import type { OtelConfig, OtelResponse } from './otel';
+import { registerOtel } from './otel';
 
 /**
  * Configuration for user provided OpenTelemetry
@@ -23,6 +18,7 @@ export interface CustomizedOtelConfig {
 
 interface OtelRegisterConfig {
 	processors?: SpanProcessor[];
+	logLevel?: LogLevel;
 }
 
 export function register(registerConfig: OtelRegisterConfig): OtelResponse {
@@ -38,44 +34,11 @@ export function register(registerConfig: OtelRegisterConfig): OtelResponse {
 		projectId: runtimeConfig.getProjectId(),
 		deploymentId: runtimeConfig.getDeploymentId(),
 		environment: runtimeConfig.getEnvironment(),
+		logLevel: registerConfig.logLevel,
+		jsonlBasePath: process.env.AGENTUITY_CLOUD_EXPORT_DIR,
 		bearerToken,
 		url,
 	};
-	let userOtelConf: CustomizedOtelConfig | undefined;
-	if (process.env.AGENTUITY_USER_OTEL_CONF) {
-		try {
-			userOtelConf = JSON.parse(process.env.AGENTUITY_USER_OTEL_CONF);
-		} catch (error) {
-			console.warn(
-				`[WARN] Failed to parse AGENTUITY_USER_OTEL_CONF: ${error instanceof Error ? error.message : String(error)}`
-			);
-		}
-	}
 
-	const otel = registerOtel(config);
-	let userLoggerProvider:
-		| {
-				provider: LoggerProvider;
-				exporter: OTLPLogExporter;
-				processor: LogRecordProcessor;
-		  }
-		| undefined;
-	if (userOtelConf) {
-		const resource = resourceFromAttributes({
-			...createResource(config).attributes,
-			...userOtelConf.resourceAttributes,
-			[ATTR_SERVICE_NAME]: userOtelConf.serviceName,
-		});
-		userLoggerProvider = createUserLoggerProvider({
-			url: userOtelConf.endpoint,
-			headers: userOtelConf.headers,
-			resource,
-		});
-		if (otel.logger instanceof OtelLogger) {
-			otel.logger.addDelegate(userLoggerProvider.provider.getLogger('default'));
-		} else {
-			console.warn('[WARN] user OTEL logger not attached: logger does not support addDelegate');
-		}
-	}
-	return otel;
+	return registerOtel(config);
 }

package/src/otel/console.ts

@@ -1,19 +1,24 @@
 import { SeverityNumber } from '@opentelemetry/api-logs';
 import { type ExportResult, ExportResultCode } from '@opentelemetry/core';
 import type { LogRecordExporter, ReadableLogRecord } from '@opentelemetry/sdk-logs';
-import ConsoleLogger from '../logger/console';
+import { type ColorScheme, createLogger } from '@agentuity/server';
+import type { Logger, LogLevel } from '@agentuity/core';
 
 /**
  * Console implementation of the LogRecordExporter interface
  */
 export class ConsoleLogRecordExporter implements LogRecordExporter {
-	private readonly logger: ConsoleLogger;
+	private readonly logger: Logger;
 
 	/**
 	 * Creates a new console log record exporter
 	 */
-	constructor() {
-		this.logger = new ConsoleLogger();
+	constructor(logLevel: LogLevel) {
+		this.logger = createLogger(
+			logLevel,
+			false,
+			(process.env.COLOR_SCHEME as ColorScheme) ?? 'dark'
+		);
 	}
 
 	/**

package/src/otel/exporters/README.md

@@ -0,0 +1,217 @@
+# JSONL Exporters
+
+Custom OpenTelemetry exporters that write telemetry data (logs, traces, metrics) to JSONL (JSON Lines) files instead of sending directly to an OTLP endpoint.
+
+## Overview
+
+These exporters write telemetry data to local files in JSONL format. Each line in the file represents a single telemetry item in JSON format. This allows for:
+
+1. **Decoupled Processing**: Telemetry data is buffered locally and processed separately
+2. **Reliability**: Data persists even if the OTLP endpoint is temporarily unavailable
+3. **Batch Processing**: A separate cron job can read and send data in batches
+4. **Easy Debugging**: JSONL files can be inspected directly
+
+## How It Works
+
+### 1. Writing Telemetry Data
+
+The exporters write telemetry data to timestamped JSONL files:
+
+- **Logs**: `./otel-data/logs-<timestamp>.jsonl`
+- **Traces**: `./otel-data/traces-<timestamp>.jsonl`
+- **Metrics**: `./otel-data/metrics-<timestamp>.jsonl`
+
+Files are named with an ISO timestamp (with colons and periods replaced by hyphens) to ensure uniqueness. The exporters will continue writing to the same file as long as it exists.
+
+### 2. Reading and Forwarding Data (External Process)
+
+A separate cron job (recommended: every 30 seconds) should:
+
+1. Read the JSONL files
+2. Parse each line as a JSON object
+3. Send the telemetry data to your OTLP endpoint
+4. Delete the file after successful transmission
+
+This decouples the application from the OTLP endpoint and provides resilience.
+
+## Configuration
+
+### Enabling JSONL Exporters
+
+By default, JSONL exporters are enabled. You can configure them via the `OtelConfig`:
+
+```typescript
+import { registerOtel } from '@agentuity/runtime/otel';
+
+registerOtel({
+	name: 'my-app',
+	version: '1.0.0',
+	url: 'https://otel.example.com',
+	useJsonlExporter: true, // Enable JSONL exporters (default: true)
+	jsonlBasePath: './.agentuity/otel-data', // Directory for JSONL files
+});
+```
+
+### Disabling JSONL Exporters
+
+To use the original OTLP exporters (direct network calls):
+
+```typescript
+registerOtel({
+	name: 'my-app',
+	version: '1.0.0',
+	url: 'https://otel.example.com',
+	useJsonlExporter: false, // Disable JSONL, use OTLP directly
+});
+```
+
+## File Format
+
+### Logs
+
+Each log entry contains:
+
+```json
+{
+	"timestamp": [seconds, nanoseconds],
+	"observedTimestamp": [seconds, nanoseconds],
+	"severityNumber": 9,
+	"severityText": "INFO",
+	"body": "Log message",
+	"attributes": { "key": "value" },
+	"resource": { "@agentuity/orgId": "...", ... },
+	"instrumentationScope": { "name": "...", "version": "..." },
+	"spanContext": { "traceId": "...", "spanId": "...", ... }
+}
+```
+
+### Traces
+
+Each span contains:
+
+```json
+{
+	"traceId": "...",
+	"spanId": "...",
+	"traceState": "...",
+	"name": "operation-name",
+	"kind": 1,
+	"startTime": [seconds, nanoseconds],
+	"endTime": [seconds, nanoseconds],
+	"attributes": { "key": "value" },
+	"status": { "code": 0 },
+	"events": [],
+	"links": [],
+	"resource": { "@agentuity/orgId": "...", ... },
+	"droppedAttributesCount": 0,
+	"droppedEventsCount": 0,
+	"droppedLinksCount": 0,
+	"duration": [seconds, nanoseconds],
+	"ended": true
+}
+```
+
+### Metrics
+
+Each metric batch contains:
+
+```json
+{
+	"resource": { "@agentuity/orgId": "...", ... },
+	"scopeMetrics": [
+		{
+			"scope": { "name": "...", "version": "..." },
+			"metrics": [
+				{
+					"descriptor": { "name": "...", "description": "...", ... },
+					"dataPointType": 0,
+					"dataPoints": [...],
+					"aggregationTemporality": 1
+				}
+			]
+		}
+	]
+}
+```
+
+## Example Cron Job
+
+Here's an example script that reads JSONL files and forwards them to OTLP:
+
+```typescript
+#!/usr/bin/env bun
+
+import { readdir, readFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const OTEL_ENDPOINT = process.env.OTEL_ENDPOINT || 'https://otel.agentuity.cloud';
+const OTEL_TOKEN = process.env.OTEL_TOKEN;
+const DATA_DIR = process.env.DATA_DIR || './.agentuity/otel-data';
+
+async function processFiles() {
+	const files = await readdir(DATA_DIR);
+
+	for (const file of files) {
+		if (file.endsWith('.jsonl')) {
+			const filePath = join(DATA_DIR, file);
+			const content = await readFile(filePath, 'utf-8');
+			const lines = content.trim().split('\n');
+
+			const type = file.startsWith('logs-')
+				? 'logs'
+				: file.startsWith('traces-')
+					? 'traces'
+					: 'metrics';
+
+			try {
+				// Send to OTLP endpoint
+				await fetch(`${OTEL_ENDPOINT}/v1/${type}`, {
+					method: 'POST',
+					headers: {
+						'Content-Type': 'application/json',
+						Authorization: `Bearer ${OTEL_TOKEN}`,
+					},
+					body: JSON.stringify({ [type]: lines.map((line) => JSON.parse(line)) }),
+				});
+
+				// Delete file after successful transmission
+				await unlink(filePath);
+				console.log(`Processed and deleted ${file}`);
+			} catch (error) {
+				console.error(`Failed to process ${file}:`, error);
+				// Don't delete the file on error, will retry next time
+			}
+		}
+	}
+}
+
+processFiles().catch(console.error);
+```
+
+Add this to your crontab to run every 30 seconds:
+
+```bash
+* * * * * /path/to/process-otel-data.ts
+* * * * * sleep 30 && /path/to/process-otel-data.ts
+```
+
+## Exporters
+
+### JSONLLogExporter
+
+Implements `LogRecordExporter` interface.
+
+### JSONLTraceExporter
+
+Implements `SpanExporter` interface.
+
+### JSONLMetricExporter
+
+Implements `PushMetricExporter` interface.
+
+## Notes
+
+- Files are written synchronously using `appendFileSync` for simplicity and reliability
+- File existence is checked before each write, creating a new file if necessary
+- Timestamps in filenames use ISO format with special characters replaced by hyphens
+- The exporters handle errors gracefully and report them via the callback mechanism

package/src/otel/exporters/index.ts

@@ -0,0 +1,3 @@
+export { JSONLLogExporter } from './jsonl-log-exporter';
+export { JSONLTraceExporter } from './jsonl-trace-exporter';
+export { JSONLMetricExporter } from './jsonl-metric-exporter';