agentic-qe 1.8.4 → 1.9.1

package/dist/telemetry/instrumentation/memory.d.ts

@@ -0,0 +1,313 @@
+/**
+ * Memory Instrumentation - OpenTelemetry spans for memory operations
+ *
+ * Provides comprehensive tracing for memory store/retrieve/search/delete operations
+ * with semantic attributes following OpenTelemetry conventions. Automatically instruments
+ * all memory operations with context propagation and performance tracking.
+ *
+ * @module telemetry/instrumentation/memory
+ */
+import { Span, Context } from '@opentelemetry/api';
+import { AgentId } from '../../types';
+/**
+ * Memory store span configuration
+ */
+export interface MemoryStoreConfig {
+    /** Agent performing the memory operation */
+    agentId: AgentId;
+    /** Memory namespace */
+    namespace: string;
+    /** Memory key */
+    key: string;
+    /** Value size in bytes */
+    valueSize: number;
+    /** Time-to-live in seconds (optional) */
+    ttl?: number;
+    /** Parent span context */
+    parentContext?: Context;
+}
+/**
+ * Memory retrieve span configuration
+ */
+export interface MemoryRetrieveConfig {
+    /** Agent performing the memory operation */
+    agentId: AgentId;
+    /** Memory namespace */
+    namespace: string;
+    /** Memory key */
+    key: string;
+    /** Parent span context */
+    parentContext?: Context;
+}
+/**
+ * Memory search span configuration
+ */
+export interface MemorySearchConfig {
+    /** Agent performing the memory operation */
+    agentId: AgentId;
+    /** Memory namespace */
+    namespace: string;
+    /** Search pattern (glob or regex) */
+    pattern: string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Parent span context */
+    parentContext?: Context;
+}
+/**
+ * Memory delete span configuration
+ */
+export interface MemoryDeleteConfig {
+    /** Agent performing the memory operation */
+    agentId: AgentId;
+    /** Memory namespace */
+    namespace: string;
+    /** Memory key */
+    key: string;
+    /** Parent span context */
+    parentContext?: Context;
+}
+/**
+ * Memory store operation result
+ */
+export interface MemoryStoreResult {
+    /** Whether the store operation was successful */
+    success: boolean;
+    /** Operation duration in milliseconds */
+    durationMs?: number;
+    /** Error if operation failed */
+    error?: Error;
+}
+/**
+ * Memory retrieve operation result
+ */
+export interface MemoryRetrieveResult {
+    /** Whether the key was found */
+    found: boolean;
+    /** Value size in bytes (if found) */
+    valueSize?: number;
+    /** Operation duration in milliseconds */
+    durationMs?: number;
+    /** Error if operation failed */
+    error?: Error;
+}
+/**
+ * Memory search operation result
+ */
+export interface MemorySearchResult {
+    /** Number of results found */
+    resultCount: number;
+    /** Operation duration in milliseconds */
+    durationMs?: number;
+    /** Error if operation failed */
+    error?: Error;
+}
+/**
+ * Memory delete operation result
+ */
+export interface MemoryDeleteResult {
+    /** Whether the delete operation was successful */
+    success: boolean;
+    /** Operation duration in milliseconds */
+    durationMs?: number;
+    /** Error if operation failed */
+    error?: Error;
+}
+/**
+ * Memory operation span manager
+ *
+ * Manages OpenTelemetry spans for memory operations with automatic
+ * context propagation and semantic attribute attachment following
+ * OTEL conventions for distributed tracing.
+ */
+export declare class MemorySpanManager {
+    private readonly tracer;
+    private activeSpans;
+    /**
+     * Start memory store span
+     *
+     * Records memory store operation with semantic attributes for namespace,
+     * key, value size, and optional TTL.
+     *
+     * @param config - Memory store configuration
+     * @returns Active span with context
+     */
+    startStoreSpan(config: MemoryStoreConfig): {
+        span: Span;
+        context: Context;
+    };
+    /**
+     * Complete memory store span
+     *
+     * @param span - Active span from startStoreSpan
+     * @param result - Store operation result
+     */
+    completeStoreSpan(span: Span, result: MemoryStoreResult): void;
+    /**
+     * Start memory retrieve span
+     *
+     * Records memory retrieve operation with semantic attributes for namespace
+     * and key lookup.
+     *
+     * @param config - Memory retrieve configuration
+     * @returns Active span with context
+     */
+    startRetrieveSpan(config: MemoryRetrieveConfig): {
+        span: Span;
+        context: Context;
+    };
+    /**
+     * Complete memory retrieve span
+     *
+     * @param span - Active span from startRetrieveSpan
+     * @param result - Retrieve operation result
+     */
+    completeRetrieveSpan(span: Span, result: MemoryRetrieveResult): void;
+    /**
+     * Start memory search span
+     *
+     * Records memory search operation with semantic attributes for namespace,
+     * search pattern, and result limits.
+     *
+     * @param config - Memory search configuration
+     * @returns Active span with context
+     */
+    startSearchSpan(config: MemorySearchConfig): {
+        span: Span;
+        context: Context;
+    };
+    /**
+     * Complete memory search span
+     *
+     * @param span - Active span from startSearchSpan
+     * @param result - Search operation result
+     */
+    completeSearchSpan(span: Span, result: MemorySearchResult): void;
+    /**
+     * Start memory delete span
+     *
+     * Records memory delete operation with semantic attributes for namespace
+     * and key deletion.
+     *
+     * @param config - Memory delete configuration
+     * @returns Active span with context
+     */
+    startDeleteSpan(config: MemoryDeleteConfig): {
+        span: Span;
+        context: Context;
+    };
+    /**
+     * Complete memory delete span
+     *
+     * @param span - Active span from startDeleteSpan
+     * @param result - Delete operation result
+     */
+    completeDeleteSpan(span: Span, result: MemoryDeleteResult): void;
+    /**
+     * Record memory operation error
+     *
+     * Records an error event on the currently active span.
+     *
+     * @param operation - Operation type (store, retrieve, search, delete)
+     * @param namespace - Memory namespace
+     * @param key - Memory key (if applicable)
+     * @param error - Error that occurred
+     */
+    recordError(operation: 'store' | 'retrieve' | 'search' | 'delete', namespace: string, key: string | undefined, error: Error): void;
+    /**
+     * Cleanup all active spans (for graceful shutdown)
+     *
+     * Ensures all memory operation spans are properly ended during
+     * application shutdown or cleanup.
+     */
+    cleanup(): void;
+}
+/**
+ * Global memory span manager instance
+ */
+export declare const memorySpanManager: MemorySpanManager;
+/**
+ * Execute function within memory store span context
+ *
+ * Convenience wrapper that automatically creates, tracks, and completes
+ * a memory store span around the provided function.
+ *
+ * @param config - Memory store configuration
+ * @param fn - Function to execute (receives span context)
+ * @returns Function result
+ *
+ * @example
+ * const result = await withMemoryStore(
+ *   { agentId, namespace: 'aqe', key: 'test-plan', valueSize: 1024 },
+ *   async (ctx) => {
+ *     return await memoryService.store('test-plan', data);
+ *   }
+ * );
+ */
+export declare function withMemoryStore<T>(config: MemoryStoreConfig, fn: (context: Context) => Promise<T>): Promise<T>;
+/**
+ * Execute function within memory retrieve span context
+ *
+ * Convenience wrapper that automatically creates, tracks, and completes
+ * a memory retrieve span around the provided function.
+ *
+ * @param config - Memory retrieve configuration
+ * @param fn - Function to execute (receives span context)
+ * @returns Function result with found flag
+ *
+ * @example
+ * const { found, value } = await withMemoryRetrieve(
+ *   { agentId, namespace: 'aqe', key: 'test-plan' },
+ *   async (ctx) => {
+ *     return await memoryService.retrieve('test-plan');
+ *   }
+ * );
+ */
+export declare function withMemoryRetrieve<T>(config: MemoryRetrieveConfig, fn: (context: Context) => Promise<{
+    found: boolean;
+    value?: T;
+    valueSize?: number;
+}>): Promise<{
+    found: boolean;
+    value?: T;
+    valueSize?: number;
+}>;
+/**
+ * Execute function within memory search span context
+ *
+ * Convenience wrapper that automatically creates, tracks, and completes
+ * a memory search span around the provided function.
+ *
+ * @param config - Memory search configuration
+ * @param fn - Function to execute (receives span context)
+ * @returns Function result with result count
+ *
+ * @example
+ * const results = await withMemorySearch(
+ *   { agentId, namespace: 'aqe', pattern: 'test-*', limit: 10 },
+ *   async (ctx) => {
+ *     return await memoryService.search('test-*');
+ *   }
+ * );
+ */
+export declare function withMemorySearch<T>(config: MemorySearchConfig, fn: (context: Context) => Promise<T[]>): Promise<T[]>;
+/**
+ * Execute function within memory delete span context
+ *
+ * Convenience wrapper that automatically creates, tracks, and completes
+ * a memory delete span around the provided function.
+ *
+ * @param config - Memory delete configuration
+ * @param fn - Function to execute (receives span context)
+ * @returns Function result
+ *
+ * @example
+ * await withMemoryDelete(
+ *   { agentId, namespace: 'aqe', key: 'test-plan' },
+ *   async (ctx) => {
+ *     await memoryService.delete('test-plan');
+ *   }
+ * );
+ */
+export declare function withMemoryDelete<T>(config: MemoryDeleteConfig, fn: (context: Context) => Promise<T>): Promise<T>;
+//# sourceMappingURL=memory.d.ts.map

package/dist/telemetry/instrumentation/memory.d.ts.map

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