Crate buswatch_tui 

buswatch

A diagnostic TUI and library for monitoring Caryatid message bus activity.

This crate provides tools for visualizing and diagnosing the health of modules communicating via the Caryatid message bus. It can receive monitor snapshots from various sources (files, channels, network streams) and display them in an interactive terminal UI.

Architecture

The crate is organized into four main modules:

┌─────────────────────────────────────────────────────────────┐
│                        Application                          │
│  ┌─────────┐    ┌──────────┐    ┌─────────┐    ┌─────────┐ │
│  │  app    │───▶│   data   │───▶│   ui    │───▶│ Terminal│ │
│  │ (state) │    │(processing)   │(rendering)   │         │ │
│  └────┬────┘    └──────────┘    └─────────┘    └─────────┘ │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────┐                                                │
│  │ source  │◀── FileSource | StreamSource | ChannelSource  │
│  │ (input) │                                                │
│  └─────────┘                                                │
└─────────────────────────────────────────────────────────────┘

• app: Application state, view navigation, and user interaction logic
• source: Data source abstraction (DataSource trait) with implementations for file polling, TCP streams, and channel-based input
• data: Data models and processing - converts raw snapshots into health-annotated MonitorData, tracks history for sparklines, and builds data flow graphs
• ui: Terminal rendering using ratatui - summary tables, bottleneck views, flow matrices, and theme support

Features

• Summary view: Overview of all modules with health status
• Bottleneck detection: Highlights topics with pending reads/writes
• Data flow visualization: Shows producer/consumer relationships
• Historical tracking: Sparklines and rate calculations

Usage

As a CLI tool

# Monitor a JSON file (produced by caryatid's Monitor)
buswatch --file monitor.json

# Monitor via TCP connection
buswatch --connect localhost:9090

As a library with file source

use buswatch_tui::{App, FileSource, Thresholds};

let source = Box::new(FileSource::new("monitor.json"));
let app = App::new(source, Thresholds::default());

As a library with stream source (TCP, etc.)

use std::io::Cursor;
use buswatch_tui::{App, StreamSource, Thresholds};

// Example with a cursor (in practice, use TcpStream)
let data = b"{}\n";
let stream = Cursor::new(data.to_vec());
let source = StreamSource::spawn(stream, "example");
let app = App::new(Box::new(source), Thresholds::default());

As a library with channel source (for message bus integration)

use buswatch_tui::{App, ChannelSource, Thresholds};

// Create a channel for receiving snapshots
let (tx, source) = ChannelSource::create("rabbitmq://localhost");

// Create the app
let app = App::new(Box::new(source), Thresholds::default());

Bridging from a message bus

use buswatch_tui::StreamSource;
use tokio::sync::mpsc;

// Create a bytes channel
let (tx, rx) = mpsc::channel::<Vec<u8>>(16);
let source = StreamSource::from_bytes_channel(rx, "rabbitmq");

Re-exports

pub use app::App;

pub use data::HealthStatus;

pub use data::ModuleData;

pub use data::MonitorData;

pub use data::Thresholds;

pub use data::TopicRead;

pub use data::TopicWrite;

pub use source::ChannelSource;

pub use source::DataSource;

pub use source::FileSource;

pub use source::StreamSource;

pub use buswatch_types;

Modules

app

Application state and navigation logic.

data

Data models and processing for monitor snapshots.

events

Event handling for keyboard and mouse input.

source

Data source abstraction for receiving monitor snapshots.

subscribe

RabbitMQ subscription for receiving monitor snapshots.

ui

Terminal UI rendering using ratatui.

Structs

Microseconds

Duration in microseconds.

ModuleMetrics

Metrics for a single module/consumer/producer in the message bus.

ReadMetrics

Metrics for reading from a topic (subscription/consumer).

SchemaVersion

Schema version information embedded in snapshots.

Snapshot

A point-in-time snapshot of message bus metrics.

WriteMetrics

Metrics for writing to a topic (publication/producer).