Analytics (TimescaleDB)

SkyView can persist long-term analytics when the Analytics license option is present. Bitrate measurements are stored once per second in TimescaleDB, automatically downsampled into 5-second and 1-minute continuous aggregates, and combined with a stream event log (online/offline and other pipeline events). The schema is ready to extend with KLV metadata and PostGIS later, but only the bitrate and event paths are enabled today.

Enabling Analytics

1. Add the TimescaleDB service from docker-compose.yml and expose it on a host port (default 5432).
2. Provide connection details to SkyView via environment variables:

SKY_VIEW_ANALYTICS_ENABLED=true
SKY_VIEW_ANALYTICS_HOST=127.0.0.1
SKY_VIEW_ANALYTICS_PORT=5432
SKY_VIEW_ANALYTICS_DB=skyview
SKY_VIEW_ANALYTICS_USER=skyview
SKY_VIEW_ANALYTICS_PASSWORD=skyview
COMPOSE_PROFILES=analytics

For production deployments, always override SKY_VIEW_ANALYTICS_PASSWORD (or use SKY_VIEW_ANALYTICS_DSN) so it matches your TimescaleDB credentials.

1. Ensure the license includes the Analytics option; otherwise, the endpoints will return 403 and ingestion is ignored.
2. If you prefer to manage analytics settings in the UI, see Analytics DB configuration for GUI overrides and connection testing.

TimescaleDB policies: - Hypertable: bitrate_samples (1-second samples) - Continuous aggregates: bitrate_5s, bitrate_1m - Automatic refresh policies (1–5 minutes) - Compression after 3 days, retention after 30 days

Bitrate sample aggregation

SkyView writes raw bitrate samples once per second into the bitrate_samples hypertable. TimescaleDB continuously aggregates those raw points into two rollups:

• bitrate_5s stores 5-second buckets with average, min, max, and sample counts.
• bitrate_1m stores 1-minute buckets with the same summary fields.

Aggregation runs in the background. Recent data may appear in raw form until the continuous aggregate refreshes, so queries can briefly show a mix of raw and aggregated buckets. The query endpoint automatically selects the best bucket size based on the requested time range.

REST endpoints

All endpoints require authentication. POST endpoints additionally require admin privileges.

Connection test

Test current configuration (uses payload values, does not save)

curl -X POST \
  "http://localhost:8100/api/analytics/connection/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dsn": "",
    "host": "127.0.0.1",
    "port": 5432,
    "database": "skyview",
    "user": "skyview",
    "password": "skyview",
    "sslMode": "disable"
  }'

The response includes state (connected or disconnected) and error when the test fails.

Bitrate samples

Ingest (1-second samples)

curl -X POST \
  "http://localhost:8100/api/analytics/streams/demo/bitrates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "samples": [
      {"timestamp": "2024-08-01T12:00:00Z", "bitrate": 3.25},
      {"bitrate": 3.1}
    ]
  }'

Query (auto bucket selection: raw/5s/1m)

curl -s \
  "http://localhost:8100/api/analytics/streams/demo/bitrates?start=2024-08-01T12:00:00Z&end=2024-08-01T13:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

Response fields include the selected bucket (raw, 5s, or 1m) and per-point averages/min/max/sample counts.

Stream events

Ingest online/offline or custom events

curl -X POST \
  "http://localhost:8100/api/analytics/streams/demo/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "Online", "severity": "info", "message": "Pipeline detected"},
      {"type": "Offline", "severity": "warning", "message": "Sensor timeout"}
    ]
  }'

Query event history

curl -s \
  "http://localhost:8100/api/analytics/streams/demo/events?limit=200" \
  -H "Authorization: Bearer $TOKEN"

Get latest status for one or more channels

curl -s \
  "http://localhost:8100/api/analytics/streams/status?streamIds=demo,camera-2" \
  -H "Authorization: Bearer $TOKEN"

If streamIds is omitted, SkyView queries all known streams and returns the newest event per channel.

Operational notes

• Analytics ingestion is skipped when the license lacks the Analytics option; the live UI continues using in-memory data.
• Continuous aggregates refresh in the background; initial queries may briefly read from raw samples until policies catch up.
• The schema keeps details as JSON for future KLV/PostGIS enrichment without breaking existing clients.