buswatch 0.2.6

Diagnostic TUI for monitoring Caryatid message bus activity
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

<div align="center">

```
 ____  ____  ____  _      ____  _____  ____  _     
/  _ \/  __\/  _ \/ \  /|/  _ \/__ __\/   _\/ \  /|
| | //|  \/|| / \|| |  ||| / \|  / \  |  /  | |__||
| |_\\|  __/| |-||| |/\||| |-||  | |  |  \_ | |  ||
\____/\_/   \_/ \|\_/  \|\_/ \|  \_/  \____/\_/  \|
```

<h3>Diagnostic toolkit for message bus observability</h3>

[![Crates.io](https://img.shields.io/crates/v/buswatch.svg)](https://crates.io/crates/buswatch)
[![Documentation](https://docs.rs/buswatch/badge.svg)](https://docs.rs/buswatch)
[![License](https://img.shields.io/crates/l/buswatch.svg)](LICENSE)

<hr/>
</div>

## Introduction

Buswatch is a collection of crates for monitoring and diagnosing message bus systems. It provides a terminal UI for real-time visualization, an instrumentation SDK for Rust applications, and adapters for popular message brokers.

Whether you're debugging a slow consumer, tracking message flow through your system, or just want visibility into your message bus, buswatch gives you the tools you need.

## Crates

The repository is organized as a Cargo workspace. Each crate serves a specific purpose and can be used independently or together.

### Core

| Crate | Description |
|-------|-------------|
| [buswatch-types](/buswatch-types) | Core type definitions and JSON schema for the wire format |
| [buswatch-tui](/buswatch-tui) | Terminal UI for real-time monitoring and diagnostics |

### Instrumentation

| Crate | Description |
|-------|-------------|
| [buswatch-sdk](/buswatch-sdk) | Lightweight SDK for instrumenting Rust applications |
| [buswatch-adapters](/buswatch-adapters) | Pre-built collectors for RabbitMQ, Kafka, and NATS |

## Quick Start

### Install the TUI

```bash
cargo install buswatch
```

### Monitor a JSON file

```bash
buswatch -f monitor.json
```

### Connect to a TCP stream

```bash
buswatch --connect localhost:9090
```

### Subscribe to RabbitMQ

```bash
buswatch --subscribe rabbitmq.toml --topic caryatid.monitor.snapshot
```

## Architecture

```
┌─────────────────┐     ┌─────────────────┐     ┌──────────────┐
│  Your App       │     │  Message Bus    │     │              │
│  + buswatch-sdk │────▶│  (RabbitMQ,     │◀────│  buswatch    │
│                 │     │   Kafka, NATS)  │     │  TUI         │
└─────────────────┘     └─────────────────┘     └──────────────┘
                                │
                                ▼
                        ┌─────────────────┐
                        │ buswatch-adapters│
                        │ (collectors)     │
                        └─────────────────┘
```

**Two ways to get data into buswatch:**

1. **Instrumentation (push)**: Add `buswatch-sdk` to your app and emit metrics
2. **Adapters (pull)**: Use `buswatch-adapters` to collect from your message bus

## Wire Format

All components communicate using the [buswatch snapshot format](/buswatch-types/schema/snapshot.schema.json):

```json
{
  "version": { "major": 1, "minor": 0 },
  "timestamp_ms": 1703160000000,
  "modules": {
    "order-processor": {
      "reads": {
        "orders.new": { "count": 1500, "backlog": 23 }
      },
      "writes": {
        "orders.processed": { "count": 1497 }
      }
    }
  }
}
```

See [buswatch-types](/buswatch-types) for the full schema and serialization options.

## Features

- **Real-time TUI** with summary, bottleneck, and flow views
- **Health detection** based on configurable thresholds
- **Sparklines** for visualizing trends
- **Multiple data sources**: files, TCP streams, message bus subscriptions
- **Instrumentation SDK** for Rust applications
- **Adapters** for RabbitMQ, Kafka, and NATS
- **OpenTelemetry** export support
- **JSON and CBOR** serialization

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.