# 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.