@lleverage-ai/agent-sdk 0.0.1

package/dist/observability/metrics.d.ts

@@ -0,0 +1,341 @@
+/**
+ * Metrics Collection System.
+ *
+ * Provides a flexible metrics system for tracking:
+ * - Token usage (input/output tokens)
+ * - Latency (request duration)
+ * - Error rates
+ * - Custom counters, gauges, and histograms
+ *
+ * @packageDocumentation
+ */
+/**
+ * Metric types supported by the system.
+ *
+ * @category Observability
+ */
+export type MetricType = "counter" | "gauge" | "histogram";
+/**
+ * Labels/tags for metrics.
+ *
+ * @category Observability
+ */
+export type MetricLabels = Record<string, string>;
+/**
+ * A single metric data point.
+ *
+ * @category Observability
+ */
+export interface MetricPoint {
+    /** Metric name */
+    name: string;
+    /** Metric type */
+    type: MetricType;
+    /** Metric value */
+    value: number;
+    /** Labels/tags */
+    labels: MetricLabels;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Histogram bucket definition.
+ *
+ * @category Observability
+ */
+export interface HistogramBucket {
+    /** Upper bound */
+    le: number;
+    /** Count of observations <= le */
+    count: number;
+}
+/**
+ * Histogram metric data.
+ *
+ * @category Observability
+ */
+export interface HistogramData {
+    /** Bucket counts */
+    buckets: HistogramBucket[];
+    /** Total sum of all observations */
+    sum: number;
+    /** Total count of observations */
+    count: number;
+}
+/**
+ * A counter metric that can only increase.
+ *
+ * @category Observability
+ */
+export interface Counter {
+    /** Increment the counter */
+    inc(value?: number, labels?: MetricLabels): void;
+    /** Get current value */
+    get(labels?: MetricLabels): number;
+    /** Reset to zero */
+    reset(labels?: MetricLabels): void;
+}
+/**
+ * A gauge metric that can go up and down.
+ *
+ * @category Observability
+ */
+export interface Gauge {
+    /** Set the gauge value */
+    set(value: number, labels?: MetricLabels): void;
+    /** Increment the gauge */
+    inc(value?: number, labels?: MetricLabels): void;
+    /** Decrement the gauge */
+    dec(value?: number, labels?: MetricLabels): void;
+    /** Get current value */
+    get(labels?: MetricLabels): number;
+}
+/**
+ * A histogram metric for measuring distributions.
+ *
+ * @category Observability
+ */
+export interface Histogram {
+    /** Observe a value */
+    observe(value: number, labels?: MetricLabels): void;
+    /** Get histogram data */
+    get(labels?: MetricLabels): HistogramData;
+    /** Start a timer that observes duration when stopped */
+    startTimer(labels?: MetricLabels): () => number;
+    /** Reset the histogram */
+    reset(labels?: MetricLabels): void;
+}
+/**
+ * A metrics exporter sends metrics to an external system.
+ *
+ * @category Observability
+ */
+export interface MetricsExporter {
+    /** Exporter name */
+    name: string;
+    /** Export metrics */
+    export(metrics: MetricPoint[]): void | Promise<void>;
+    /** Optional flush for batch exporters */
+    flush?(): void | Promise<void>;
+    /** Optional close for cleanup */
+    close?(): void | Promise<void>;
+}
+/**
+ * Options for creating a metrics registry.
+ *
+ * @category Observability
+ */
+export interface MetricsRegistryOptions {
+    /** Default labels for all metrics */
+    defaultLabels?: MetricLabels;
+    /** Exporters to send metrics to */
+    exporters?: MetricsExporter[];
+    /** Export interval in milliseconds (0 = manual only) */
+    exportInterval?: number;
+    /** Prefix for all metric names */
+    prefix?: string;
+}
+/**
+ * A registry for managing metrics.
+ *
+ * @category Observability
+ */
+export interface MetricsRegistry {
+    /** Create or get a counter */
+    counter(name: string, description?: string): Counter;
+    /** Create or get a gauge */
+    gauge(name: string, description?: string): Gauge;
+    /** Create or get a histogram */
+    histogram(name: string, buckets?: number[], description?: string): Histogram;
+    /** Get all current metric values */
+    getMetrics(): MetricPoint[];
+    /** Export metrics to all exporters */
+    export(): Promise<void>;
+    /** Close the registry and exporters */
+    close(): Promise<void>;
+}
+/**
+ * Default histogram buckets (latency in ms).
+ */
+export declare const DEFAULT_LATENCY_BUCKETS: number[];
+/**
+ * Default histogram buckets for token counts.
+ */
+export declare const DEFAULT_TOKEN_BUCKETS: number[];
+/**
+ * Creates a metrics registry.
+ *
+ * @param options - Registry options
+ * @returns A metrics registry
+ *
+ * @example
+ * ```typescript
+ * const registry = createMetricsRegistry({
+ *   defaultLabels: { service: "my-agent" },
+ * });
+ *
+ * const requestCounter = registry.counter("requests_total");
+ * const latencyHistogram = registry.histogram("request_duration_ms");
+ *
+ * requestCounter.inc();
+ * latencyHistogram.observe(150);
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createMetricsRegistry(options?: MetricsRegistryOptions): MetricsRegistry;
+/**
+ * Creates a console exporter for debugging.
+ *
+ * @returns A console exporter
+ *
+ * @example
+ * ```typescript
+ * const registry = createMetricsRegistry({
+ *   exporters: [createConsoleMetricsExporter()],
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createConsoleMetricsExporter(): MetricsExporter;
+/**
+ * Creates a memory exporter that stores metrics.
+ *
+ * @returns A memory exporter with access to stored metrics
+ *
+ * @example
+ * ```typescript
+ * const exporter = createMemoryMetricsExporter();
+ * const registry = createMetricsRegistry({ exporters: [exporter] });
+ *
+ * registry.counter("test").inc();
+ * await registry.export();
+ *
+ * console.log(exporter.metrics);
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createMemoryMetricsExporter(): MetricsExporter & {
+    metrics: MetricPoint[];
+    clear(): void;
+};
+/**
+ * Creates a callback exporter that invokes a function for each export.
+ *
+ * @param callback - Function to call with metrics
+ * @returns A callback exporter
+ *
+ * @example
+ * ```typescript
+ * const exporter = createCallbackMetricsExporter((metrics) => {
+ *   sendToPrometheus(metrics);
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createCallbackMetricsExporter(callback: (metrics: MetricPoint[]) => void | Promise<void>): MetricsExporter;
+/**
+ * Pre-defined metrics for agent SDK.
+ *
+ * @category Observability
+ */
+export interface AgentMetrics {
+    /** Total requests made */
+    requestsTotal: Counter;
+    /** Requests in progress */
+    requestsInProgress: Gauge;
+    /** Request duration in milliseconds */
+    requestDurationMs: Histogram;
+    /** Input tokens used */
+    inputTokensTotal: Counter;
+    /** Output tokens used */
+    outputTokensTotal: Counter;
+    /** Total tokens used */
+    tokensTotal: Counter;
+    /** Tool calls made */
+    toolCallsTotal: Counter;
+    /** Tool call errors */
+    toolErrorsTotal: Counter;
+    /** Subagent spawns */
+    subagentSpawnsTotal: Counter;
+    /** Errors by type */
+    errorsTotal: Counter;
+    /** Context compactions */
+    compactionsTotal: Counter;
+    /** Checkpoint operations */
+    checkpointsTotal: Counter;
+}
+/**
+ * Creates pre-defined agent metrics.
+ *
+ * @param registry - The metrics registry to use
+ * @returns Agent metrics object
+ *
+ * @example
+ * ```typescript
+ * const registry = createMetricsRegistry();
+ * const metrics = createAgentMetrics(registry);
+ *
+ * // Use in agent hooks
+ * hooks.on("PostGenerate", (ctx) => {
+ *   metrics.requestsTotal.inc({ model: "claude-3" });
+ *   if (ctx.data.type === "PostGenerate" && ctx.data.result.usage) {
+ *     metrics.inputTokensTotal.inc(ctx.data.result.usage.inputTokens);
+ *     metrics.outputTokensTotal.inc(ctx.data.result.usage.outputTokens);
+ *   }
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createAgentMetrics(registry: MetricsRegistry): AgentMetrics;
+import type { HookCallback } from "../types.js";
+/**
+ * Creates hooks that automatically update agent metrics.
+ *
+ * @param metrics - The agent metrics to update
+ * @returns Hook callbacks for metrics collection
+ *
+ * @example
+ * ```typescript
+ * const registry = createMetricsRegistry();
+ * const metrics = createAgentMetrics(registry);
+ * const metricsHooks = createMetricsHooks(metrics);
+ *
+ * const agent = createAgent({
+ *   model,
+ *   hooks: {
+ *     PostGenerate: [metricsHooks.PostGenerate],
+ *     PostToolUse: [metricsHooks.PostToolUse],
+ *     PostToolUseFailure: [metricsHooks.PostToolUseFailure],
+ *     PostCompact: [metricsHooks.PostCompact],
+ *   },
+ * });
+ * ```
+ *
+ * @category Observability
+ */
+export declare function createMetricsHooks(metrics: AgentMetrics): {
+    PostGenerate: HookCallback;
+    PostToolUse: HookCallback;
+    PostToolUseFailure: HookCallback;
+    PostCompact: HookCallback;
+};
+/**
+ * The default global metrics registry.
+ *
+ * @category Observability
+ */
+export declare let defaultMetricsRegistry: MetricsRegistry;
+/**
+ * Sets the default global metrics registry.
+ *
+ * @param registry - The registry to use as default
+ *
+ * @category Observability
+ */
+export declare function setDefaultMetricsRegistry(registry: MetricsRegistry): void;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/observability/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"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"}