pi-harness-runtime 0.10.11 → 0.10.12

package/packages/observability/src/tracer.ts

@@ -0,0 +1,336 @@
+/**
+ * Observability Package - Tracer
+ *
+ * Distributed tracing with OpenTelemetry-compatible interface.
+ */
+
+import { randomUUID } from "node:crypto";
+import type {
+	Span,
+	SpanEvent,
+	SpanStatus,
+	StartSpanOptions,
+	TracerConfig,
+} from "./types.js";
+import { Logger } from "./logger.js";
+
+// --- Span Handle -------------------------------------------------------------
+
+export class SpanHandle {
+	private readonly tracer: Tracer;
+	private readonly span: Span;
+	private ended = false;
+
+	constructor(tracer: Tracer, span: Span) {
+		this.tracer = tracer;
+		this.span = span;
+	}
+
+	/**
+	 * End the span
+	 */
+	end(): void {
+		if (this.ended) return;
+		this.ended = true;
+		this.span.endTime = Date.now();
+		this.tracer.recordCompletedSpan(this.span);
+	}
+
+	/**
+	 * Set span status
+	 */
+	setStatus(status: SpanStatus): void {
+		this.span.status = status;
+	}
+
+	/**
+	 * Set an attribute
+	 */
+	setAttribute(key: string, value: string | number | boolean): void {
+		this.span.attributes[key] = value;
+	}
+
+	/**
+	 * Add an event to the span
+	 */
+	addEvent(
+		name: string,
+		attributes?: Record<string, string | number | boolean>,
+	): void {
+		const event: SpanEvent = {
+			name,
+			timestamp: Date.now(),
+			attributes,
+		};
+		this.span.events.push(event);
+	}
+
+	/**
+	 * Record an exception
+	 */
+	recordException(error: Error): void {
+		this.span.status = "error";
+		this.addEvent("exception", {
+			"exception.type": error.name,
+			"exception.message": error.message,
+			"exception.stacktrace": error.stack ?? "",
+		});
+	}
+
+	/**
+	 * Get the underlying span
+	 */
+	getSpan(): Readonly<Span> {
+		return this.span;
+	}
+}
+
+// --- Tracer Class ------------------------------------------------------------
+
+export class Tracer {
+	private readonly config: TracerConfig;
+	private readonly logger: Logger;
+	private readonly spans: Span[] = [];
+	private currentSpan?: SpanHandle;
+
+	constructor(config: TracerConfig) {
+		this.config = config;
+		this.logger = new Logger({ level: config.logLevel ?? "warn" });
+	}
+
+	/**
+	 * Generate a new trace ID
+	 */
+	private generateTraceId(): string {
+		return randomUUID();
+	}
+
+	/**
+	 * Generate a new span ID
+	 */
+	private generateSpanId(): string {
+		return randomUUID().replace(/-/g, "").slice(0, 16);
+	}
+
+	/**
+	 * Start a new span
+	 */
+	startSpan(name: string, options?: StartSpanOptions): SpanHandle {
+		const traceId = this.generateTraceId();
+		const spanId = this.generateSpanId();
+
+		const span: Span = {
+			name,
+			traceId,
+			spanId,
+			parentSpanId: options?.parentSpanId,
+			startTime: Date.now(),
+			status: "ok",
+			attributes: options?.attributes ?? {},
+			events: [],
+			links: options?.links ?? [],
+		};
+
+		const handle = new SpanHandle(this, span);
+		this.currentSpan = handle;
+
+		return handle;
+	}
+
+	/**
+	 * Get the current active span
+	 */
+	getCurrentSpan(): SpanHandle | null {
+		return this.currentSpan ?? null;
+	}
+
+	/**
+	 * Record a completed span (called by SpanHandle)
+	 */
+	recordCompletedSpan(span: Span): void {
+		this.spans.push(span);
+
+		// Export span based on configuration
+		switch (this.config.exporter) {
+			case "console":
+				this.exportToConsole(span);
+				break;
+			case "otlp":
+			case "jaeger":
+				this.exportToOTLP(span);
+				break;
+		}
+
+		// Clear current span if this was the current span
+		if (this.currentSpan?.getSpan() === span) {
+			this.currentSpan = undefined;
+		}
+	}
+
+	/**
+	 * Export span to console
+	 */
+	private exportToConsole(span: Span): void {
+		const duration = span.endTime
+			? span.endTime - span.startTime
+			: Date.now() - span.startTime;
+
+		const output = {
+			service: this.config.serviceName,
+			traceId: span.traceId,
+			spanId: span.spanId,
+			parentSpanId: span.parentSpanId,
+			name: span.name,
+			status: span.status,
+			durationMs: duration,
+			attributes: span.attributes,
+			events: span.events,
+			timestamp: new Date(span.startTime).toISOString(),
+		};
+
+		if (span.status === "error") {
+			console.error("[Tracer]", JSON.stringify(output));
+		} else {
+			console.log("[Tracer]", JSON.stringify(output));
+		}
+	}
+
+	/**
+	 * Export span to OTLP/Jaeger
+	 */
+	private exportToOTLP(span: Span): void {
+		// In a real implementation, this would send to OTLP endpoint
+		if (this.config.endpoint) {
+			this.logger.debug("Exporting span to OTLP", {
+				endpoint: this.config.endpoint,
+				traceId: span.traceId,
+				spanId: span.spanId,
+			});
+		}
+	}
+
+	/**
+	 * Wrap an async function with tracing
+	 */
+	async trace<T>(name: string, fn: () => Promise<T>): Promise<T>;
+	async trace<T>(
+		name: string,
+		options: StartSpanOptions,
+		fn: () => Promise<T>,
+	): Promise<T>;
+	async trace<T>(
+		name: string,
+		optionsOrFn: StartSpanOptions | (() => Promise<T>),
+		fn?: () => Promise<T>,
+	): Promise<T> {
+		const spanOptions: StartSpanOptions | undefined =
+			typeof optionsOrFn === "function" ? undefined : optionsOrFn;
+		const handler: () => Promise<T> =
+			typeof optionsOrFn === "function" ? optionsOrFn : fn!;
+
+		const span = this.startSpan(name, spanOptions);
+
+		try {
+			const result = await handler();
+			span.end();
+			return result;
+		} catch (error) {
+			if (error instanceof Error) {
+				span.recordException(error);
+			}
+			span.end();
+			throw error;
+		}
+	}
+
+	/**
+	 * Wrap a sync function with tracing
+	 */
+	traceSync<T>(name: string, fn: () => T): T;
+	traceSync<T>(name: string, options: StartSpanOptions, fn: () => T): T;
+	traceSync<T>(
+		name: string,
+		optionsOrFn: StartSpanOptions | (() => T),
+		fn?: () => T,
+	): T {
+		const spanOptions: StartSpanOptions | undefined =
+			typeof optionsOrFn === "function" ? undefined : optionsOrFn;
+		const handler: () => T =
+			typeof optionsOrFn === "function" ? optionsOrFn : fn!;
+
+		const span = this.startSpan(name, spanOptions);
+
+		try {
+			const result = handler();
+			span.end();
+			return result;
+		} catch (error) {
+			if (error instanceof Error) {
+				span.recordException(error);
+			}
+			span.end();
+			throw error;
+		}
+	}
+
+	/**
+	 * Record an exception on the current span
+	 */
+	recordException(error: Error): void {
+		if (this.currentSpan) {
+			this.currentSpan.recordException(error);
+		}
+	}
+
+	/**
+	 * Add an event to the current span
+	 */
+	addEvent(
+		name: string,
+		attributes?: Record<string, string | number | boolean>,
+	): void {
+		if (this.currentSpan) {
+			this.currentSpan.addEvent(name, attributes);
+		}
+	}
+
+	/**
+	 * Get all recorded spans
+	 */
+	getSpans(): Readonly<Span>[] {
+		return [...this.spans];
+	}
+
+	/**
+	 * Clear all recorded spans
+	 */
+	clearSpans(): void {
+		this.spans.length = 0;
+	}
+
+	/**
+	 * Export all spans
+	 */
+	exportSpans(): Span[] {
+		return [...this.spans];
+	}
+
+	/**
+	 * Create a child tracer
+	 */
+	childTracer(additionalConfig: Partial<TracerConfig>): Tracer {
+		return new Tracer({
+			...this.config,
+			...additionalConfig,
+		});
+	}
+}
+
+// --- Factory Function --------------------------------------------------------
+
+/**
+ * Create a tracer with the given configuration
+ */
+export function createTracer(config: TracerConfig): Tracer {
+	return new Tracer(config);
+}

package/packages/observability/src/types.ts

@@ -0,0 +1,391 @@
+/**
+ * Observability Package - Types
+ *
+ * Core types for logging, tracing, metrics, and health monitoring.
+ */
+
+// --- SDK Version ------------------------------------------------------------
+
+/**
+ * SDK version for compatibility checks
+ */
+export const SDK_VERSION = "1.0.0";
+
+// --- Log Types ---------------------------------------------------------------
+
+/**
+ * Log severity levels
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+
+/**
+ * Log output format
+ */
+export type LogFormat = "json" | "pretty";
+
+/**
+ * Log output destination
+ */
+export type LogOutput = "stdout" | "stderr" | "file" | "both";
+
+/**
+ * Log entry structure
+ */
+export interface LogEntry {
+	timestamp: string;
+	level: LogLevel;
+	message: string;
+	correlationId?: string;
+	traceId?: string;
+	spanId?: string;
+	jobId?: string;
+	taskId?: string;
+	component?: string;
+	durationMs?: number;
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * Logger configuration
+ */
+export interface LoggerConfig {
+	level?: LogLevel;
+	format?: LogFormat;
+	output?: LogOutput;
+	filePath?: string;
+	maxFileSize?: number;
+	maxFiles?: number;
+	correlationIdHeader?: string;
+	defaultMeta?: Record<string, unknown>;
+}
+
+// --- Trace Types ------------------------------------------------------------
+
+/**
+ * Span status
+ */
+export type SpanStatus = "ok" | "error";
+
+/**
+ * Span event
+ */
+export interface SpanEvent {
+	name: string;
+	timestamp: number;
+	attributes?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Span link
+ */
+export interface SpanLink {
+	traceId: string;
+	spanId: string;
+}
+
+/**
+ * Span
+ */
+export interface Span {
+	name: string;
+	traceId: string;
+	spanId: string;
+	parentSpanId?: string;
+	startTime: number;
+	endTime?: number;
+	status: SpanStatus;
+	attributes: Record<string, string | number | boolean>;
+	events: SpanEvent[];
+	links: SpanLink[];
+}
+
+/**
+ * Start span options
+ */
+export interface StartSpanOptions {
+	parentSpanId?: string;
+	attributes?: Record<string, string | number | boolean>;
+	links?: SpanLink[];
+}
+
+/**
+ * Tracer configuration
+ */
+export interface TracerConfig {
+	serviceName: string;
+	exporter: "console" | "otlp" | "jaeger";
+	endpoint?: string;
+	sampleRate: number;
+	logLevel?: LogLevel;
+}
+
+// --- Metrics Types ----------------------------------------------------------
+
+/**
+ * Metric types
+ */
+export type MetricType = "counter" | "gauge" | "histogram" | "summary";
+
+/**
+ * Labels for metrics
+ */
+export type Labels = Record<string, string>;
+
+/**
+ * Counter metric
+ */
+export interface Counter {
+	name: string;
+	help: string;
+	labels: string[];
+	value: Map<string, number>;
+}
+
+/**
+ * Gauge metric
+ */
+export interface Gauge {
+	name: string;
+	help: string;
+	labels: string[];
+	value: Map<string, number>;
+}
+
+/**
+ * Histogram bucket
+ */
+export interface HistogramBucket {
+	le: number;
+	count: number;
+}
+
+/**
+ * Histogram metric
+ */
+export interface Histogram {
+	name: string;
+	help: string;
+	labels: string[];
+	buckets: HistogramBucket[];
+	sum: Map<string, number>;
+	count: Map<string, number>;
+}
+
+/**
+ * Quantile for summary
+ */
+export interface SummaryQuantile {
+	quantile: number;
+	value: number;
+}
+
+/**
+ * Summary metric
+ */
+export interface Summary {
+	name: string;
+	help: string;
+	labels: string[];
+	quantiles: SummaryQuantile[];
+	sum: Map<string, number>;
+	count: Map<string, number>;
+}
+
+/**
+ * Metrics configuration
+ */
+export interface MetricsConfig {
+	serviceName?: string;
+	defaultLabels?: Labels;
+	exportInterval?: number;
+	prefix?: string;
+}
+
+/**
+ * Prometheus format metric output
+ */
+export interface PrometheusMetric {
+	name: string;
+	help: string;
+	type: MetricType;
+	values: Array<{
+		labels: Labels;
+		value: number;
+	}>;
+}
+
+// --- Health Types -----------------------------------------------------------
+
+/**
+ * Health check result
+ */
+export interface HealthResult {
+	status: "healthy" | "degraded" | "unhealthy";
+	message?: string;
+	details?: Record<string, unknown>;
+	timestamp: string;
+}
+
+/**
+ * Health check function
+ */
+export type HealthCheck = () => Promise<HealthResult>;
+
+/**
+ * Health check registration
+ */
+export interface HealthCheckRegistration {
+	name: string;
+	check: HealthCheck;
+	critical: boolean;
+}
+
+/**
+ * Health report
+ */
+export interface HealthReport {
+	overall: "healthy" | "degraded" | "unhealthy";
+	version: string;
+	uptime: number;
+	checks: Record<string, HealthResult>;
+	timestamp: string;
+}
+
+// --- Alert Types ------------------------------------------------------------
+
+/**
+ * Alert condition types
+ */
+export type AlertConditionType = "threshold" | "rate" | "error_rate";
+
+/**
+ * Threshold condition
+ */
+export interface ThresholdCondition {
+	type: "threshold";
+	metric: string;
+	operator: ">" | "<" | ">=" | "<=" | "==";
+	value: number;
+}
+
+/**
+ * Rate condition
+ */
+export interface RateCondition {
+	type: "rate";
+	metric: string;
+	window: number;
+	threshold: number;
+}
+
+/**
+ * Error rate condition
+ */
+export interface ErrorRateCondition {
+	type: "error_rate";
+	component: string;
+	threshold: number;
+}
+
+/**
+ * Alert condition
+ */
+export type AlertCondition =
+	| ThresholdCondition
+	| RateCondition
+	| ErrorRateCondition;
+
+/**
+ * Alert severity
+ */
+export type AlertSeverity = "info" | "warning" | "critical";
+
+/**
+ * Alert action types
+ */
+export type AlertActionType = "log" | "notify" | "webhook" | "execute";
+
+/**
+ * Log action
+ */
+export interface LogAction {
+	type: "log";
+	level: LogLevel;
+}
+
+/**
+ * Notify action
+ */
+export interface NotifyAction {
+	type: "notify";
+	channel: string;
+	message: string;
+}
+
+/**
+ * Webhook action
+ */
+export interface WebhookAction {
+	type: "webhook";
+	url: string;
+	method?: "GET" | "POST";
+	headers?: Record<string, string>;
+}
+
+/**
+ * Execute action
+ */
+export interface ExecuteAction {
+	type: "execute";
+	command: string;
+}
+
+/**
+ * Alert action
+ */
+export type AlertAction =
+	| LogAction
+	| NotifyAction
+	| WebhookAction
+	| ExecuteAction;
+
+/**
+ * Alert rule
+ */
+export interface AlertRule {
+	name: string;
+	condition: AlertCondition;
+	severity: AlertSeverity;
+	cooldown: number;
+	actions: AlertAction[];
+	enabled?: boolean;
+}
+
+/**
+ * Alert
+ */
+export interface Alert {
+	ruleName: string;
+	severity: AlertSeverity;
+	message: string;
+	triggeredAt: string;
+	resolvedAt?: string;
+	fired: boolean;
+	metadata?: Record<string, unknown>;
+}
+
+// --- Export Types -----------------------------------------------------------
+
+/**
+ * Exporter types
+ */
+export type ExporterType = "prometheus" | "otlp" | "json";
+
+/**
+ * Export result
+ */
+export interface ExportResult {
+	format: ExporterType;
+	content: string;
+	timestamp: string;
+}