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
Next steps
Production guide
Capacity planning and warm-pool profiles behind the metrics here.
Security guide
The controls whose audit trail feeds these alerts.
API reference
The controller endpoints these health checks sit alongside.
Deployments
Where to wire the Prometheus and Grafana configuration for each cloud.