diff --git a/404.html b/404.html index c8a1f008..021e3b2e 100644 --- a/404.html +++ b/404.html @@ -1390,6 +1390,8 @@ + + @@ -1565,6 +1567,34 @@ +
  • + + + + + + + + Dashboard + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/dev/creating-a-service/index.html b/dev/creating-a-service/index.html index 8afb4b62..765eebf5 100644 --- a/dev/creating-a-service/index.html +++ b/dev/creating-a-service/index.html @@ -1638,6 +1638,8 @@ + + @@ -1816,6 +1818,34 @@ +
  • + + + + + + + + Dashboard + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/dev/rest-api/authentication/index.html b/dev/rest-api/authentication/index.html index 2dab4733..b0fa78e0 100644 --- a/dev/rest-api/authentication/index.html +++ b/dev/rest-api/authentication/index.html @@ -1410,6 +1410,8 @@ + + @@ -1868,6 +1870,34 @@ +
  • + + + + + + + + Dashboard + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/dev/rest-api/dashboard/index.html b/dev/rest-api/dashboard/index.html new file mode 100644 index 00000000..050c49ce --- /dev/null +++ b/dev/rest-api/dashboard/index.html @@ -0,0 +1,2260 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Dashboard - unshackle + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + + + Skip to content + + +
    +
    + +
    + + + + +
    + + +
    + +
    + + + + + + + + + +
    +
    + + + +
    +
    +
    + + + + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    + +
    + + + + + + + + +

    Developer Dashboard

    +

    The dashboard endpoints show the operator of a serve instance what the server is doing: +version and uptime, request counts, live remote sessions, download jobs, and the recent +log lines. They exist so you can watch a headless server (serve --quiet) from a web page +instead of a terminal.

    +

    The dashboard endpoints are for the person who runs the server, not for API users. They +have their own key: a user key or a tier key never opens them.

    +

    Enable

    +

    Set a dashboard key under serve.dashboard in unshackle.yaml:

    +
    serve:
+  api_secret: ...
+  dashboard:
+    key: a-long-random-string
+
    +

    Without dashboard.key the server does not register the routes, and they answer 404. +serve --no-key turns off user authentication only; the dashboard key stays required. +Once the dashboard key is set, every /api/dashboard/ request must carry it in +X-Secret-Key. +Every other endpoint refuses the dashboard key, and the dashboard refuses user keys. The +routes are available in --remote-only mode too.

    +

    Run the server headless with --quiet: no banner, no Rich output, one plain log line per +event on stderr, and api.* loggers stay at INFO so remote session activity reaches the +log ring. Add --debug to raise the level to DEBUG and also write the full log to +directories.logs as unshackle_serve_<time>.log. Nothing else the dashboard shows reaches +the disk: stats, the log ring and the event stream live in memory and reset on restart, so a +dashboard UI that wants history must keep its own copy.

    +
    unshackle serve --remote-only --quiet
+
    +

    Endpoints

    +

    All are GET.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    PathReturns
    /api/dashboard/statusVersion, code_hash, bind host and port, mode (full, api_only, remote_only), uptime, requests_total, requests_rejected (401s), requests_by_key (label → count), loaded service count, session count, max_sessions, session_ttl, job counts by status.
    /api/dashboard/sessionsEvery live remote session: id, owner (username or masked key), creator_ip, service, title_id, titles, tracks, title (the first resolved title's display name), auth_status, auth_error, client, actions, created_at and last_accessed (ISO 8601) with created_ts and last_accessed_ts (Unix epoch, the same clock as log ts), age_seconds, idle_seconds. client is whatever the remote client sent as client in its session create request (the current CLI sends nothing, so it is {}). actions is the session's request log, newest last, capped at 500: ts, method, action (titles, tracks, segments, license, prompt, …), query, status, ms, bytes_in, bytes_out.
    /api/dashboard/jobsEvery download job with full detail, regardless of owner. Empty in --remote-only mode.
    /api/dashboard/logs{"seq": N, "records": [...]}: the last 1000 log records. ?since=<seq> returns only newer records; ?level=WARNING sets the minimum level; ?logger=serve keeps one logger and its children (aiohttp.access is the noisiest). ts is a Unix epoch in seconds.
    /api/dashboard/eventsServer-Sent Events stream. With ?since=<seq> it returns {"seq", "stats", "events": [...]} instead: every event after seq (the server keeps the last 20000, log records included, so a poll every few seconds is safe even under a busy access log) as one JSON burst, so a UI that polls every few seconds still sees a remote session that opened and closed in between.
    +

    requests_rejected counts 401 responses; those never appear in requests_by_key. The +label is the username from the users entry when one is set, else the first four +characters of the API key.

    +

    Event stream

    +

    /api/dashboard/events sends a stats event (the same body as /status) on connect and +then every 5 seconds, so the connection stays alive and the counters stay current. Between +those it sends:

    + + + + + + + + + + + + + + + + + + + + + +
    EventData
    logOne log record: seq, ts, level, logger, msg.
    sessionaction (create, update on every request the session makes and when titles or tracks load, or delete) plus the full remote session summary, so each event is a complete snapshot. A delete also carries reason: closed (the client ended it), expired (TTL sweep) or evicted (max_sessions reached). A session opened by --skip-dl can live only a few seconds, so a UI that wants history must keep its own record of these events.
    jobevent (queued, progress, status, or the terminal status) plus the full job object.
    +

    Every frame carries an id: (the event seq). After a dropped connection an EventSource +reconnects with Last-Event-ID and the server replays the events it missed. The connection +never closes on its own.

    +

    A browser EventSource cannot set headers, so this route also accepts the dashboard key as +?secret_key=. The dashboard key then appears in proxy and access logs and in browser history, so +use the query parameter only for /events and send the header everywhere else.

    +
    const es = new EventSource(`${server}/api/dashboard/events?secret_key=${key}`);
+es.addEventListener("log", (e) => console.log(JSON.parse(e.data).msg));
+
    +

    CORS is open (Access-Control-Allow-Origin: *), so a dashboard page served from another +origin works without a proxy.

    + + + + + + + + + + + + + +
    +
    + + + + + +
    + + + +
    + + + +
    +
    +
    +
    + + + + + + + + + + + + + \ No newline at end of file diff --git a/dev/rest-api/endpoints/index.html b/dev/rest-api/endpoints/index.html index beab5354..d9a130b0 100644 --- a/dev/rest-api/endpoints/index.html +++ b/dev/rest-api/endpoints/index.html @@ -1410,6 +1410,8 @@ + + @@ -2094,6 +2096,34 @@ +
  • + + + + + + + + Dashboard + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/dev/rest-api/errors/index.html b/dev/rest-api/errors/index.html index a6809337..b72c84f3 100644 --- a/dev/rest-api/errors/index.html +++ b/dev/rest-api/errors/index.html @@ -1410,6 +1410,8 @@ + + @@ -1588,6 +1590,34 @@ +
  • + + + + + + + + Dashboard + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/dev/rest-api/index.html b/dev/rest-api/index.html index 4d934403..25ec8c04 100644 --- a/dev/rest-api/index.html +++ b/dev/rest-api/index.html @@ -1410,6 +1410,8 @@ + + @@ -1588,6 +1590,34 @@ +
  • + + + + + + + + Dashboard + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/dev/rest-api/job-lifecycle/index.html b/dev/rest-api/job-lifecycle/index.html index 6b30a68f..ca672a79 100644 --- a/dev/rest-api/job-lifecycle/index.html +++ b/dev/rest-api/job-lifecycle/index.html @@ -16,7 +16,7 @@ - + @@ -1410,6 +1410,8 @@ + + @@ -1873,6 +1875,34 @@ +
  • + + + + + + + + Dashboard + + + + + + + + +
    • + + + + + + + + + +
  • @@ -2955,13 +2985,13 @@ or logs them.

    -     +
    Next
    - Remote Sessions + Dashboard
    diff --git a/dev/rest-api/quickstart/index.html b/dev/rest-api/quickstart/index.html index ce44e43e..341b9b62 100644 --- a/dev/rest-api/quickstart/index.html +++ b/dev/rest-api/quickstart/index.html @@ -1410,6 +1410,8 @@ + + @@ -1773,6 +1775,34 @@ +
  • + + + + + + + + Dashboard + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/dev/rest-api/remote-sessions/index.html b/dev/rest-api/remote-sessions/index.html index cb160117..d00648bf 100644 --- a/dev/rest-api/remote-sessions/index.html +++ b/dev/rest-api/remote-sessions/index.html @@ -13,7 +13,7 @@ - + @@ -1410,6 +1410,8 @@ + + @@ -1586,6 +1588,34 @@ + + +
  • + + + + + + + + Dashboard + + + + + + + + +
    • + + + + + + + + @@ -2900,7 +2930,7 @@ to pick one.