Server dashboard
From 9.14.0, turning on the dashboard option makes the server serve a live status page. It is most useful on servers that run game logic inside the server (hosts), but a server without hosts still shows its server and traffic state.
import { Server } from 'iosignal' // 9.14.0 or later
const server = new Server({ port: 7777, dashboard: true })
// in a browser: http://server-address:7777/dashboard
It is off by default. The page ships inside the package, so it opens without internet access.
What it shows
| Panel | Content |
|---|---|
| Server | Gauges for CPU, event-loop delay (p99) and utilization, memory; a 5-minute load chart; connections (WebSocket, TCP, logged in) |
| Traffic | Messages and bytes received and sent per second, messages dropped by quota, slow connections and queued bytes |
| Hosts | For each host: participants, inputs, broadcasts and one-to-one sends per second, handler time, blocked forgeries, an input chart |
| Game loop | Actual tick interval (p50, p99) and step time against the host.loop() target, and values sent with host.report() |
| Participants | Inputs per participant, logged in or not, time joined, last input |
| Events | Timeline of joins, leaves, blocked forgeries and errors |
Viewers turn panels on and off at the top of the page; the choice is remembered in that browser. Charts update every second and follow light and dark mode.
Options
new Server({
port: 7777,
dashboard: {
path: '/dashboard', // page address; path + '/io.js' is used too
access: 'open', // 'open' | { token: '...' } | { login: { roles: ['admin'], cids: [] } }
panels: ['server', 'hosts'], // panels shown first (server, traffic, hosts, game, participants, events)
history: 300, // seconds kept for the charts (10-3600)
maxViewers: 20, // viewers at the same time (1-200)
showIdentities: false, // show participant CIDs and names (default: false when access is 'open')
},
})
Who may watch
access | Behavior | Good for |
|---|---|---|
'open' (default) | Anyone who knows the address. Only the first two characters of participant CIDs are shown | Classrooms, events, one local network |
{ token: '…' } | The page asks for the token (8 characters or more). Adding ?key=… to the address also works | A quick lock |
{ login: { roles, cids } } | Only connections logged in with this server's authentication whose role is roles (default ['admin']) or higher, or whose CID is in cids | Production servers |
IP addresses, keys and message contents are never sent, whatever the access. The dashboard is read-only; it cannot disconnect anyone.
On your own HTTP server
When you pass httpServer instead of port, call server.dashboard.handle(req, res) first in your request handler. It answers dashboard addresses and returns true.
const http = createServer((req, res) => {
if (server.dashboard.handle(req, res)) return
// everything else as before
})
const server = new Server({ httpServer: http, dashboard: { path: '/ops/status' } })
http.listen(8080)
Sending game state
Two additions to a host fill the "Game loop" panel.
const host = server.host('race', { inbound: ['race#in'], own: ['race#state'] })
// Instead of setInterval: runs every 33 ms and measures tick interval and step time
host.loop(33, (now) => {
game.step(now)
host.publish('race#state', game.snapshot())
})
// Values the game wants to show (numbers, short strings, booleans; up to 20). null removes one
host.report({ round: 3, players: game.players.size, leader: 'mina' })
- When a
host.loop()function throws, the host's'error'reports it and the loop goes on. It returns a stop function, andhost.close()stops every loop. - Per-host counters can also be read directly from
host.counters. The full list is in Server API: server host.
How it works
- The page connects as an IOSignal client, and a dashboard host inside the server (
iosignal.dashboard) sends state withhost.to()only to viewers who passed the check. Nobody can watch by subscribing to a channel, and other clients cannot forge the dashboard's frames. - The server computes its state once a second and keeps a history (
history), so the charts show the past minutes as soon as the page opens. Nothing is sent while nobody watches. - Dashboard connections count in connections and traffic. The page header shows how many viewers there are.
- When the server opens with
portand the dashboard is on, it makes its own HTTP server and serves the WebSocket and the page on the same port.