How sensiarion/uptime-kuma-metrics-proxy works
Project Type and Purpose
• This is a small, containerized proxy microservice written in Rust.
• Its sole purpose is to sit between Uptime Kuma and Prometheus (and by extension, Grafana), fetch tags over a WebSocket feed, and filter the raw Prometheus metrics stream based on those tags.
File Structure
• Top-level files:
– Cargo.toml / src/**: the Rust binary’s code.
– Dockerfile, docker-compose.yaml, .env.example: containerization and environment setup.
– docs/images: sample PNGs that illustrate high-level data flow.
• src/ modules:
– common/config.rs: loads .env/.env.example
– websocket_parse.rs: establishes socket.io connection, pulls service+tag info
– routes.rs: implements HTTP server endpoints (/metrics, /metrics/{tag})
– utils.rs + errors.rs: parsing and error handling
README for Architecture Insights
• The README shows two key flows:
– “How it works demonstration” (pulling tags over WebSocket)
• The docker-compose snippet reveals a three-container network: domain-nginx, uptime_kuma, metrics_proxy.
Main System Components
a. External Traffic Ingress (domain-nginx)
b. Uptime Kuma Service (louislam/uptime-kuma:1)
c. Metrics Proxy Service (this Rust binary)
– WebSocket Client (fetch tags)
– HTTP Server (act as Prometheus metrics endpoint)
– Metrics Filter Engine (filter by tag or pass-through)
d. Monitoring Consumers
– Prometheus scraper
– Grafana dashboards
Relationships and Data Flows
• On startup, Metrics Proxy opens a socket.io connection to Uptime Kuma to pull the full list of services & tags.
• Every scrape request from Prometheus (to /metrics or /metrics/{tag}) arrives via Nginx → Metrics Proxy HTTP server.
• The proxy forwards (or rewrites) the request to the underlying Uptime Kuma /metrics endpoint, streams back the Prometheus text, applies the tag filter, then returns the filtered stream.
• Prometheus ingests these metrics. Grafana reads from Prometheus.
Architectural Patterns
• Single‐responsibility microservice: only metrics proxy + filter.
• Event‐driven tag refresh via WebSocket with TTL caching.
• HTTP reverse-proxy pattern for metrics path rewriting.
• Containerized deployment (Docker, docker-compose).
Technologies/Frameworks
• Rust (Tokio runtime, Hyper or Actix for HTTP, socket.io client lib)
• Docker + docker-compose for orchestration
• Nginx as reverse proxy + TLS termination
• Prometheus + Grafana as monitoring stack
Final Checklist
– [ ] Sub-components inside Metrics Proxy: Config Loader, WebSocket Client, HTTP Router, Filter Engine
– [ ] Notes on TTL-based tag refresh and caching