@agentium/observability 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,279 @@
+import { EventBus, Agent } from '@agentium/core';
+
+type SpanKind = "agent" | "llm" | "tool" | "guardrail" | "memory" | "cache" | "handoff" | "team" | "workflow" | "internal";
+type SpanStatus = "ok" | "error" | "running";
+interface SpanEvent {
+    name: string;
+    timestamp: number;
+    attributes?: Record<string, unknown>;
+}
+interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: SpanKind;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    status: SpanStatus;
+    attributes: Record<string, unknown>;
+    events: SpanEvent[];
+}
+interface Trace {
+    traceId: string;
+    spans: Span[];
+    rootSpanId: string;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    metadata: Record<string, unknown>;
+}
+interface TraceExporter {
+    name: string;
+    export(trace: Trace): Promise<void>;
+    flush?(): Promise<void>;
+    shutdown?(): Promise<void>;
+}
+interface MetricsSnapshot {
+    counters: {
+        runs_total: number;
+        runs_success: number;
+        runs_error: number;
+        tool_calls_total: number;
+        handoffs_total: number;
+        cache_hits: number;
+        cache_misses: number;
+    };
+    histograms: {
+        run_duration_ms: number[];
+        tool_latency_ms: number[];
+    };
+    gauges: {
+        total_cost_usd: number;
+        total_tokens: number;
+        prompt_tokens: number;
+        completion_tokens: number;
+        reasoning_tokens: number;
+        cached_tokens: number;
+        audio_input_tokens: number;
+        audio_output_tokens: number;
+    };
+    rates: {
+        cache_hit_ratio: number;
+        error_rate: number;
+    };
+    timestamp: number;
+}
+type ExporterShorthand = "console" | "langfuse" | "json-file" | "otel";
+interface ObservabilityConfig {
+    /** Exporter instances or shorthand strings like "console", "langfuse". */
+    exporters?: (TraceExporter | ExporterShorthand)[];
+    metrics?: boolean;
+    structuredLogs?: boolean | LogDrain;
+}
+type LogDrain = "console" | "json" | ((entry: LogEntry) => void);
+interface LogEntry {
+    timestamp: string;
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+    traceId?: string;
+    spanId?: string;
+    agentName?: string;
+    attributes?: Record<string, unknown>;
+}
+
+declare class CallbackExporter implements TraceExporter {
+    name: string;
+    private callback;
+    constructor(callback: (trace: Trace) => void | Promise<void>);
+    export(trace: Trace): Promise<void>;
+}
+
+declare class ConsoleExporter implements TraceExporter {
+    name: string;
+    export(trace: Trace): Promise<void>;
+    private printSpan;
+}
+
+interface JsonFileExporterConfig {
+    path?: string;
+    mode?: "overwrite" | "append";
+    pretty?: boolean;
+}
+declare class JsonFileExporter implements TraceExporter {
+    name: string;
+    private path;
+    private mode;
+    private pretty;
+    constructor(config?: JsonFileExporterConfig);
+    export(trace: Trace): Promise<void>;
+}
+
+interface LangfuseExporterConfig {
+    /** Defaults to LANGFUSE_PUBLIC_KEY env var. */
+    publicKey?: string;
+    /** Defaults to LANGFUSE_SECRET_KEY env var. */
+    secretKey?: string;
+    /** Defaults to LANGFUSE_BASE_URL env var or https://cloud.langfuse.com. */
+    baseUrl?: string;
+}
+declare class LangfuseExporter implements TraceExporter {
+    name: string;
+    private publicKey;
+    private secretKey;
+    private baseUrl;
+    constructor(config?: LangfuseExporterConfig);
+    private fetchWithRetry;
+    export(trace: Trace): Promise<void>;
+}
+
+interface OTelExporterConfig {
+    /** Defaults to OTEL_EXPORTER_OTLP_ENDPOINT env var. */
+    endpoint?: string;
+    /** Defaults to OTEL_EXPORTER_OTLP_HEADERS env var (comma-separated key=value pairs). */
+    headers?: Record<string, string>;
+    protocol?: "http/json" | "http/protobuf";
+    /** Defaults to OTEL_SERVICE_NAME env var or "agentium". */
+    serviceName?: string;
+}
+declare class OTelExporter implements TraceExporter {
+    name: string;
+    private endpoint;
+    private headers;
+    private serviceName;
+    constructor(config?: OTelExporterConfig);
+    private fetchWithRetry;
+    export(trace: Trace): Promise<void>;
+    private padHex;
+    private mapKind;
+    private toOtlpValue;
+}
+
+declare class MetricsCollector {
+    private counters;
+    private histograms;
+    private gauges;
+    private readonly MAX_HISTOGRAM_SIZE;
+    private toolStartTimes;
+    private runStartTimes;
+    private listeners;
+    attach(eventBus: EventBus): void;
+    detach(eventBus: EventBus): void;
+    getMetrics(): MetricsSnapshot;
+    reset(): void;
+}
+
+declare class Tracer {
+    private traces;
+    private runToTrace;
+    private runToRootSpan;
+    private activeSpans;
+    private exporters;
+    private listeners;
+    private pendingExports;
+    private maxTraces;
+    constructor(exporters?: TraceExporter[]);
+    attach(eventBus: EventBus): void;
+    detach(eventBus: EventBus): void;
+    getTrace(traceId: string): Trace | undefined;
+    getTraceByRunId(runId: string): Trace | undefined;
+    getAllTraces(): Trace[];
+    clear(): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private startSpan;
+    private endSpan;
+    private finalizeTrace;
+    private runExporters;
+}
+
+declare class StructuredLogger {
+    private drain;
+    private tracer;
+    private listeners;
+    constructor(drain?: LogDrain, tracer?: Tracer);
+    attach(eventBus: EventBus): void;
+    detach(eventBus: EventBus): void;
+    private log;
+}
+
+interface InstrumentResult {
+    tracer: Tracer;
+    metrics: MetricsCollector | null;
+    logger: StructuredLogger | null;
+    detach: () => void;
+}
+/**
+ * Attach observability to an agent in one call.
+ *
+ * ```ts
+ * import { instrument } from "@agentium/observability";
+ *
+ * // Minimal — just pass string shorthands:
+ * const obs = instrument(agent, { exporters: ["langfuse", "console"] });
+ *
+ * // Or bring your own exporter instances for custom config:
+ * const obs = instrument(agent, {
+ *   exporters: [new LangfuseExporter({ baseUrl: "..." }), "console"],
+ * });
+ * ```
+ */
+declare function instrument(agent: Agent, config?: ObservabilityConfig): InstrumentResult;
+/**
+ * Attach observability to a raw EventBus (for teams, workflows, or custom setups).
+ */
+declare function instrumentBus(eventBus: EventBus, config?: ObservabilityConfig): InstrumentResult;
+
+interface AgentMetrics {
+    runs: number;
+    errors: number;
+    avgDurationMs: number;
+    p95DurationMs: number;
+    totalCost: number;
+    totalTokens: number;
+    promptTokens: number;
+    completionTokens: number;
+    reasoningTokens: number;
+    cachedTokens: number;
+    audioInputTokens: number;
+    audioOutputTokens: number;
+    toolCallCount: number;
+    toolUsageFrequency: Record<string, number>;
+    errorRate: number;
+    tokensPerRun: number;
+    /** Estimated total KV cache memory (GB) across all sessions. Requires capacity module. */
+    estimatedKvCacheGb?: number;
+    /** Average context length (tokens) per run. */
+    avgContextLength?: number;
+    /** Session count by category (light/medium/heavy/extreme). */
+    sessionCategories?: Record<string, number>;
+}
+interface MetricEvent {
+    type: string;
+    agentName?: string;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+declare class MetricsExporter {
+    private runs;
+    private toolUsage;
+    private runStartTimes;
+    private runToolCounts;
+    private listeners;
+    private subscribers;
+    private maxRecords;
+    private sessionCategories;
+    private estimatedKvCacheGb?;
+    attach(eventBus: EventBus): void;
+    detach(eventBus: EventBus): void;
+    private addRecord;
+    private emit;
+    getMetrics(agentName?: string): AgentMetrics;
+    toPrometheus(): string;
+    toJSON(): object;
+    stream(): AsyncIterable<MetricEvent>;
+    reset(): void;
+}
+
+export { type AgentMetrics, CallbackExporter, ConsoleExporter, type ExporterShorthand, type InstrumentResult, JsonFileExporter, type JsonFileExporterConfig, LangfuseExporter, type LangfuseExporterConfig, type LogDrain, type LogEntry, type MetricEvent, MetricsCollector, MetricsExporter, type MetricsSnapshot, OTelExporter, type OTelExporterConfig, type ObservabilityConfig, type Span, type SpanEvent, type SpanKind, type SpanStatus, StructuredLogger, type Trace, type TraceExporter, Tracer, instrument, instrumentBus };

package/dist/index.d.ts

@@ -0,0 +1,279 @@
+import { EventBus, Agent } from '@agentium/core';
+
+type SpanKind = "agent" | "llm" | "tool" | "guardrail" | "memory" | "cache" | "handoff" | "team" | "workflow" | "internal";
+type SpanStatus = "ok" | "error" | "running";
+interface SpanEvent {
+    name: string;
+    timestamp: number;
+    attributes?: Record<string, unknown>;
+}
+interface Span {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: SpanKind;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    status: SpanStatus;
+    attributes: Record<string, unknown>;
+    events: SpanEvent[];
+}
+interface Trace {
+    traceId: string;
+    spans: Span[];
+    rootSpanId: string;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    metadata: Record<string, unknown>;
+}
+interface TraceExporter {
+    name: string;
+    export(trace: Trace): Promise<void>;
+    flush?(): Promise<void>;
+    shutdown?(): Promise<void>;
+}
+interface MetricsSnapshot {
+    counters: {
+        runs_total: number;
+        runs_success: number;
+        runs_error: number;
+        tool_calls_total: number;
+        handoffs_total: number;
+        cache_hits: number;
+        cache_misses: number;
+    };
+    histograms: {
+        run_duration_ms: number[];
+        tool_latency_ms: number[];
+    };
+    gauges: {
+        total_cost_usd: number;
+        total_tokens: number;
+        prompt_tokens: number;
+        completion_tokens: number;
+        reasoning_tokens: number;
+        cached_tokens: number;
+        audio_input_tokens: number;
+        audio_output_tokens: number;
+    };
+    rates: {
+        cache_hit_ratio: number;
+        error_rate: number;
+    };
+    timestamp: number;
+}
+type ExporterShorthand = "console" | "langfuse" | "json-file" | "otel";
+interface ObservabilityConfig {
+    /** Exporter instances or shorthand strings like "console", "langfuse". */
+    exporters?: (TraceExporter | ExporterShorthand)[];
+    metrics?: boolean;
+    structuredLogs?: boolean | LogDrain;
+}
+type LogDrain = "console" | "json" | ((entry: LogEntry) => void);
+interface LogEntry {
+    timestamp: string;
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+    traceId?: string;
+    spanId?: string;
+    agentName?: string;
+    attributes?: Record<string, unknown>;
+}
+
+declare class CallbackExporter implements TraceExporter {
+    name: string;
+    private callback;
+    constructor(callback: (trace: Trace) => void | Promise<void>);
+    export(trace: Trace): Promise<void>;
+}
+
+declare class ConsoleExporter implements TraceExporter {
+    name: string;
+    export(trace: Trace): Promise<void>;
+    private printSpan;
+}
+
+interface JsonFileExporterConfig {
+    path?: string;
+    mode?: "overwrite" | "append";
+    pretty?: boolean;
+}
+declare class JsonFileExporter implements TraceExporter {
+    name: string;
+    private path;
+    private mode;
+    private pretty;
+    constructor(config?: JsonFileExporterConfig);
+    export(trace: Trace): Promise<void>;
+}
+
+interface LangfuseExporterConfig {
+    /** Defaults to LANGFUSE_PUBLIC_KEY env var. */
+    publicKey?: string;
+    /** Defaults to LANGFUSE_SECRET_KEY env var. */
+    secretKey?: string;
+    /** Defaults to LANGFUSE_BASE_URL env var or https://cloud.langfuse.com. */
+    baseUrl?: string;
+}
+declare class LangfuseExporter implements TraceExporter {
+    name: string;
+    private publicKey;
+    private secretKey;
+    private baseUrl;
+    constructor(config?: LangfuseExporterConfig);
+    private fetchWithRetry;
+    export(trace: Trace): Promise<void>;
+}
+
+interface OTelExporterConfig {
+    /** Defaults to OTEL_EXPORTER_OTLP_ENDPOINT env var. */
+    endpoint?: string;
+    /** Defaults to OTEL_EXPORTER_OTLP_HEADERS env var (comma-separated key=value pairs). */
+    headers?: Record<string, string>;
+    protocol?: "http/json" | "http/protobuf";
+    /** Defaults to OTEL_SERVICE_NAME env var or "agentium". */
+    serviceName?: string;
+}
+declare class OTelExporter implements TraceExporter {
+    name: string;
+    private endpoint;
+    private headers;
+    private serviceName;
+    constructor(config?: OTelExporterConfig);
+    private fetchWithRetry;
+    export(trace: Trace): Promise<void>;
+    private padHex;
+    private mapKind;
+    private toOtlpValue;
+}
+
+declare class MetricsCollector {
+    private counters;
+    private histograms;
+    private gauges;
+    private readonly MAX_HISTOGRAM_SIZE;
+    private toolStartTimes;
+    private runStartTimes;
+    private listeners;
+    attach(eventBus: EventBus): void;
+    detach(eventBus: EventBus): void;
+    getMetrics(): MetricsSnapshot;
+    reset(): void;
+}
+
+declare class Tracer {
+    private traces;
+    private runToTrace;
+    private runToRootSpan;
+    private activeSpans;
+    private exporters;
+    private listeners;
+    private pendingExports;
+    private maxTraces;
+    constructor(exporters?: TraceExporter[]);
+    attach(eventBus: EventBus): void;
+    detach(eventBus: EventBus): void;
+    getTrace(traceId: string): Trace | undefined;
+    getTraceByRunId(runId: string): Trace | undefined;
+    getAllTraces(): Trace[];
+    clear(): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private startSpan;
+    private endSpan;
+    private finalizeTrace;
+    private runExporters;
+}
+
+declare class StructuredLogger {
+    private drain;
+    private tracer;
+    private listeners;
+    constructor(drain?: LogDrain, tracer?: Tracer);
+    attach(eventBus: EventBus): void;
+    detach(eventBus: EventBus): void;
+    private log;
+}
+
+interface InstrumentResult {
+    tracer: Tracer;
+    metrics: MetricsCollector | null;
+    logger: StructuredLogger | null;
+    detach: () => void;
+}
+/**
+ * Attach observability to an agent in one call.
+ *
+ * ```ts
+ * import { instrument } from "@agentium/observability";
+ *
+ * // Minimal — just pass string shorthands:
+ * const obs = instrument(agent, { exporters: ["langfuse", "console"] });
+ *
+ * // Or bring your own exporter instances for custom config:
+ * const obs = instrument(agent, {
+ *   exporters: [new LangfuseExporter({ baseUrl: "..." }), "console"],
+ * });
+ * ```
+ */
+declare function instrument(agent: Agent, config?: ObservabilityConfig): InstrumentResult;
+/**
+ * Attach observability to a raw EventBus (for teams, workflows, or custom setups).
+ */
+declare function instrumentBus(eventBus: EventBus, config?: ObservabilityConfig): InstrumentResult;
+
+interface AgentMetrics {
+    runs: number;
+    errors: number;
+    avgDurationMs: number;
+    p95DurationMs: number;
+    totalCost: number;
+    totalTokens: number;
+    promptTokens: number;
+    completionTokens: number;
+    reasoningTokens: number;
+    cachedTokens: number;
+    audioInputTokens: number;
+    audioOutputTokens: number;
+    toolCallCount: number;
+    toolUsageFrequency: Record<string, number>;
+    errorRate: number;
+    tokensPerRun: number;
+    /** Estimated total KV cache memory (GB) across all sessions. Requires capacity module. */
+    estimatedKvCacheGb?: number;
+    /** Average context length (tokens) per run. */
+    avgContextLength?: number;
+    /** Session count by category (light/medium/heavy/extreme). */
+    sessionCategories?: Record<string, number>;
+}
+interface MetricEvent {
+    type: string;
+    agentName?: string;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+declare class MetricsExporter {
+    private runs;
+    private toolUsage;
+    private runStartTimes;
+    private runToolCounts;
+    private listeners;
+    private subscribers;
+    private maxRecords;
+    private sessionCategories;
+    private estimatedKvCacheGb?;
+    attach(eventBus: EventBus): void;
+    detach(eventBus: EventBus): void;
+    private addRecord;
+    private emit;
+    getMetrics(agentName?: string): AgentMetrics;
+    toPrometheus(): string;
+    toJSON(): object;
+    stream(): AsyncIterable<MetricEvent>;
+    reset(): void;
+}
+
+export { type AgentMetrics, CallbackExporter, ConsoleExporter, type ExporterShorthand, type InstrumentResult, JsonFileExporter, type JsonFileExporterConfig, LangfuseExporter, type LangfuseExporterConfig, type LogDrain, type LogEntry, type MetricEvent, MetricsCollector, MetricsExporter, type MetricsSnapshot, OTelExporter, type OTelExporterConfig, type ObservabilityConfig, type Span, type SpanEvent, type SpanKind, type SpanStatus, StructuredLogger, type Trace, type TraceExporter, Tracer, instrument, instrumentBus };