📊 Performance Logging System

Overview

Clean console logging system that can be toggled on/off to reduce console noise in production while preserving critical performance insights during development and debugging.

Quick Toggle

Use window.togglePerfLogs() in browser console to instantly enable/disable performance logs during development!

---

🚀 Quick Start Guide

Development Modes

🔇 Clean Development (Default)

# Normal development - performance logs OFF for clean console
pnpm dev

Best for: Daily development, focusing on functionality

📊 Performance Debugging

# When you need performance insights - logs ON
pnpm devPerformance

Best for: Performance analysis, optimization work

⚡ TTFVT Optimization Mode

# Maximum speed mode for Time To First Visible Token optimization
pnpm devTTFVT

# Or for local development (no SST binding)
pnpm local:frontend:ttfvt

Best for: TTFVT optimization, speed testing

---

🎯 TTFVT Mode Features

Performance Breakthrough

TTFVT Mode provides 60-75% additional speed improvement on top of existing optimizations!

Key Optimizations

Feature	Benefit	Impact
Queue Bypass	Direct API processing	Eliminates SQS latency
Aggressive Feature Disabling	QuestMaster, Mementos, Agents OFF	Reduces processing overhead
Minimal History	3 messages vs 50+	Faster context loading
No Server Throttling	Client-optimized streaming	Smoother real-time updates
10x Rate Limit	100 req/min vs 10 req/min	Rapid testing capability
Parallel Operations	Simultaneous data fetching	Eliminates sequential bottlenecks

Performance Impact

graph LR
    A[Original: 12s] --> B[Just-in-Time API: 1.7s]
    B --> C[TTFVT Mode: 400-800ms]
    
    A -.->|85% improvement| B
    B -.->|60-75% additional| C
    A -.->|95% total improvement| C

---

🛡️ Configuration Options

Method 1: Script-Based Control (Recommended)

# Development modes
pnpm dev                    # 🔇 Clean console, normal speed
pnpm devPerformance         # 📊 Performance logs, normal speed  
pnpm devTTFVT               # 📊 Performance logs, MAXIMUM speed

# Local development (no SST binding)
pnpm local:frontend         # Clean console, normal speed
pnpm local:frontend:perf    # Performance logs, normal speed
pnpm local:frontend:ttfvt   # Performance logs, MAXIMUM speed

Recommendation

Use script-based control for the cleanest development experience. No environment files needed!

Method 2: Environment Variable Override

# TTFVT Mode Environment Variables
BYPASS_QUEUE=true                    # Skip SQS queue processing
ENABLE_SERVER_THROTTLING=false      # Disable server-side throttling
ENABLE_MEMENTOS=false               # Disable memory features
ENABLE_QUESTMASTER=false            # Disable quest planning
ENABLE_AGENTS=false                 # Disable agent processing
ENABLE_ARTIFACTS=false              # Disable artifact processing
PRESERVE_HISTORY=false              # Use minimal history (3 msgs)

# Performance Logging Control
NEXT_PUBLIC_VERBOSE_PERFORMANCE=true   # Enable/disable logs

Method 3: Runtime Control (Development Only)

// Toggle on/off (easiest way)
window.togglePerfLogs();

// Enable performance logs
window.enablePerfLogs();

// Disable performance logs  
window.disablePerfLogs();

// Check if enabled
window.isPerfLogsEnabled();

---

🔧 Usage Examples

Basic Logging

import perfLogger from './performanceLogger';

// These will only show when performance logging is enabled
perfLogger.log('🎯 Performance metric:', value);
perfLogger.info('📊 Database query completed in 150ms');
perfLogger.warn('⚠️ Slow operation detected');

// Errors always show (even in production)
perfLogger.error('🚨 Critical error occurred'); 

Performance Timing

perfLogger.time('database-query');
// ... execute database query ...
perfLogger.timeEnd('database-query');

// Output: "database-query: 142.50ms"

Conditional Logging

// Only log when performance mode is active
if (perfLogger.isEnabled()) {
  const metrics = calculateComplexMetrics();
  perfLogger.log('🎯 Complex metrics:', metrics);
}

---

📊 What Gets Logged

Streaming Performance

• ⚡ Real-time chunk timing and intervals
• 🔄 React Query update optimizations
• 🔌 WebSocket subscription lifecycle
• 🛡️ Smart throttling behavior

Database Performance

• 🗄️ Query execution times
• 📦 Cache hit/miss rates
• 📊 Batch operation metrics
• 🔍 Index usage statistics

Client Performance

• ⚛️ React Query batch operations
• 🎬 Optimistic UI updates
• 🤖 Agent detection timing
• 🎯 Component render performance

---

🎨 Log Categories & Examples

Emoji	Category	Example	Purpose
🎯	Performance Milestones	🎯 [STREAMING] Final React Query update completed	Key performance checkpoints
⚡	Speed Metrics	⚡ [STREAMING] Chunk received in 150ms	Timing measurements
🔄	State Changes	🔄 [QUERY_UPDATE] Starting async update	State transitions
🛡️	Optimizations	🛡️ [STREAMING] Smart throttling activated	Performance optimizations
🎬	User Actions	🎬 [STREAMING] Live streaming update applied	User-triggered events
🚨	Errors	🚨 [STREAMING] Error in streaming pipeline	Error conditions

---

📈 Performance Insights

Example Performance Log Output

🎯 [TTFVT] Query classified as: simple (fast-path enabled)
⚡ [PARALLEL] Features completed in 150ms (85% efficiency)
🛡️ [STREAMING] Smart throttling activated - 250ms intervals
🔄 [REACT_QUERY] Batch update: 15 items in 45ms
🎬 [UI] Live streaming chunk applied (chunk #42)
⏱️ [COMPLETION] Total time: 847ms (60% improvement)

Performance Patterns to Watch

Common Issues

• Slow chunks: ⚡ Chunk received in 500ms+ indicates network issues
• Throttling conflicts: 🛡️ Throttling disabled due to conflicts suggests optimization needed
• Cache misses: 📦 Cache MISS repeatedly indicates cache strategy issues

Good Performance

• Fast chunks: ⚡ Chunk received in 50-150ms is optimal
• High efficiency: 85%+ parallelization efficiency shows good optimization
• Quick updates: 🔄 Update completed in <100ms indicates smooth UX

---

🚀 Benefits

✅ Developer Experience

• Clean Development by Default: pnpm dev gives quiet console
• Performance Insights on Demand: pnpm devPerformance for debugging
• Zero Configuration: No env files needed
• Runtime Toggle: Enable/disable without restart

✅ Production Safety

• Always Disabled in Production: No performance impact
• Error Visibility: Critical errors always shown
• Selective Logging: Only relevant information when enabled

✅ Debugging Power

• Real-time Insights: See performance as it happens
• Category Filtering: Focus on specific subsystems
• Timing Analysis: Identify bottlenecks quickly

---

🎯 Best Practices

When to Enable Performance Logs

# 🎯 ENABLE when:
pnpm devPerformance    # Optimizing performance
pnpm devTTFVT          # Testing TTFVT improvements
# Debugging slow responses
# Analyzing streaming behavior
# Measuring optimization impact

# 🔇 DISABLE when:
pnpm dev               # Normal feature development  
# Focusing on UI/UX
# Working on business logic
# Clean console needed

Development Workflow

1. Daily Development: Use pnpm dev for clean console
2. Performance Work: Switch to pnpm devPerformance
3. Speed Optimization: Use pnpm devTTFVT for maximum insights
4. Quick Toggle: Use window.togglePerfLogs() for runtime control

---

🔗 Related Documentation

• TTFVT Optimizations - Performance optimization strategies
• Streaming Debug Guide - Debugging streaming issues
• Development Performance - General performance tips

---

🛠️ Implementation Details

Logger Architecture

class PerformanceLogger {
  private enabled: boolean;
  
  constructor() {
    this.enabled = this.checkEnvironment();
  }
  
  log(message: string, ...args: any[]) {
    if (this.enabled) {
      console.log(message, ...args);
    }
  }
  
  // Errors always show regardless of setting
  error(message: string, ...args: any[]) {
    console.error(message, ...args);
  }
}

Environment Detection

The logger automatically detects the appropriate mode based on:

• Environment variables
• Build configuration
• Runtime settings
• Script-based flags

Safety First

Performance logs are automatically disabled in production builds, ensuring zero impact on end users.