511e52a05c
Create standalone monitoring container that subscribes to all CHORUS pub/sub topics and logs traffic in real-time for debugging and observability. Features: - Subscribes to chorus-bzzz, chorus-hmmm, chorus-context topics - Logs all messages with timestamps and sender information - Pretty-printed JSON output with topic-specific emojis - Minimal resource usage (256MB RAM, 0.5 CPU) - Read-only monitoring (doesn't publish messages) Files: - hmmm-monitor/main.go: Main monitoring application - hmmm-monitor/Dockerfile: Multi-stage build for minimal image - hmmm-monitor/docker-compose.yml: Swarm deployment config - hmmm-monitor/README.md: Usage documentation This tool helps debug council formation, task execution, and agent coordination by providing visibility into all HMMM/Bzzz traffic. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
121 lines
3.0 KiB
Markdown
121 lines
3.0 KiB
Markdown
# HMMM Traffic Monitor
|
|
|
|
Real-time monitoring tool for CHORUS libp2p pub/sub messages (HMMM and Bzzz).
|
|
|
|
## Purpose
|
|
|
|
This standalone monitoring container subscribes to all CHORUS pub/sub topics and logs all traffic in real-time. It's designed for:
|
|
|
|
- **Debugging**: See exactly what messages are being sent
|
|
- **Observability**: Monitor agent coordination and task execution
|
|
- **Development**: Understand message flow during development
|
|
- **Troubleshooting**: Identify communication issues between agents
|
|
|
|
## Topics Monitored
|
|
|
|
- `chorus-bzzz`: Main coordination topic (task claims, availability, progress)
|
|
- `chorus-hmmm`: Meta-discussion topic (help requests, collaboration)
|
|
- `chorus-context`: Context feedback messages
|
|
- `council-formation`: Council formation broadcasts
|
|
- `council-assignments`: Role assignments
|
|
|
|
## Usage
|
|
|
|
### Build the Image
|
|
|
|
```bash
|
|
cd hmmm-monitor
|
|
docker build -t anthonyrawlins/hmmm-monitor:latest .
|
|
```
|
|
|
|
### Run Locally
|
|
|
|
```bash
|
|
docker run --rm --network chorus_net anthonyrawlins/hmmm-monitor:latest
|
|
```
|
|
|
|
### Deploy to Swarm
|
|
|
|
```bash
|
|
docker stack deploy -c docker-compose.yml hmmm-monitor
|
|
```
|
|
|
|
### View Logs
|
|
|
|
```bash
|
|
# Real-time logs
|
|
docker service logs -f hmmm-monitor_hmmm-monitor
|
|
|
|
# Filter by topic
|
|
docker service logs hmmm-monitor_hmmm-monitor | grep "chorus-bzzz"
|
|
|
|
# Filter by message type
|
|
docker service logs hmmm-monitor_hmmm-monitor | grep "availability_broadcast"
|
|
|
|
# Export to file
|
|
docker service logs hmmm-monitor_hmmm-monitor > hmmm-traffic-$(date +%Y%m%d).log
|
|
```
|
|
|
|
## Message Format
|
|
|
|
Each logged message includes:
|
|
|
|
```json
|
|
{
|
|
"timestamp": "2025-10-11T12:30:45Z",
|
|
"topic": "chorus-bzzz",
|
|
"from": "12D3Koo...",
|
|
"type": "availability_broadcast",
|
|
"payload": {
|
|
"agent_id": "agent-123",
|
|
"current_tasks": 1,
|
|
"max_tasks": 3,
|
|
"available_for_work": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## Emojis
|
|
|
|
The monitor uses emojis to quickly identify message types:
|
|
|
|
- 🐝 General Bzzz coordination
|
|
- 📊 Availability broadcasts
|
|
- 🎯 Capability broadcasts
|
|
- ✋ Task claims
|
|
- ⏳ Task progress
|
|
- ✅ Task complete
|
|
- 🧠 HMMM meta-discussion
|
|
- 💬 Discussion messages
|
|
- 🆘 Help requests
|
|
- 💡 Help responses
|
|
- 🚨 Escalation triggers
|
|
- 🎭 Council formation
|
|
- 👔 Council assignments
|
|
|
|
## Troubleshooting
|
|
|
|
### No messages appearing
|
|
|
|
1. Check network connectivity: `docker exec hmmm-monitor ping chorus`
|
|
2. Verify container is on correct network: `docker inspect hmmm-monitor | grep NetworkMode`
|
|
3. Check CHORUS agents are publishing: `docker service logs CHORUS_chorus | grep "broadcast"`
|
|
|
|
### High CPU usage
|
|
|
|
The monitor processes all pub/sub traffic. If CPU usage is high, consider:
|
|
- Reducing replicas count
|
|
- Filtering logs externally rather than in the container
|
|
- Running only during debugging sessions
|
|
|
|
## Architecture
|
|
|
|
The monitor is a minimal libp2p node that:
|
|
|
|
1. Joins the same libp2p network as CHORUS agents
|
|
2. Subscribes to gossipsub topics
|
|
3. Logs all received messages
|
|
4. Does NOT publish any messages (read-only)
|
|
|
|
This makes it safe to run in production without affecting agent behavior.
|