Files

anthonyrawlins 511e52a05c feat: Add HMMM traffic monitoring tool

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>

2025-10-11 12:30:43 +11:00

3.0 KiB

Raw Blame History

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

Check network connectivity: docker exec hmmm-monitor ping chorus
Verify container is on correct network: docker inspect hmmm-monitor | grep NetworkMode
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:

Joins the same libp2p network as CHORUS agents
Subscribes to gossipsub topics
Logs all received messages
Does NOT publish any messages (read-only)

This makes it safe to run in production without affecting agent behavior.

3.0 KiB Raw Blame History