Skip to content

Story 2 — Add rich interactive views to orium doctor --watch #2

Description

@NoaLand

Title

Add interactive runtime observability views to orium doctor --watch

Story

As a Scriptorium developer,
I want to observe runtime health and performance interactively over time,
so that I can understand performance trends, identify regressions, and locate bottlenecks across individual components.

Build on the diagnostic and telemetry capabilities introduced by orium doctor.

orium doctor --watch should provide a live TUI/dashboard rather than a one-shot diagnostic report.

Overview View

Provide an overall system view containing:

┌─ Scriptorium Doctor ───────────────────────────────────────┐
│ Overall  ● HEALTHY                         Uptime 01:42:17 │
├─ Processes ──────────────────┬─ IPC ───────────────────────┤
│ ● brush                      │ brush → inkstone   0.4 ms  │
│ ● inkstone                   │ inkstone → ink     0.3 ms  │
│ ● ink                        │                            │
│ ● dictionary                 │                            │
├─ Performance ────────────────┴────────────────────────────┤
│ avg     3.1 ms     p50 2.8 ms                            │
│ p95     5.4 ms     p99 8.7 ms                            │
├─ Recent Events ───────────────────────────────────────────┤
│ brush       composition changed                           │
│ inkstone    candidates generated                          │
│ ink         candidate window updated                      │
└───────────────────────────────────────────────────────────┘

Component Views

Allow individual runtime components to have dedicated views, for example:

orium doctor --watch inkstone
orium doctor --watch brush
orium doctor --watch dictionary

A component view may expose:

Requests       12,481
Average         1.42 ms
P50             1.17 ms
P95             2.83 ms
P99             5.21 ms
Errors             3

Historical Performance

Keep a bounded history of runtime telemetry so that performance can be visualised over time.

For example:

Latency

8ms │                  ╭╮
6ms │             ╭╮   ││
4ms │     ╭─╮    ╭╯╰───╯╰╮
2ms │─────╯ ╰────╯        ╰────
    └───────────────────────────
      -60s                  now

The historical view should make performance regressions and transient latency spikes easier to identify.

Views

The TUI may eventually provide views such as:

[1] Overview
[2] Latency
[3] IPC
[4] Errors
[5] Events

The exact interaction model is intentionally left open until the underlying telemetry capabilities are mature enough to drive the design.

Acceptance Criteria

  • orium doctor --watch continuously updates runtime information.
  • Overall system health can be observed without leaving the dashboard.
  • Individual components can be inspected independently.
  • Recent performance history can be visualised.
  • Common latency statistics such as average, p50, p95 and p99 can be displayed.
  • IPC latency can be distinguished from component processing latency where instrumentation permits.
  • Recent errors/events can be correlated with performance behaviour.
  • The dashboard consumes the diagnostic/telemetry model from Phase 1 rather than introducing a separate observability mechanism.
  • The UI remains independent from the runtime components being observed.

Non-goals

This phase does not need to become a general-purpose monitoring platform.

The goal is specifically:

Make Scriptorium observable enough that runtime and performance problems can be investigated instead of guessed.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions