Observability: metrics, health and logs

You can only run what you can see

StreamHub is built to be observed. Out of the box it exposes Prometheus metrics, a health probe, a server-stats endpoint, and a structured log store — the four things you need to run a media server without guessing.

Prometheus at /metrics

The core exposes prom-client metrics at the root /metrics path (outside the /api/v1 prefix, per Prometheus convention). It is public by default, or you can require a METRICS_TOKEN. Every metric is prefixed streamhub_:

• streamhub_active_streams — live streams, by app.
• streamhub_stream_viewers — last observed viewer count per stream.
• streamhub_vods / streamhub_vods_generated_total — VOD rows by status and totals.
• streamhub_upload_queue_depth — VODs pending upload, by app.
• streamhub_s3_uploads_total / streamhub_s3_errors_total — storage health.
• streamhub_recording_failures_total — failures, by reason.
• streamhub_tenant_quota / streamhub_tenant_usage — usage against limits.
• streamhub_http_request_duration_seconds — request latency histogram.

LiveKit exposes its own native metrics too — scrape both for the full picture.

A Prometheus scrape job

scrape_configs:
  - job_name: streamhub
    metrics_path: /metrics
    static_configs:
      - targets: ['media.example.com']

From there, Grafana dashboards and alertmanager rules are downstream: alert on streamhub_upload_queue_depth climbing, on streamhub_recording_failures_total increasing, or on streamhub_active_streams hitting your capacity line.

Health and stats

• GET /api/v1/health is a public liveness probe returning { status, up, version, uptimeSeconds } — point your load balancer or uptime monitor here.
• GET /api/v1/stats (authenticated) returns a rich snapshot: CPU load, memory, disk, whether LiveKit / egress / ingress are reachable, and counts of apps, rooms and active streams.

curl -s $BASE/health
curl -s $BASE/stats -H "Authorization: Bearer $TOKEN"

Logs you can query

Beyond metrics, StreamHub keeps a structured, queryable log store, and the streamhub logs CLI tails compose logs and can save them for a support bundle. Between metrics for trends, stats for a point-in-time snapshot, and logs for the detail, you can answer "is it healthy, and if not, why" without SSHing around blindly.