Operations Guide
This guide covers monitoring, metrics, health checks, alerting, and operational procedures for running StateSet Sandbox in production.Health Endpoints
The controller exposes several health endpoints for monitoring and orchestration:GET /health
Basic health check returning current status.healthy- All systems operationalconnected/disconnected- Component statusnot_configured- Optional component not enabled
GET /ready
Kubernetes readiness probe. Returns 200 when ready to accept traffic, 503 otherwise.GET /health/detailed
Comprehensive health with component details. Useful for debugging.GET /metrics
Prometheus metrics endpoint. RequiresINTERNAL_API_KEY in production.
Prometheus Metrics
All metrics use thestateset_sandbox_ prefix.
HTTP Metrics
Sandbox Lifecycle
Warm Pool
Kubernetes Operations
API Keys & Auth
Plan & Billing
Errors
MicroVM & Advanced (when enabled)
eBPF Observability (when enabled)
Prometheus Configuration
Grafana Dashboards
Key Panels
Overview:- Active sandboxes gauge
- Sandbox creation rate
- Error rate
- P99 latency
- Cold start histogram
- Warm pool hit rate
- Exec latency distribution
- K8s API latency
- CPU utilization by org
- Memory utilization by org
- Network bandwidth
- Storage usage
Example Queries
Alerting Rules
Prometheus AlertManager
Logging
Log Levels
Log Format
Logs are JSON-formatted for easy parsing:Log Aggregation
Kubernetes with Loki:Useful Log Queries
Operational Runbooks
High Error Rate
-
Check metrics for error patterns:
-
Review logs for stack traces:
-
Check dependencies:
- Database:
curl /health | jq .database - Redis:
curl /health | jq .redis - K8s API:
kubectl get pods -n stateset-sandbox
- Database:
-
Common causes:
- Database connection pool exhausted
- K8s API rate limiting
- Node resource pressure
- Network issues
Slow Cold Starts
-
Identify phase causing delay:
-
Check warm pool:
-
Check scheduling delays:
-
Remediation:
- Increase
WARM_POOL_SIZE - Add more warm pool profiles
- Check node resources
- Verify image is pre-pulled
- Increase
Database Issues
-
Check connection:
-
Check pool stats:
-
Check for locks:
-
Remediation:
- Restart controller to reset pool
- Check database server health
- Review connection limits
Warm Pool Empty
-
Check pool status:
-
Check pod creation:
-
Review events:
-
Remediation:
- Check cluster capacity
- Review warm pool configuration
- Check for image pull issues
- Verify RBAC permissions
Memory Pressure
-
Check controller memory:
-
Check for leaks:
-
Remediation:
- Increase memory limits
- Review connection pool sizes
- Check for large response payloads
- Consider horizontal scaling
Scaling
Horizontal Scaling
The controller supports horizontal scaling with some considerations:- Database: Shared state via PostgreSQL
- Redis: Required for distributed warm pool
- Leader election: Not currently implemented (future)
Vertical Scaling
For single-instance deployments:Backup & Recovery
Database Backup
Critical Data
Ensure backup of:- API keys table (encrypted)
- Organizations and users
- Billing/usage records
- Audit logs (if enabled)
Recovery Procedure
- Deploy new controller instance
- Restore database from backup
- Verify connectivity
- Run health checks
- Re-enable traffic
Security Operations
Rotating Secrets
JWT Secret:- Generate new secret
- Update in Kubernetes secret
- Restart controller (all JWTs invalidated)
- Cannot rotate without re-encrypting data
- Plan data migration if needed
Audit Log Review
IfAUDIT_LOGS_ENABLED=true:
Incident Response
- Contain: Suspend affected organization
- Investigate: Review audit logs and metrics
- Remediate: Revoke keys, patch vulnerabilities
- Recover: Restore normal operation
- Document: Post-incident review