@onlineapps/service-wrapper 2.0.0

package/docs/PERFORMANCE.md

@@ -0,0 +1,453 @@
+# Service Wrapper - Performance & Optimization
+
+## Performance Metrics
+
+### Latency Breakdown (typical)
+```
+Operation                Time        Notes
+---------                ----        -----
+Queue receive            1-2ms       AMQP overhead
+Header parsing           0.5ms       Extract context
+Message deserialize      1-3ms       JSON.parse
+Cache check              2-3ms       Redis GET
+API call                 5-50ms      HTTP to service (varies)
+Cache store              1-2ms       Redis SET
+Result serialize         1-2ms       JSON.stringify
+Queue publish            2-3ms       AMQP publish
+-------------------------------------------------
+Total overhead:          ~15-20ms + service time
+```
+
+### Throughput Capabilities
+```
+Single instance:         100-200 msg/sec
+With caching (50% hits): 150-300 msg/sec
+Parallel (10 prefetch):  500-1000 msg/sec
+Multi-instance (5x):     2500-5000 msg/sec
+```
+
+## Optimization Strategies
+
+### 1. Cache-First Strategy
+```javascript
+class CacheOptimizer {
+  constructor(cache, config) {
+    this.cache = cache;
+    this.config = config;
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      errors: 0
+    };
+  }
+
+  async getWithCache(key, fetchFn) {
+    // Try cache first
+    try {
+      const cached = await this.cache.get(key);
+      if (cached) {
+        this.stats.hits++;
+        return cached;
+      }
+    } catch (error) {
+      this.stats.errors++;
+      // Continue without cache if error
+    }
+
+    // Cache miss - fetch from source
+    this.stats.misses++;
+    const result = await fetchFn();
+
+    // Store in cache (async, don't wait)
+    this.cache.set(key, result, { ttl: this.config.ttl })
+      .catch(err => console.error('Cache store failed:', err));
+
+    return result;
+  }
+
+  getHitRate() {
+    const total = this.stats.hits + this.stats.misses;
+    return total > 0 ? this.stats.hits / total : 0;
+  }
+}
+```
+
+### 2. Connection Pooling
+```javascript
+class ConnectionPool {
+  constructor(serviceUrl, maxSockets = 10) {
+    this.agent = new http.Agent({
+      keepAlive: true,
+      maxSockets: maxSockets,
+      maxFreeSockets: 5,
+      timeout: 60000,
+      keepAliveMsecs: 30000
+    });
+
+    this.client = axios.create({
+      baseURL: serviceUrl,
+      httpAgent: this.agent,
+      timeout: 5000,
+      maxRedirects: 0
+    });
+  }
+
+  async request(config) {
+    return this.client.request(config);
+  }
+
+  getStats() {
+    return {
+      activeSockets: Object.keys(this.agent.sockets).length,
+      freeSockets: Object.keys(this.agent.freeSockets).length,
+      requests: this.agent.requests.length
+    };
+  }
+}
+```
+
+### 3. Batch Processing
+```javascript
+class BatchProcessor {
+  constructor(processFunc, options = {}) {
+    this.processFunc = processFunc;
+    this.batchSize = options.batchSize || 10;
+    this.batchTimeout = options.batchTimeout || 100;
+    this.batch = [];
+    this.timer = null;
+  }
+
+  async add(item) {
+    return new Promise((resolve, reject) => {
+      this.batch.push({ item, resolve, reject });
+
+      if (this.batch.length >= this.batchSize) {
+        this.flush();
+      } else if (!this.timer) {
+        this.timer = setTimeout(() => this.flush(), this.batchTimeout);
+      }
+    });
+  }
+
+  async flush() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+
+    if (this.batch.length === 0) return;
+
+    const currentBatch = this.batch;
+    this.batch = [];
+
+    try {
+      // Process batch in parallel
+      const items = currentBatch.map(b => b.item);
+      const results = await this.processFunc(items);
+
+      // Resolve individual promises
+      currentBatch.forEach((b, i) => {
+        b.resolve(results[i]);
+      });
+    } catch (error) {
+      currentBatch.forEach(b => b.reject(error));
+    }
+  }
+}
+```
+
+### 4. Adaptive Prefetch
+```javascript
+class AdaptivePrefetch {
+  constructor(channel, options = {}) {
+    this.channel = channel;
+    this.minPrefetch = options.minPrefetch || 1;
+    this.maxPrefetch = options.maxPrefetch || 20;
+    this.currentPrefetch = options.initialPrefetch || 10;
+    this.metrics = {
+      processed: 0,
+      errors: 0,
+      avgProcessTime: 0
+    };
+  }
+
+  async adjustPrefetch() {
+    const errorRate = this.metrics.errors / this.metrics.processed;
+    const memoryUsage = process.memoryUsage().heapUsed / 1024 / 1024; // MB
+
+    let newPrefetch = this.currentPrefetch;
+
+    // Reduce if high error rate or memory pressure
+    if (errorRate > 0.1 || memoryUsage > 200) {
+      newPrefetch = Math.max(this.minPrefetch,
+        Math.floor(this.currentPrefetch * 0.8));
+    }
+    // Increase if performing well
+    else if (errorRate < 0.01 && memoryUsage < 100) {
+      newPrefetch = Math.min(this.maxPrefetch,
+        Math.floor(this.currentPrefetch * 1.2));
+    }
+
+    if (newPrefetch !== this.currentPrefetch) {
+      await this.channel.prefetch(newPrefetch);
+      this.currentPrefetch = newPrefetch;
+
+      console.log(`Prefetch adjusted: ${this.currentPrefetch} -> ${newPrefetch}`);
+    }
+  }
+
+  recordMetric(success, processTime) {
+    this.metrics.processed++;
+    if (!success) this.metrics.errors++;
+
+    // Calculate running average
+    this.metrics.avgProcessTime =
+      (this.metrics.avgProcessTime * (this.metrics.processed - 1) + processTime) /
+      this.metrics.processed;
+
+    // Adjust every 100 messages
+    if (this.metrics.processed % 100 === 0) {
+      this.adjustPrefetch();
+    }
+  }
+}
+```
+
+## Memory Management
+
+### Memory Monitoring
+```javascript
+class MemoryMonitor {
+  constructor(threshold = 200) { // MB
+    this.threshold = threshold;
+    this.baseline = process.memoryUsage().heapUsed;
+    this.checks = [];
+  }
+
+  check() {
+    const current = process.memoryUsage();
+    const usedMB = current.heapUsed / 1024 / 1024;
+
+    this.checks.push({
+      timestamp: Date.now(),
+      heapUsed: usedMB,
+      heapTotal: current.heapTotal / 1024 / 1024,
+      external: current.external / 1024 / 1024,
+      rss: current.rss / 1024 / 1024
+    });
+
+    // Keep only last 100 checks
+    if (this.checks.length > 100) {
+      this.checks.shift();
+    }
+
+    // Check for memory leak (continuous growth)
+    if (this.checks.length >= 10) {
+      const recent = this.checks.slice(-10);
+      const growth = recent[9].heapUsed - recent[0].heapUsed;
+
+      if (growth > 50) { // 50MB growth in 10 checks
+        console.warn('Possible memory leak detected:', {
+          growth: `${growth.toFixed(2)}MB`,
+          current: `${usedMB.toFixed(2)}MB`
+        });
+      }
+    }
+
+    // Force GC if over threshold (if --expose-gc flag)
+    if (usedMB > this.threshold && global.gc) {
+      console.log(`Memory threshold exceeded (${usedMB.toFixed(2)}MB), forcing GC`);
+      global.gc();
+    }
+
+    return usedMB;
+  }
+
+  getStats() {
+    if (this.checks.length === 0) return null;
+
+    const heapValues = this.checks.map(c => c.heapUsed);
+    return {
+      current: heapValues[heapValues.length - 1],
+      min: Math.min(...heapValues),
+      max: Math.max(...heapValues),
+      avg: heapValues.reduce((a, b) => a + b, 0) / heapValues.length,
+      trend: this.calculateTrend()
+    };
+  }
+
+  calculateTrend() {
+    if (this.checks.length < 2) return 'stable';
+
+    const recent = this.checks.slice(-10);
+    const firstHalf = recent.slice(0, 5).map(c => c.heapUsed);
+    const secondHalf = recent.slice(5).map(c => c.heapUsed);
+
+    const avgFirst = firstHalf.reduce((a, b) => a + b, 0) / firstHalf.length;
+    const avgSecond = secondHalf.reduce((a, b) => a + b, 0) / secondHalf.length;
+
+    const diff = avgSecond - avgFirst;
+    if (diff > 10) return 'increasing';
+    if (diff < -10) return 'decreasing';
+    return 'stable';
+  }
+}
+```
+
+## Event Loop Monitoring
+```javascript
+class EventLoopMonitor {
+  constructor() {
+    this.lagThreshold = 10; // ms
+    this.checkInterval = 1000; // ms
+    this.lastCheck = Date.now();
+    this.lags = [];
+  }
+
+  start() {
+    this.interval = setInterval(() => {
+      const now = Date.now();
+      const expectedTime = this.lastCheck + this.checkInterval;
+      const lag = now - expectedTime;
+
+      if (lag > this.lagThreshold) {
+        console.warn(`Event loop lag detected: ${lag}ms`);
+      }
+
+      this.lags.push(lag);
+      if (this.lags.length > 60) {
+        this.lags.shift(); // Keep last 60 measurements
+      }
+
+      this.lastCheck = now;
+    }, this.checkInterval);
+  }
+
+  stop() {
+    if (this.interval) {
+      clearInterval(this.interval);
+    }
+  }
+
+  getStats() {
+    if (this.lags.length === 0) return null;
+
+    return {
+      current: this.lags[this.lags.length - 1],
+      avg: this.lags.reduce((a, b) => a + b, 0) / this.lags.length,
+      max: Math.max(...this.lags),
+      warnings: this.lags.filter(l => l > this.lagThreshold).length
+    };
+  }
+}
+```
+
+## Performance Testing
+
+### Load Test Configuration
+```javascript
+// load-test.js
+const LoadTester = {
+  async runTest(config) {
+    const results = {
+      totalMessages: config.messages,
+      duration: 0,
+      throughput: 0,
+      latencies: [],
+      errors: 0
+    };
+
+    const startTime = Date.now();
+
+    // Generate test messages
+    const promises = [];
+    for (let i = 0; i < config.messages; i++) {
+      const message = this.generateTestMessage(i);
+      const promise = this.sendAndMeasure(message);
+      promises.push(promise);
+
+      // Control send rate
+      if (config.rateLimit && i % config.rateLimit === 0) {
+        await new Promise(resolve => setTimeout(resolve, 1000));
+      }
+    }
+
+    // Wait for all to complete
+    const measurements = await Promise.all(promises);
+
+    results.duration = Date.now() - startTime;
+    results.throughput = (config.messages / results.duration) * 1000;
+    results.latencies = measurements.filter(m => m.success).map(m => m.latency);
+    results.errors = measurements.filter(m => !m.success).length;
+
+    // Calculate percentiles
+    results.latencies.sort((a, b) => a - b);
+    results.p50 = results.latencies[Math.floor(results.latencies.length * 0.50)];
+    results.p95 = results.latencies[Math.floor(results.latencies.length * 0.95)];
+    results.p99 = results.latencies[Math.floor(results.latencies.length * 0.99)];
+
+    return results;
+  },
+
+  generateTestMessage(index) {
+    return {
+      workflowId: `test-workflow-${index}`,
+      cookbook: {
+        steps: [
+          {
+            service: 'hello-service',
+            operation: 'sayGoodDay',
+            params: { name: `User${index}` }
+          }
+        ]
+      }
+    };
+  },
+
+  async sendAndMeasure(message) {
+    const start = Date.now();
+    try {
+      await mqClient.publish('workflow.init', message);
+      // Wait for completion (simplified)
+      await waitForCompletion(message.workflowId);
+      return {
+        success: true,
+        latency: Date.now() - start
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message
+      };
+    }
+  }
+};
+```
+
+## Optimization Checklist
+
+### Quick Wins
+- [ ] Enable connection keep-alive
+- [ ] Implement basic caching
+- [ ] Set appropriate prefetch (10-20)
+- [ ] Use connection pooling
+
+### Advanced Optimizations
+- [ ] Implement batch processing
+- [ ] Add adaptive prefetch
+- [ ] Enable memory monitoring
+- [ ] Add event loop monitoring
+- [ ] Implement circuit breaker for services
+- [ ] Add request deduplication
+- [ ] Enable compression for large messages
+
+### Monitoring Setup
+- [ ] Track cache hit rate
+- [ ] Monitor message processing time
+- [ ] Watch memory usage trend
+- [ ] Track event loop lag
+- [ ] Monitor connection pool usage
+- [ ] Set up alerts for anomalies
+
+---
+*For implementation details, see [Process Flows](./PROCESS_FLOWS.md)*