Skip to content

Add orium doctor for runtime health and performance diagnostics #1

Description

@NoaLand

Title

Add orium doctor for runtime health and performance diagnostics

Story

As a Scriptorium developer,
I want to inspect the health and runtime performance of the Scriptorium system,
so that I can diagnose failures and performance problems without having to guess which process or component is responsible.

orium doctor should provide a single diagnostic entry point for the Scriptorium runtime.

The first version should focus on useful diagnostic information rather than a sophisticated UI.

Scope

orium doctor should be able to inspect:

  • Runtime health of Scriptorium processes/components
  • IPC connectivity between processes
  • Component readiness
  • Recent errors or unhealthy states
  • Runtime performance information where available
  • End-to-end input latency where instrumentation allows it

Example:

Scriptorium Doctor

[✓] brush          healthy
[✓] inkstone       healthy
[✓] ink            healthy
[✓] dictionary     healthy
[✓] IPC            healthy

Performance

brush → inkstone        0.42 ms
tokenization            0.71 ms
dictionary lookup       1.34 ms
inkstone → ink          0.31 ms

End-to-end              3.21 ms

Overall: Healthy

Observability foundation

Introduce or preserve the runtime instrumentation necessary for diagnostics.

Diagnostic events should be able to carry information such as:

Trace ID
Timestamp
Process / Component
Operation
Duration
Result

A single input operation should eventually be traceable across process boundaries, for example:

Keystroke
   ↓
Brush / TSF
   ↓
IPC
   ↓
Inkstone
   ↓
Tokenizer / Dictionary
   ↓
IPC
   ↓
Ink
   ↓
Candidate visible

The instrumentation should not depend on the eventual dashboard implementation.

Acceptance Criteria

  • orium doctor provides an overall runtime health summary.
  • Individual Scriptorium components can expose health/readiness information.
  • IPC failures can be distinguished from component failures.
  • Performance measurements can be exposed for instrumented operations.
  • Diagnostic information has sufficient timestamps/context to correlate operations across processes.
  • The diagnostic model does not depend on a particular TUI implementation.
  • The command remains useful even if no interactive dashboard is implemented.

Non-goals

This story does not require:

  • Historical performance charts
  • Advanced TUI navigation
  • Per-component dashboards
  • Persistent long-term telemetry storage
  • A polished monitoring UI

Those belong to Phase 2.

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