Monitoring

📊 Monitoring & Observability

Metrics are implemented with the prometheus crate (stackhouse/src/platform/metrics.rs) and cover HTTP request counts/duration, DB query duration, auth events (signups/logins/OAuth/failed logins/token refreshes), storage operations, and realtime WebSocket connections/subscriptions.

Metrics Endpoints

GET /metrics              # Prometheus text-exposition format (mounted at root, not under /v1)
GET /v1/metrics/summary   # Human-readable JSON summary

curl http://localhost:3000/metrics

Response (text/plain; version=0.0.4, standard Prometheus exposition format):

# HELP stackhouse_http_requests_total Total HTTP requests
# TYPE stackhouse_http_requests_total counter
stackhouse_http_requests_total{method="GET",path="/v1/query/users",status="200"} 42
...

curl http://localhost:3000/v1/metrics/summary

Response:

{
  "uptime_seconds": 3600,
  "http": { "active_connections": 42 },
  "auth": { "total_signups": 10, "total_logins": 120, "failed_logins": 3 },
  "storage": { "total_uploads": 8, "total_downloads": 55 },
  "realtime": { "active_connections": 4, "active_subscriptions": 12, "total_messages": 900 }
}

Dashboard Integration

Prometheus:

scrape_configs:
  - job_name: 'stackhouse'
    metrics_path: '/metrics'
    static_configs:
      - targets: ['localhost:3000']

No packaged Grafana dashboard ships with this repo today — build panels against the metric names above, or export /metrics into your existing Prometheus/Grafana stack.

Alerts

Example AlertManager rules built on the exposed counters/histograms (stackhouse_http_requests_total, stackhouse_http_request_duration_seconds, stackhouse_auth_failed_logins_total, etc. — check the exact metric names via curl /metrics for your build):

groups:
  - name: stackhouse
    rules:
      - alert: HighAuthFailureRate
        expr: rate(stackhouse_auth_failed_logins_total[5m]) > 1
        for: 5m

Logging

Logging uses tracing with a compact formatter (see stackhouse/src/main.rs), controlled by the standard RUST_LOG env var (e.g. RUST_LOG=info, RUST_LOG=stackhouse=debug,tower_http=info). There is no [logging] config file — set RUST_LOG in your process environment.

Structured log forwarding is also supported: setting STACKHOUSE_LOG_DRAIN_URL (and optionally STACKHOUSE_LOG_DRAIN_KEY) enables an outbound log-drain client (stackhouse/src/platform/log_drain.rs), plus a /v1/admin log-drain management router for configuring drains per tenant.

Next: Backup & Recovery