@agentuity/runtime 2.0.11 → 3.0.0-alpha.1

package/src/otel/config.ts

@@ -1,47 +0,0 @@
-import type { LogLevel } from '@agentuity/core';
-import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
-import { getServiceUrls } from '@agentuity/server';
-import * as runtimeConfig from '../_config';
-import type { OtelConfig, OtelResponse } from './otel';
-import { registerOtel } from './otel';
-
-/**
- * Configuration for user provided OpenTelemetry
- */
-export interface CustomizedOtelConfig {
-	endpoint: string;
-	// only supports http/json for now
-	// protocol: 'grpc' | 'http/protobuf' | 'http/json';
-	serviceName: string;
-	resourceAttributes: Record<string, string>;
-	headers: Record<string, string>;
-}
-
-interface OtelRegisterConfig {
-	processors?: SpanProcessor[];
-	logLevel?: LogLevel;
-}
-
-export function register(registerConfig: OtelRegisterConfig): OtelResponse {
-	const region = process.env.AGENTUITY_REGION ?? 'usc';
-	const serviceUrls = getServiceUrls(region);
-	const url = serviceUrls.otel;
-	const bearerToken = process.env.AGENTUITY_OTLP_BEARER_TOKEN ?? process.env.AGENTUITY_SDK_KEY;
-	const config: OtelConfig = {
-		spanProcessors: registerConfig.processors,
-		name: runtimeConfig.getAppName(),
-		version: runtimeConfig.getAppVersion(),
-		cliVersion: runtimeConfig.getCLIVersion(),
-		devmode: runtimeConfig.isDevMode(),
-		orgId: runtimeConfig.getOrganizationId(),
-		projectId: runtimeConfig.getProjectId(),
-		deploymentId: runtimeConfig.getDeploymentId(),
-		environment: runtimeConfig.getEnvironment(),
-		logLevel: registerConfig.logLevel,
-		jsonlBasePath: process.env.AGENTUITY_CLOUD_EXPORT_DIR,
-		bearerToken,
-		url,
-	};
-
-	return registerOtel(config);
-}

package/src/otel/console.ts

@@ -1,91 +0,0 @@
-import { SeverityNumber } from '@opentelemetry/api-logs';
-import { type ExportResult, ExportResultCode } from '@opentelemetry/core';
-import type { LogRecordExporter, ReadableLogRecord } from '@opentelemetry/sdk-logs';
-import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
-import { __originalConsole } from './logger';
-
-/**
- * Console implementation of the LogRecordExporter interface
- * Uses __originalConsole to avoid infinite loop when console is patched
- */
-export class ConsoleLogRecordExporter implements LogRecordExporter {
-	private dumpRecords = false;
-
-	constructor(dumpRecords: boolean) {
-		this.dumpRecords = dumpRecords;
-	}
-	/**
-	 * Exports log records to the console
-	 *
-	 * @param logs - The log records to export
-	 * @param resultCallback - Callback function to report the export result
-	 */
-	export(logs: ReadableLogRecord[], resultCallback: (result: ExportResult) => void): void {
-		for (const log of logs) {
-			if (this.dumpRecords) {
-				__originalConsole.log('[LOG]', {
-					body: log.body,
-					severityNumber: log.severityNumber,
-					severityText: log.severityText,
-					timestamp: log.hrTime,
-					attributes: log.attributes,
-					resource: log.resource.attributes,
-				});
-			} else {
-				const severity = log.severityNumber ? SeverityNumber[log.severityNumber] : 'INFO';
-				const msg = `[${severity}] ${log.body}`;
-				switch (log.severityNumber) {
-					case SeverityNumber.DEBUG:
-						__originalConsole.debug(msg);
-						break;
-					case SeverityNumber.INFO:
-						__originalConsole.info(msg);
-						break;
-					case SeverityNumber.WARN:
-						__originalConsole.warn(msg);
-						break;
-					case SeverityNumber.ERROR:
-						__originalConsole.error(msg);
-						break;
-					default:
-						__originalConsole.log(msg);
-						break;
-				}
-			}
-		}
-		resultCallback({ code: ExportResultCode.SUCCESS });
-	}
-
-	/**
-	 * Shuts down the exporter
-	 *
-	 * @returns A promise that resolves when shutdown is complete
-	 */
-	shutdown(): Promise<void> {
-		return Promise.resolve();
-	}
-}
-
-/**
- * Console implementation of the SpanExporter interface
- * Uses __originalConsole to avoid infinite loop when console is patched
- */
-export class DebugSpanExporter implements SpanExporter {
-	export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void {
-		for (const span of spans) {
-			__originalConsole.log('[SPAN]', {
-				name: span.name,
-				traceId: span.spanContext().traceId,
-				spanId: span.spanContext().spanId,
-				duration: span.duration,
-				status: span.status,
-				attributes: span.attributes,
-			});
-		}
-		resultCallback({ code: ExportResultCode.SUCCESS });
-	}
-
-	shutdown(): Promise<void> {
-		return Promise.resolve();
-	}
-}

package/src/otel/exporters/README.md

@@ -1,217 +0,0 @@
-# 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

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

package/src/otel/exporters/jsonl-log-exporter.ts

@@ -1,113 +0,0 @@
-import { type ExportResult, ExportResultCode } from '@opentelemetry/core';
-import type { LogRecordExporter, ReadableLogRecord } from '@opentelemetry/sdk-logs';
-import { existsSync, appendFileSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { randomUUID } from 'node:crypto';
-
-/**
- * JSONL implementation of the LogRecordExporter interface
- * Writes logs to a timestamped JSONL file
- */
-export class JSONLLogExporter implements LogRecordExporter {
-	private currentFile: string | null = null;
-	private readonly basePath: string;
-	private readonly filePrefix: string;
-
-	/**
-	 * Creates a new JSONL log record exporter
-	 * @param basePath - Directory to store the JSONL files
-	 */
-	constructor(basePath: string) {
-		this.basePath = basePath;
-		this.filePrefix = 'otel-log';
-		this.ensureDirectory();
-	}
-
-	private ensureDirectory(): void {
-		if (!existsSync(this.basePath)) {
-			mkdirSync(this.basePath, { recursive: true });
-		}
-	}
-
-	private getOrCreateFile(): string {
-		// If current file exists, use it
-		if (this.currentFile && existsSync(this.currentFile)) {
-			return this.currentFile;
-		}
-
-		this.currentFile = join(
-			this.basePath,
-			`${this.filePrefix}-${Date.now()}.${randomUUID()}.jsonl`
-		);
-		return this.currentFile;
-	}
-
-	/**
-	 * Exports log records to a JSONL file
-	 *
-	 * @param logs - The log records to export
-	 * @param resultCallback - Callback function to report the export result
-	 */
-	export(logs: ReadableLogRecord[], resultCallback: (result: ExportResult) => void): void {
-		try {
-			if (logs.length === 0) {
-				resultCallback({ code: ExportResultCode.SUCCESS });
-				return;
-			}
-			const file = this.getOrCreateFile();
-			const lines: string[] = [];
-			for (const log of logs) {
-				const record = {
-					timestamp: log.hrTime,
-					observedTimestamp: log.hrTimeObserved,
-					severityNumber: log.severityNumber,
-					severityText: log.severityText,
-					body: log.body,
-					attributes: log.attributes,
-					resource: log.resource.attributes,
-					instrumentationScope: log.instrumentationScope,
-					spanContext: log.spanContext,
-				};
-
-				lines.push(JSON.stringify(record));
-			}
-			const payload = `${lines.join('\n')}\n`;
-			try {
-				appendFileSync(file, payload, 'utf-8');
-			} catch (err) {
-				// File may have been deleted, reset and retry once
-				const code = (err as NodeJS.ErrnoException).code;
-				if (code === 'ENOENT') {
-					this.currentFile = null;
-					const newFile = this.getOrCreateFile();
-					appendFileSync(newFile, payload, 'utf-8');
-				} else {
-					throw err;
-				}
-			}
-
-			resultCallback({ code: ExportResultCode.SUCCESS });
-		} catch (error) {
-			resultCallback({
-				code: ExportResultCode.FAILED,
-				error: error instanceof Error ? error : new Error(String(error)),
-			});
-		}
-	}
-
-	/**
-	 * Shuts down the exporter
-	 *
-	 * @returns A promise that resolves when shutdown is complete
-	 */
-	async shutdown(): Promise<void> {
-		this.currentFile = null;
-	}
-
-	/**
-	 * Forces a flush of any pending data
-	 */
-	async forceFlush(): Promise<void> {
-		// No-op for file-based exporter as writes are synchronous
-	}
-}

package/src/otel/exporters/jsonl-metric-exporter.ts

@@ -1,120 +0,0 @@
-import { type ExportResult, ExportResultCode } from '@opentelemetry/core';
-import {
-	type PushMetricExporter,
-	type ResourceMetrics,
-	AggregationTemporality,
-	InstrumentType,
-} from '@opentelemetry/sdk-metrics';
-import { existsSync, appendFileSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { randomUUID } from 'node:crypto';
-
-/**
- * JSONL implementation of the PushMetricExporter interface
- * Writes metrics to a timestamped JSONL file
- */
-export class JSONLMetricExporter implements PushMetricExporter {
-	private currentFile: string | null = null;
-	private readonly basePath: string;
-	private readonly filePrefix: string;
-
-	/**
-	 * Creates a new JSONL metric exporter
-	 * @param basePath - Directory to store the JSONL files
-	 */
-	constructor(basePath: string) {
-		this.basePath = basePath;
-		this.filePrefix = 'otel-metric';
-		this.ensureDirectory();
-	}
-
-	private ensureDirectory(): void {
-		if (!existsSync(this.basePath)) {
-			mkdirSync(this.basePath, { recursive: true });
-		}
-	}
-
-	private getOrCreateFile(): string {
-		// If current file exists, use it
-		if (this.currentFile && existsSync(this.currentFile)) {
-			return this.currentFile;
-		}
-
-		this.currentFile = join(
-			this.basePath,
-			`${this.filePrefix}-${Date.now()}.${randomUUID()}.jsonl`
-		);
-		return this.currentFile;
-	}
-
-	/**
-	 * Exports metrics to a JSONL file
-	 *
-	 * @param metrics - The resource metrics to export
-	 * @param resultCallback - Callback function to report the export result
-	 */
-	export(metrics: ResourceMetrics, resultCallback: (result: ExportResult) => void): void {
-		try {
-			const file = this.getOrCreateFile();
-
-			const record = {
-				resource: metrics.resource.attributes,
-				scopeMetrics: metrics.scopeMetrics.map((sm) => ({
-					scope: sm.scope,
-					metrics: sm.metrics.map((m) => ({
-						descriptor: m.descriptor,
-						dataPointType: m.dataPointType,
-						dataPoints: m.dataPoints,
-						aggregationTemporality: m.aggregationTemporality,
-					})),
-				})),
-			};
-
-			const line = JSON.stringify(record) + '\n';
-			try {
-				appendFileSync(file, line, 'utf-8');
-			} catch (err) {
-				// File may have been deleted, reset and retry once
-				const code = (err as NodeJS.ErrnoException).code;
-				if (code === 'ENOENT') {
-					this.currentFile = null;
-					const newFile = this.getOrCreateFile();
-					appendFileSync(newFile, line, 'utf-8');
-				} else {
-					throw err;
-				}
-			}
-
-			resultCallback({ code: ExportResultCode.SUCCESS });
-		} catch (error) {
-			resultCallback({
-				code: ExportResultCode.FAILED,
-				error: error instanceof Error ? error : new Error(String(error)),
-			});
-		}
-	}
-
-	/**
-	 * Shuts down the exporter
-	 *
-	 * @returns A promise that resolves when shutdown is complete
-	 */
-	async shutdown(): Promise<void> {
-		this.currentFile = null;
-	}
-
-	/**
-	 * Forces a flush of any pending data
-	 */
-	async forceFlush(): Promise<void> {
-		// No-op for file-based exporter as writes are synchronous
-	}
-
-	/**
-	 * Selects the aggregation temporality for the given instrument type
-	 */
-	selectAggregationTemporality?(_instrumentType: InstrumentType): AggregationTemporality {
-		// Default to cumulative temporality
-		return AggregationTemporality.CUMULATIVE;
-	}
-}