failmap

Real-time microservice health monitoring dashboard.
Visualize your service dependencies as an interactive graph with live status updates.

---

Why failmap?

Monitoring tools are either overkill (Grafana + Prometheus + exporters) or too basic (uptime pings). failmap sits in the middle: drop a YAML config, run one binary, and instantly see your architecture as a live interactive map. No database, no agents, no setup.

Features

• Interactive graph — D3.js force-directed visualization of services and dependencies
• Real-time updates — WebSocket-powered, not polling
• HTTP & TCP checks — Monitor APIs, databases, caches, anything with a port
• Single binary — Static files embedded via embed.FS, no Node.js
• Zero external dependencies — No database, no message queue, no agents
• Dark UI — Clean modern dashboard, click any node for details
• Docker ready — docker compose up with demo services included

Quick Start

From source

git clone https://github.com/Jimmy7892/failmap.git
cd failmap
go build -o failmap ./cmd/failmap
./failmap -config failmap.example.yaml

Open http://localhost:8080

Docker

git clone https://github.com/Jimmy7892/failmap.git
cd failmap
docker compose up --build

This starts failmap with 3 demo microservices wired together.

Makefile

make run     # build + run with example config
make demo    # docker compose up --build
make build   # just compile

Configuration

Create a failmap.yaml:

server:
  port: 8080

services:
  - name: api-gateway
    url: http://localhost:8001/health
    type: http
    interval: 5s
    dependencies:
      - auth-service
      - postgres

  - name: auth-service
    url: http://localhost:8002/health
    type: http
    interval: 5s

  - name: postgres
    host: localhost:5432
    type: tcp
    interval: 10s

Service fields

Field	Type	Required	Description
name	string	yes	Unique service identifier
type	string	yes	http or tcp
url	string	http only	Health endpoint URL
host	string	tcp only	host:port to dial
interval	duration	no	Check frequency (default: 5s)
dependencies	[]string	no	Services this one depends on

Dashboard

Node colors

Color	Status	Condition
Green	Healthy	Check passed, latency < 2s
Yellow	Degraded	Check passed, latency > 2s
Red	Unhealthy	Check failed
Gray	Pending	Not yet checked

Interactions

• Drag nodes to rearrange the graph
• Click a node to open the detail panel (latency, uptime %, last check)
• Nodes pulse when unhealthy
• Edges animate to show dependency flow

API

Endpoint	Method	Description
/	GET	Dashboard UI
/api/services	GET	JSON snapshot of all service states
/ws	GET	WebSocket — streams { type: "update", services: {...} } on every check

Architecture

┌───────────┐     WebSocket      ┌────────────┐     goroutines      ┌──────────┐
│  Browser   │◄─────────────────►│  Go Server  │◄──────────────────►│ Services │
│  (D3.js)   │                   │  (net/http) │                    │ HTTP/TCP │
└───────────┘                    └────────────┘                     └──────────┘

• Config → YAML parsed at startup, defines services + dependencies
• Checker → One goroutine per service, runs health checks at configured intervals
• Hub → WebSocket broadcast hub, pushes state diffs to all connected browsers
• Frontend → D3.js force graph + vanilla JS, embedded in the binary

Project Structure

failmap/
├── cmd/
│   ├── failmap/          # Main binary entrypoint
│   │   ├── main.go
│   │   └── web/          # Embedded static frontend
│   │       ├── index.html
│   │       ├── style.css
│   │       └── app.js
│   └── demo/             # Demo microservice for docker-compose
├── internal/
│   ├── config/           # YAML configuration loader
│   ├── checker/          # Health check engine
│   ├── hub/              # WebSocket broadcast hub
│   └── api/              # HTTP + WebSocket handlers
├── failmap.example.yaml  # Example configuration
├── Dockerfile            # Multi-stage production build
├── docker-compose.yml    # Demo with mock services
└── Makefile

Tech Stack

Component	Technology
Backend	Go, net/http, goroutines
WebSocket	gorilla/websocket
Config	gopkg.in/yaml.v3
Frontend	D3.js v7, vanilla JS/CSS
Embedding	Go embed.FS
Container	Multi-stage Docker (Alpine)

License

MIT