Skip to main content

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.
Response:
Status values:
  • healthy - All systems operational
  • connected / disconnected - Component status
  • not_configured - Optional component not enabled

GET /ready

Kubernetes readiness probe. Returns 200 when ready to accept traffic, 503 otherwise.
Response:
Use in Kubernetes:

GET /health/detailed

Comprehensive health with component details. Useful for debugging.
Response:

GET /metrics

Prometheus metrics endpoint. Requires INTERNAL_API_KEY in production.

Prometheus Metrics

All metrics use the stateset_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
Performance:
  • Cold start histogram
  • Warm pool hit rate
  • Exec latency distribution
  • K8s API latency
Resources:
  • 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

  1. Check metrics for error patterns:
  2. Review logs for stack traces:
  3. Check dependencies:
    • Database: curl /health | jq .database
    • Redis: curl /health | jq .redis
    • K8s API: kubectl get pods -n stateset-sandbox
  4. Common causes:
    • Database connection pool exhausted
    • K8s API rate limiting
    • Node resource pressure
    • Network issues

Slow Cold Starts

  1. Identify phase causing delay:
  2. Check warm pool:
  3. Check scheduling delays:
  4. Remediation:
    • Increase WARM_POOL_SIZE
    • Add more warm pool profiles
    • Check node resources
    • Verify image is pre-pulled

Database Issues

  1. Check connection:
  2. Check pool stats:
  3. Check for locks:
  4. Remediation:
    • Restart controller to reset pool
    • Check database server health
    • Review connection limits

Warm Pool Empty

  1. Check pool status:
  2. Check pod creation:
  3. Review events:
  4. Remediation:
    • Check cluster capacity
    • Review warm pool configuration
    • Check for image pull issues
    • Verify RBAC permissions

Memory Pressure

  1. Check controller memory:
  2. Check for leaks:
  3. 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:
  1. Database: Shared state via PostgreSQL
  2. Redis: Required for distributed warm pool
  3. 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

  1. Deploy new controller instance
  2. Restore database from backup
  3. Verify connectivity
  4. Run health checks
  5. Re-enable traffic

Security Operations

Rotating Secrets

JWT Secret:
  1. Generate new secret
  2. Update in Kubernetes secret
  3. Restart controller (all JWTs invalidated)
Database Encryption Key:
  1. Cannot rotate without re-encrypting data
  2. Plan data migration if needed
API Keys:

Audit Log Review

If AUDIT_LOGS_ENABLED=true:

Incident Response

  1. Contain: Suspend affected organization
  2. Investigate: Review audit logs and metrics
  3. Remediate: Revoke keys, patch vulnerabilities
  4. Recover: Restore normal operation
  5. Document: Post-incident review