Hosting edition

Metrics, reports and locations

Scrape per-station Prometheus metrics, export the listener sessions and song plays that royalty collecting societies ask for, and see which countries listeners are in.

All three are part of the Hosting edition. The open-source core has the status endpoints instead.

Prometheus metrics#

GET /metrics returns Prometheus text. It accepts the hosting API token as a bearer token, or the admin account with basic authentication.

curl -H "Authorization: Bearer $TOKEN" https://radio.example/metrics

Every metric is a gauge.

Metric Labels Value
lurcast_uptime_seconds none Seconds since the server started.
lurcast_listeners mount, station Connected listeners per mount.
lurcast_source_connected mount, station 1 when a source is connected.
lurcast_bitrate_kbps mount, station Stream bitrate in kbps.
lurcast_station_month_bytes_sent station Bytes sent to listeners this month (UTC).
lurcast_station_month_listener_seconds station Listening time this month (UTC).
lurcast_station_transfer_quota_bytes station Monthly transfer quota. Absent when the station has no quota.
lurcast_station_suspended station 1 when the station is suspended.
lurcast_license_expiry_timestamp_seconds none When the license expires, as a Unix timestamp.

The per-mount metrics carry a station label only for mounts that belong to a provisioned station; other mounts, such as relays from the configuration file, have only mount.

lurcast_listeners{mount="/rockfm",station="rockfm"} 87
lurcast_station_month_bytes_sent{station="rockfm"} 52428800000
lurcast_station_transfer_quota_bytes{station="rockfm"} 107374182400

Scrape configuration#

Store the API token in a file Prometheus can read, then:

scrape_configs:
  - job_name: lurcast
    scheme: https
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/lurcast-token
    static_configs:
      - targets: ["radio.example:443"]

Alerts worth having#

groups:
  - name: lurcast
    rules:
      - alert: LurcastLicenseExpiresSoon
        expr: lurcast_license_expiry_timestamp_seconds - time() < 7 * 86400
        labels:
          severity: warning
      - alert: LurcastStationNearQuota
        expr: lurcast_station_month_bytes_sent / lurcast_station_transfer_quota_bytes > 0.9
        labels:
          severity: info

Automatic renewal starts 10 days before expiry, so a license that is still within 7 days of expiry usually means renewal is failing. See Licensing and renewal.

Royalty reports#

The server logs every listener session and every song change to CSV files, one pair per station and month:

<data_dir>/reports/<station>/<YYYY-MM>-sessions.csv
<data_dir>/reports/<station>/<YYYY-MM>-plays.csv

Download them through the API, or read them from disk:

curl -H "Authorization: Bearer $TOKEN" -o rockfm-2026-11-sessions.csv \
  'https://radio.example/api/hosting/v1/stations/rockfm/reports/sessions.csv?month=2026-11'
curl -H "Authorization: Bearer $TOKEN" -o rockfm-2026-11-plays.csv \
  'https://radio.example/api/hosting/v1/stations/rockfm/reports/plays.csv?month=2026-11'

sessions.csv#

One row per listener session, written when the listener disconnects.

Column Contents
started_at, ended_at RFC 3339 timestamps.
duration_seconds Length of the session.
bytes_sent Bytes sent to this listener.
ip Listener address, truncated to /24 (IPv4) or /48 (IPv6) while anonymize_ips is on.
user_agent The player's user agent.
listener_id The server's ID for the connection.
mount The mount listened to.
country The listener's country code, such as SE, when listener locations are on. Empty otherwise.

plays.csv#

One row per song change, from the source's metadata.

Column Contents
played_at RFC 3339 timestamp.
artist, title Split from Artist - Title. If the title has no -, artist is empty.
raw_title The metadata exactly as the source sent it.
listeners Listeners connected when the song started.

Plays are only as good as the metadata your customers' encoders send.

Monthly summary#

GET /api/hosting/v1/stations/{id}/reports/summary?month=YYYY-MM totals the month:

  • Aggregate tuning hours: the sum of all session durations, in hours.
  • Total performances: the sum of listeners across every play.
{
  "station": "rockfm",
  "month": "2026-11",
  "summary": {
    "sessions": 4210,
    "aggregate_tuning_hours": 1820.5,
    "plays": 3150,
    "total_performances": 61240
  }
}

These are the figures most collecting societies, such as SoundExchange, PRS and STIM, ask for. Each society has its own template and rules, so check them before you submit.

Listener locations#

Point the Hosting edition at a country database to see where listeners are:

hosting:
  geoip_database: /var/lib/lurcast/dbip-country-lite.mmdb

Any country database in MaxMind DB format (.mmdb) works:

  • DB-IP IP to Country Lite: free under CC BY 4.0, with no account. Download the .mmdb from db-ip.com. It is updated monthly.
  • MaxMind GeoLite2 Country: free with a MaxMind account.

Each listener's country is looked up on your server when they connect. No listener address is sent anywhere, and only the country is kept, never the city. The lookup uses the full address, so sessions.csv can show listening per country even while anonymize_ips truncates the address in the ip column. The country appears:

  • in the admin dashboard: a Listener locations panel for the whole server, a Where listeners are chart per mount, and a country column in the listener list
  • in the country column of sessions.csv, for collecting societies that ask for listening by territory
  • in the listener.connected and listener.disconnected webhooks

Listener locations in the dashboard

To update the database, replace the file and reload the configuration (Reload config in the dashboard, or systemctl reload). Behind a reverse proxy, set trusted_proxies so the listener's own address is looked up, not the proxy's.

Session files started before the country column existed keep their original columns until the next month begins.