CHORUS/hmmm-monitor

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

cd hmmm-monitor
docker build -t anthonyrawlins/hmmm-monitor:latest .

Run Locally

docker run --rm --network chorus_net anthonyrawlins/hmmm-monitor:latest

Deploy to Swarm

docker stack deploy -c docker-compose.yml hmmm-monitor

View Logs

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

{
  "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.