This document covers caching strategies, circuit breaker patterns, performance monitoring, and optimization techniques in the VTEX Rewriter application.
📋 Table of Contents
- Cache Architecture
- Auto-Cache System
- Circuit Breaker Pattern
- Performance Monitoring
- Metrics Collection
🗄️ Cache Architecture
� Auto-Cache System
The Auto-Cache system automatically populates VBase with compatibility routes, transforming a 20% cache hit rate into 95%+ over time without depending on external indexers.
Auto-Cache Flow
Auto-Cache Implementation
_67// Background save function - non-blocking_67const saveCompatibilityRouteInBackground = (_67 compatibility: Internal,_67 internals: any,_67 redirects: any_67) => {_67 const tomorrow = new Date()_67 tomorrow.setDate(tomorrow.getDate() + 1)_67 const routeWithExpiry = {_67 ...compatibility,_67 endDate: tomorrow.toISOString(), // 24h TTL_67 }_67 _67 // Fire-and-forget save (doesn't block response)_67 internals.save(routeWithExpiry, redirects)_67}_67_67// Performance tracking with auto-cache metrics_67const internalLoad = async (ctx: Context, url: UrlWithParsedQuery, workspace: string) => {_67 const vbaseStart = Date.now()_67 const internal = await internals.get(locator)_67 const vbaseElapsed = Date.now() - vbaseStart_67_67 if (internal) {_67 // Cache hit - served from VBase (~17ms)_67 metrics.batch('route-performance-tracking', undefined, {_67 route_path: locator.from,_67 access_type: 'cache_hit',_67 latency_ms: vbaseElapsed,_67 vbase_ms: vbaseElapsed,_67 compatibility_ms: 0,_67 will_be_cached: 0,_67 total: 1,_67 })_67 return { hit: true, internal }_67 }_67_67 // Cache miss - query compatibility layer_67 const compatStart = Date.now()_67 const compatibility = await maybeLoadCompatibilityRoute(locator, ctx)_67 const compatElapsed = Date.now() - compatStart_67_67 if (compatibility) {_67 const totalLatency = vbaseElapsed + compatElapsed_67_67 // Log performance metrics_67 metrics.batch('route-performance-tracking', undefined, {_67 route_path: locator.from,_67 access_type: 'cache_miss_first_time',_67 latency_ms: totalLatency,_67 vbase_ms: vbaseElapsed,_67 compatibility_ms: compatElapsed,_67 will_be_cached: 1,_67 total: 1,_67 })_67_67 // Auto-cache for production workspace only_67 const shouldSaveCompatibilityRoute = _67 workspace === 'master' && compatibility.type !== 'notFoundProduct'_67_67 if (shouldSaveCompatibilityRoute) {_67 saveCompatibilityRouteInBackground(compatibility, internals, redirects)_67 }_67 }_67_67 return { hit: false, internal: compatibility }_67}
Performance Improvement Metrics
Before Auto-Cache:
- Cache Hit Rate: ~20%
- Average Latency: ~200ms (80% slow requests)
- VBase: ~17ms vs Catalog API: ~89ms
After Auto-Cache (Production Results):
- Cache Hit Rate: 20% → 95%+ over time
- Cache Hit Latency: ~18ms (⚡ 5.8x faster)
- Cache Miss → Hit Evolution:
- First visit: 112ms (13ms VBase + 99ms Catalog)
- Second visit: 21ms (100% VBase)
- Improvement: 81-98% latency reduction
ROI Analysis
| Route | First Visit | Subsequent Visits | Improvement |
|---|---|---|---|
/produto/smartphone/p | 617ms | 10ms | 98.4% ⬇️ |
/categoria/electronics | 112ms | 21ms | 81.3% ⬇️ |
/apparel-accessories | 119ms | 21ms | 82.4% ⬇️ |
Key Benefits:
- 🚀 Self-Improving Performance: Each cache miss becomes a future cache hit
- 🔄 Zero Maintenance: No manual cache population required
- 📈 Progressive Enhancement: Site gets faster with usage
- 🎯 Production Focus: Only active in master workspace
�🔄 Circuit Breaker Pattern
_38class CircuitBreaker {_38 private failures = 0_38 private lastFailureTime = 0_38 private state: 'CLOSED' | 'OPEN' | 'HALF_OPEN' = 'CLOSED'_38 _38 async execute<T>(operation: () => Promise<T>): Promise<T> {_38 if (this.state === 'OPEN') {_38 if (Date.now() - this.lastFailureTime > this.timeout) {_38 this.state = 'HALF_OPEN'_38 } else {_38 throw new Error('Circuit breaker is OPEN')_38 }_38 }_38 _38 try {_38 const result = await operation()_38 this.onSuccess()_38 return result_38 } catch (error) {_38 this.onFailure()_38 throw error_38 }_38 }_38 _38 private onSuccess(): void {_38 this.failures = 0_38 this.state = 'CLOSED'_38 }_38 _38 private onFailure(): void {_38 this.failures++_38 this.lastFailureTime = Date.now()_38 _38 if (this.failures >= this.threshold) {_38 this.state = 'OPEN'_38 }_38 }_38}
Circuit Breaker State Diagram
📊 Performance Monitoring
Performance Monitoring Flow
📊 Metrics Collection
Metrics Collection
_14// Track cache performance_14metrics.trackCache('vbase', vbaseCacheStorage)_14metrics.trackCache('catalog', catalogCacheStorage)_14_14// Track internal routes usage_14const internalStats = { _14 hit: hit ? 1 : 0, _14 miss: hit ? 0 : 1, _14 total: 1 _14}_14metrics.batch('internals-stats', undefined, internalStats)_14_14// Track authorization_14metrics.trackAuth('admin-access', { user: ctx.vtex.user?.id })
Health Checks
_22async function healthCheck(ctx: Context): Promise<void> {_22 const checks = await Promise.allSettled([_22 // VBase connectivity_22 ctx.clients.vbase.getJSON('health', 'check.json'),_22 _22 // Catalog API_22 ctx.clients.catalog.getSkuById('1'),_22 _22 // Proxy connectivity _22 ctx.clients.proxy.get('/health')_22 ])_22 _22 const failures = checks.filter(r => r.status === 'rejected')_22 _22 if (failures.length > 0) {_22 ctx.status = 503_22 ctx.body = { status: 'unhealthy', failures }_22 } else {_22 ctx.status = 200_22 ctx.body = { status: 'healthy' }_22 }_22}