# sensiarion/uptime-kuma-metrics-proxy architecture

> Architecture diagram of the GitHub repository sensiarion/uptime-kuma-metrics-proxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sensiarion/uptime-kuma-metrics-proxy
- Repository: https://github.com/sensiarion/uptime-kuma-metrics-proxy

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Ingress
    Nginx["Nginx Reverse Proxy"]:::ingress
    click Nginx "https://github.com/sensiarion/uptime-kuma-metrics-proxy/blob/main/docker-compose.yaml"

    %% Application Services
    UptimeKuma["Uptime Kuma Service"]:::app
    MetricsProxy["Metrics Proxy"]:::app

    %% Monitoring Clients
    Prometheus["Prometheus Scraper"]:::monitoring
    Grafana["Grafana Dashboard"]:::monitoring

    %% Metrics Proxy Internal Structure
    subgraph "Metrics Proxy Internal"
        direction TB
        EntryPoint["Application Entry Point"]:::internal
        click EntryPoint "https://github.com/sensiarion/uptime-kuma-metrics-proxy/blob/main/src/main.rs"

        ConfigLoader["Config Loader"]:::internal
        click ConfigLoader "https://github.com/sensiarion/uptime-kuma-metrics-proxy/blob/main/src/common/config.rs"

        WebSocketClient["WebSocket Client (tags)"]:::internal
        click WebSocketClient "https://github.com/sensiarion/uptime-kuma-metrics-proxy/blob/main/src/websocket_parse.rs"

        HTTPServer["HTTP Server / Router"]:::internal
        click HTTPServer "https://github.com/sensiarion/uptime-kuma-metrics-proxy/blob/main/src/routes.rs"

        FilterEngine["Metrics Filter Engine"]:::internal
        click FilterEngine "https://github.com/sensiarion/uptime-kuma-metrics-proxy/blob/main/src/utils.rs"
    end

    %% Docker & Configuration
    DockerBuild["Docker Build Setup"]:::infra
    click DockerBuild "https://github.com/sensiarion/uptime-kuma-metrics-proxy/tree/main/Dockerfile"

    Orchestration["Container Orchestration"]:::infra
    click Orchestration "https://github.com/sensiarion/uptime-kuma-metrics-proxy/blob/main/docker-compose.yaml"

    EnvTemplate["Environment Config Template"]:::infra
    click EnvTemplate "https://github.com/sensiarion/uptime-kuma-metrics-proxy/blob/main/.env.example"

    Manifest["Rust Manifest & Lockfile"]:::infra
    click Manifest "https://github.com/sensiarion/uptime-kuma-metrics-proxy/blob/main/Cargo.toml"

    CICD["CI/CD Workflow"]:::infra
    click CICD "https://github.com/sensiarion/uptime-kuma-metrics-proxy/blob/main/.github/workflows/docker-image.yml"

    DocsAssets["Documentation Assets"]:::infra
    click DocsAssets "https://github.com/sensiarion/uptime-kuma-metrics-proxy/tree/main/docs/images"

    README["Project README"]:::infra
    click README "https://github.com/sensiarion/uptime-kuma-metrics-proxy/blob/main/README.md"

    %% Data Flows
    Prometheus -->|"HTTP GET /metrics"| Nginx
    Nginx -->|"Forward /metrics"| HTTPServer
    HTTPServer -->|"HTTP GET /metrics"| UptimeKuma
    UptimeKuma -->|"Metrics Stream"| FilterEngine
    FilterEngine -->|"Filtered Metrics"| HTTPServer
    HTTPServer -->|"HTTP Response"| Nginx
    Nginx -->|"Respond to Scrape"| Prometheus
    Prometheus -->|"Data Source"| Grafana

    %% WebSocket Tag Flow
    EntryPoint --> ConfigLoader
    EntryPoint --> WebSocketClient
    EntryPoint --> HTTPServer
    EntryPoint --> FilterEngine

    WebSocketClient -->|"WS subscribe"| UptimeKuma
    UptimeKuma -->|"Tags Payload"| WebSocketClient
    WebSocketClient -->|"Tags Cache"| FilterEngine

    %% Infra Relationships
    EntryPoint --> DockerBuild
    DockerBuild --> Orchestration
    Orchestration --> Nginx
    Orchestration --> UptimeKuma
    Orchestration --> MetricsProxy

    %% Legend
    subgraph "Legend"
        direction TB
        L1["Rectangle: Service/Component"]
        L2["Parallelogram: HTTP Endpoint"]
        L3["Lightning bolt: WebSocket"]
        L4["Blue: Ingress"]
        L5["Green: Application"]
        L6["Orange: Monitoring"]
        L7["Gray: Internal/Infra"]
    end

    %% Styles
    classDef ingress fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef app fill:#90EE90,stroke:#333,stroke-width:1px
    classDef monitoring fill:#FFA500,stroke:#333,stroke-width:1px
    classDef internal fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef infra fill:#E0E0E0,stroke:#333,stroke-width:1px
```
