# Performance Optimization - Quick Start Guide
Get started with the Komodo MCP performance layer in 5 minutes.
## 1. Installation
The performance layer is built-in. No additional dependencies required.
```bash
# Already included in komodo-mcp
npm install
npm run build
```
## 2. Basic Usage
Replace your existing `KomodoClient` with `EnhancedKomodoClient`:
```typescript
// Before
import { KomodoClient } from './client/KomodoClient.js';
const client = new KomodoClient(config);
// After - just change the import
import { EnhancedKomodoClient } from './client/EnhancedKomodoClient.js';
const client = new EnhancedKomodoClient(config);
// Use exactly the same API
const response = await client.get('/api/resource');
```
That's it! All optimizations are now active.
## 3. Configuration
### Default Settings (Recommended)
```typescript
const client = new EnhancedKomodoClient(config);
// All optimizations enabled with sensible defaults
```
### Custom Settings
```typescript
const client = new EnhancedKomodoClient(config, {
enableConnectionPool: true, // Reuse HTTP connections
enableCache: true, // Cache GET requests (60s TTL)
enableRateLimiting: true, // Rate limit to 100 req/s
enableCircuitBreaker: true, // Fault tolerance
enableAdaptiveTimeouts: true, // Auto-adjust timeouts
enableMetrics: true, // Performance tracking
});
```
## 4. Monitoring
### Quick Health Check
```typescript
// Check if performance is acceptable
if (!client.isPerformanceAcceptable()) {
console.warn('Performance degraded!');
}
```
### Detailed Report
```typescript
// Get comprehensive performance report
console.log(client.getPerformanceReport());
// Output:
// Performance Report
// ==================
// Uptime: 120s
//
// Latency:
// P95: 85.00ms
// Avg: 45.00ms
//
// Cache:
// Hit Rate: 65.00%
//
// Circuit Breaker:
// State: CLOSED
// Health: Healthy
```
### Programmatic Access
```typescript
const metrics = client.getPerformanceMetrics();
console.log(`P95 Latency: ${metrics.system.latency.p95}ms`);
console.log(`Cache Hit Rate: ${metrics.cache.hitRate * 100}%`);
console.log(`Error Rate: ${metrics.system.errors.rate * 100}%`);
console.log(`Circuit State: ${metrics.circuitBreaker.state}`);
```
## 5. Common Scenarios
### High-Traffic Applications
```typescript
const client = new EnhancedKomodoClient(config, {
enableConnectionPool: true, // Essential for high traffic
enableCache: true, // Reduces API calls
enableRateLimiting: true, // Prevents overwhelming API
});
```
### Unreliable Network
```typescript
const client = new EnhancedKomodoClient(config, {
enableCircuitBreaker: true, // Prevent cascade failures
enableAdaptiveTimeouts: true, // Adjust to network conditions
});
```
### Read-Heavy Workload
```typescript
const client = new EnhancedKomodoClient(config, {
enableCache: true, // Cache GET requests
});
// Increase cache size and TTL if needed
// (See docs/PERFORMANCE.md for details)
```
## 6. Troubleshooting
### Slow Requests
```typescript
// Check timeout recommendations
const timeouts = client.getPerformanceMetrics().timeout;
console.log('Timeout recommendations:', timeouts);
// Check circuit breaker state
const cb = client.getPerformanceMetrics().circuitBreaker;
if (cb.state === 'OPEN') {
console.log('Circuit breaker is open - endpoint unavailable');
}
```
### Low Cache Hit Rate
```typescript
const cache = client.getPerformanceMetrics().cache;
console.log(`Cache hit rate: ${cache.hitRate * 100}%`);
// If low, check:
// 1. Are you making repeated GET requests?
// 2. Is the default TTL (60s) too short?
// 3. Is cache size too small?
```
### Rate Limiting Issues
```typescript
const rl = client.getPerformanceMetrics().rateLimiter;
console.log(`Queue length: ${rl.waitingRequests}`);
console.log(`Tokens available: ${rl.currentTokens}`);
// If queue is growing, increase rate limit or optimize requests
```
## 7. Performance Checklist
Before deploying to production:
- [ ] Enable all optimizations
- [ ] Monitor metrics for baseline
- [ ] Check cache hit rate (target: >50%)
- [ ] Verify connection reuse (target: >80%)
- [ ] Test circuit breaker behavior
- [ ] Validate P95 latency (<200ms)
- [ ] Set up alerting for degraded performance
## 8. Next Steps
- **Deep Dive**: Read [PERFORMANCE.md](./PERFORMANCE.md) for detailed documentation
- **Implementation**: See [PERFORMANCE_IMPLEMENTATION.md](./PERFORMANCE_IMPLEMENTATION.md) for technical details
- **Testing**: Review [performance.test.ts](../src/performance/performance.test.ts) for examples
## 9. Quick Reference
### Environment Variables
```bash
KOMODO_TIMEOUT=30000 # Default timeout (ms)
KOMODO_RETRY_COUNT=3 # Max retry attempts
KOMODO_RETRY_DELAY=1000 # Base retry delay (ms)
```
### Performance Targets
| Metric | Target |
|--------|--------|
| Layer Overhead | <100ms |
| Cache Hit Rate | >50% |
| Connection Reuse | >80% |
| P95 Latency | <200ms |
| Error Rate | <1% |
### Component Summary
| Component | Purpose | Default |
|-----------|---------|---------|
| Connection Pool | Socket reuse | 50 sockets |
| Cache | GET response cache | 60s TTL |
| Rate Limiter | Request throttling | 100 req/s |
| Retry Strategy | Exponential backoff | 3 retries |
| Timeout Manager | Adaptive timeouts | Per-operation |
| Circuit Breaker | Fault tolerance | 5 failures |
| Metrics | Performance tracking | Always on |
## 10. Support
- **Documentation**: [docs/PERFORMANCE.md](./PERFORMANCE.md)
- **Examples**: [src/performance/README.md](../src/performance/README.md)
- **Tests**: [src/performance/performance.test.ts](../src/performance/performance.test.ts)
- **Issues**: GitHub Issues
---
**You're all set!** The performance layer is now optimizing your Komodo MCP server.
