Skip to main content

Cold Start Detection

This document explains how the application detects Cloud Run cold starts and provides user feedback during service initialization.

Overview​

The application includes a system for detecting when Cloud Run instances start from a cold state (no active instances) versus when they're already warm and ready to serve requests. This helps users understand when the server is "waking up" versus when it's processing their actual request.

Components​

PingService (src/app/services/ping.service.ts)​

Performs lightweight HTTP requests to detect cold starts in Cloud Run instances.

Key Features:

  • Makes HEAD requests to /health endpoint
  • Measures response time to detect cold starts (>1 second threshold)
  • Handles timeouts and network errors gracefully
  • Provides both cold start detection and simple connectivity checks

Usage:

// Inject the service
constructor(private pingService: PingService) {}

// Detect cold start
this.pingService.pingForColdStart().subscribe(result => {
  if (result.isColdStart) {
    console.log('Cold start detected!');
  }
  console.log(`Response time: ${result.responseTime}ms`);
});

// Simple connectivity check
this.pingService.quickPing().subscribe(isConnected => {
  console.log('Server reachable:', isConnected);
});

Configuration​

Cold Start Threshold​

The cold start detection threshold can be configured in PingService:

private readonly COLD_START_THRESHOLD = 1000; // 1 second

Ping Endpoint​

The ping endpoint can be configured in PingService:

private readonly PING_ENDPOINT = '/health'; // Lightweight health endpoint

Note: Your Cloud Run service should have a lightweight /health endpoint that returns quickly. This endpoint should:

  • Do minimal work (no database queries, etc.)
  • Return a 200 status code
  • Complete in under 100ms for warm instances

Testing​

A demo component is available at src/app/components/progress-demo/progress-demo.component.ts that demonstrates cold start detection functionality.

To test the demo, add a route to your application:

// In app.routes.ts
{
  path: 'progress-demo',
  component: ProgressDemoComponent
}

Best Practices​

  1. Use a lightweight health endpoint - avoid database queries or heavy operations
  2. Set appropriate thresholds - 1 second is a good default for Cloud Run
  3. Handle timeouts gracefully - network issues shouldn't break the user experience
  4. Test cold start scenarios - the functionality is most valuable when Cloud Run instances are scaled to zero

Troubleshooting​

Cold start detection not working​

  • Verify that your Cloud Run service has a /health endpoint
  • Check that the endpoint responds quickly (< 100ms for warm instances)
  • Ensure the endpoint is accessible without authentication or with the same auth as your main API
  • Check browser console for network errors

Architecture​

┌─────────────────┐    ┌──────────────────┐
│   Component     │    │  PingService     │
│                 │───▶│                  │
│ - User Action   │    │ - HTTP Ping      │
│ - API Call      │    │ - Timing         │
└─────────────────┘    │ - Cold Start     │
                       │   Detection      │
                       └──────────────────┘

This architecture provides clean separation between cold start detection and the main application logic, ensuring that users get appropriate feedback when services are starting up.