diff --git a/.env.example b/.env.example index 9099563..677317f 100644 --- a/.env.example +++ b/.env.example @@ -1,3 +1,9 @@ WEB_PORT=5173 API_PORT=3000 DATABASE_URL=postgres://postgres:postgres@localhost:5432/zeavis_edu + +# ── Telemetry / ClickHouse ────────────────────────────────────────── +# These credentials are used by the telemetry Docker Compose stack. +# See telemetry/deploy/.env.example for production overrides. +CLICKHOUSE_USER=telemetry +CLICKHOUSE_PASSWORD=telemetry diff --git a/.gitignore b/.gitignore index 54b8758..b174b3a 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,5 @@ coverage/ *.tsbuildinfo .DS_Store + +.claude/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..4675227 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "telemetry"] + path = telemetry + url = https://github.com/MythEclipse/Telemetry.git diff --git a/CLAUDE.md b/CLAUDE.md index 48573c0..196231f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -107,6 +107,31 @@ Run the ML service directly: cd apps/ml-service && cargo run ``` +Run the Telemetry stack: + +```bash +# Start all telemetry services (Prometheus, Ingester, Vector, ClickHouse, Query Proxy, Telemetry UI) +make telemetry-up + +# Local dev mode (port bindings exposed) +make telemetry-up-local + +# Check health of all telemetry services +make telemetry-status + +# View telemetry logs +make telemetry-logs [s=] + +# Build telemetry components +make telemetry-build + +# Send a test metric +make telemetry-test-metric + +# Stop telemetry +make telemetry-down +``` + ## High-level architecture - `Machine_Learning/preprocessing.py` prepares the training dataset locally. It extracts three source ZIP files, merges selected class folders into `dataset/`, maps selected Mandarin labels from Dataset 3 via `desc.json`, removes known problematic image files, then creates `dataset.zip` for upload to Google Drive/Colab. @@ -116,6 +141,22 @@ cd apps/ml-service && cargo run - TensorFlow.js export is intentionally done with the `tensorflowjs_converter` CLI rather than from Python to avoid protobuf/runtime conflicts documented in the README. - `apps/ml-service/` is a Rust/Axum service that loads the ONNX model and serves HTTP endpoints for health checks, metadata, and image classification predictions. It uses ONNX Runtime for cross-platform inference performance. +## Telemetry architecture + +The repository includes a full Prometheus → ClickHouse metric pipeline as a git submodule at `telemetry/`. Each ZeaVis Edu service exposes a `GET /metrics` endpoint: + +- **Web app** (`apps/web`): In dev mode, a Vite plugin serves client-side session metrics (page views, Web Vitals). In production, nginx proxies `/metrics` to the API service. Source: `apps/web/src/lib/telemetry.ts`, `apps/web/vite-plugin-metrics.ts`. +- **API** (`apps/api`): Uses `prom-client` for Node.js default metrics plus custom HTTP, auth, classification, and diagnosis counters/histograms. Source: `apps/api/src/lib/telemetry.ts`, exposed via `apps/api/src/routes/metrics.ts`. +- **ML service** (`apps/ml-service`): Uses the `prometheus` Rust crate for HTTP metrics, prediction counts, and model load status. Source: `apps/ml-service/src/telemetry.rs`. + +All three share the `zeavis_` metric prefix and are scraped by the Telemetry Prometheus instance via `file_sd_configs` (see `telemetry/prometheus/targets/zeavis-edu.json`). + +**IMPORTANT — Production architecture:** ZeaVis Edu apps and the Telemetry stack run on **separate VPS instances** connected via **Tailscale** (mesh VPN). Prometheus scrapes the API and ML service through their **Tailscale IPs** (e.g. `100.x.x.a:3000`), not via Docker hostnames. The target file `telemetry/prometheus/targets/zeavis-edu.json` has `__CHANGE_ME__` placeholders — before deploying, replace with the actual Tailscale IPs of the app VPS. + +The telemetry stack is managed from the project root via `make telemetry-*` targets (see `Makefile`). The Docker Compose files in `telemetry/deploy/` define 6 services (Prometheus, Metric Ingester, Vector, ClickHouse, Query Proxy, Telemetry UI). + +For **local single-host dev**, Prometheus can reach app services via a shared Docker network (`app-shared-net`). Use `make telemetry-up-local` for this mode — it includes the `docker-compose.telemetry.yml` override. + ## Fullstack application architecture The root TypeScript workspace is a Bun + Moon monorepo: diff --git a/METRICS.md b/METRICS.md new file mode 100644 index 0000000..af8ba31 --- /dev/null +++ b/METRICS.md @@ -0,0 +1,121 @@ +# ZeaVis Edu — Metrics Endpoints + +This document lists every Prometheus metrics endpoint exposed by the ZeaVis Edu +application stack and the payload each service provides. + +--- + +## Overview + +| Service | Host (prod) | Metrics Endpoint | Port (local) | +|-----------------------|-----------------------------------|----------------------------|--------------| +| Web (Vite dev) | `zeavisedu.asepharyana.my.id` | `GET /metrics` | 5173 | +| API (Elysia) | `api-zeavisedu.asepharyana.my.id` | `GET /metrics` | 3000 | +| ML Service (Axum) | `ml-zeavisedu.asepharyana.my.id` | `GET /metrics` | 8000 | +| Prometheus Collector | — | `GET /metrics` (self) | 9090 | + +> In production all metrics are scraped by the Prometheus collector running in the +> Telemetry stack on a **separate VPS** connected via **Tailscale**. +> See [`telemetry/prometheus/targets/`](./telemetry/prometheus/targets/) +> for the auto‑discovery configuration. Target files must use **Tailscale IPs** +> (e.g. `100.x.x.a:3000`), not Docker hostnames, because the services are on +> different hosts. +> +> In production (nginx), the web app proxies `/metrics` to the API service: +> see [`apps/web/nginx.conf`](apps/web/nginx.conf). +> +> For local development the Vite plugin `vite-plugin-metrics.ts` serves +> client‑side session metrics at `GET /metrics` on the Vite dev server. + +--- + +## 1. Web App — `GET /metrics` + +| Endpoint | Description | +|-------------------|--------------------------------------------------| +| `/metrics` | Vite dev‑server middleware + client‑side snapshot | + +### Metrics + +| Metric Name | Type | Labels | Description | +|-------------------------------------|---------|-------------------------------|------------------------------------------| +| `zeavis_web_page_views_total` | counter | — | Total page views this session | +| `zeavis_web_vital_bucket` | gauge | `name`, `rating` | Last‑seen Web Vitals (CLS, FCP, INP…) | + +**Development:** served inline by the Vite plugin `vite-plugin-metrics.ts`. +**Production:** the static frontend serves no `/metrics` endpoint — consider +forwarding the Vite dev server, or use the Telemetry collector to scrape +client‑side beacons. + +--- + +## 2. API (Elysia/Bun) — `GET /metrics` + +| Endpoint | Description | +|-------------------|--------------------------------------------------| +| `/metrics` | Prometheus text format via `prom-client` | + +### Metrics + +| Metric Name | Type | Labels | Description | +|--------------------------------------------|-----------|--------------------------------|------------------------------------------| +| `zeavis_api_http_requests_total` | counter | `method`, `path`, `status` | Total HTTP requests | +| `zeavis_api_http_request_duration_seconds` | histogram | `method`, `path` | Request latency buckets | +| `zeavis_api_http_requests_active` | gauge | — | Concurrently‑handled requests | +| `zeavis_api_classifications_total` | counter | `result` | AI image classifications | +| `zeavis_api_diagnoses_total` | counter | `disease` | Created diagnoses | +| `zeavis_api_auth_operations_total` | counter | `operation`, `success` | Login / register attempts | +| Default Node.js metrics | various | — | CPU, memory, event‑loop lag, GC … | + +**Source:** `apps/api/src/lib/telemetry.ts`, instrumented in `routes/`. + +--- + +## 3. ML Service (Rust/Axum) — `GET /metrics` + +| Endpoint | Description | +|-------------------|--------------------------------------------------| +| `/metrics` | Prometheus text format via `prometheus` crate | + +### Metrics + +| Metric Name | Type | Labels | Description | +|--------------------------------------------|-----------|--------------------------------|------------------------------------------| +| `zeavis_ml_http_requests_total` | counter | — | Total HTTP requests | +| `zeavis_ml_http_request_duration_seconds` | histogram | — | Request latency buckets | +| `zeavis_ml_http_requests_active` | gauge | — | Concurrently‑handled requests | +| `zeavis_ml_predictions_total` | counter | — | Successful ONNX predictions | +| `zeavis_ml_model_load_status` | gauge | — | 1 = loaded, 0 = not loaded | +| Process metrics (libc/procfs) | various | — | RSS, CPU, fd count … | + +**Source:** `apps/ml-service/src/telemetry.rs`, instrumented in `routes.rs`. + +--- + +## Prometheus Auto‑Discovery (Telemetry Stack) + +The Telemetry submodule includes a Prometheus instance that uses +`file_sd_configs` to discover targets. Place a target file under +`telemetry/prometheus/targets/` with content such as: + +```json +[ + { + "targets": ["100.x.x.a:3000"], + "labels": { "service": "zeavis-api", "component": "backend", "env": "production" } + }, + { + "targets": ["100.x.x.b:8000"], + "labels": { "service": "zeavis-ml", "component": "inference", "env": "production" } + } +] +``` + +> ⚠️ **Cross-VPS:** Gunakan **IP Tailscale** (bukan Docker hostname) karena +> Prometheus dan ZeaVis Edu berjalan di VPS berbeda. Pastikan port service +> (`:3000`, `:8000`) terekspos di `0.0.0.0` atau diizinkan oleh aturan +> `iptables`/`ufw` untuk interface Tailscale (`tailscale0`/`100.x.x.x/10`). + +The Prometheus config (in `telemetry/prometheus/prometheus.yml`) will +automatically pick up new files within its 15‑second scrape interval — +no restart required. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..8559fa3 --- /dev/null +++ b/Makefile @@ -0,0 +1,151 @@ +# ============================================================================= +# ZeaVis Edu — Root Makefile +# +# Orchestrates the application stack (web, api, ml) and the telemetry +# metric pipeline (Prometheus → Ingester → Vector → ClickHouse). +# +# Telemetry commands operate on the submodule at telemetry/. +# ============================================================================= + +.PHONY: dev build typecheck +.PHONY: telemetry-up telemetry-down telemetry-build telemetry-logs telemetry-restart telemetry-init-db telemetry-test-metric telemetry-status +.PHONY: up-all down-all + +SHELL := /bin/bash + +# ────────────────────────────────────────────────────────────────────────────── +# Application (Bun / Moon) +# ────────────────────────────────────────────────────────────────────────────── + +dev: + bun run dev + +build: + bun run build + +typecheck: + bun run typecheck + +# ────────────────────────────────────────────────────────────────────────────── +# Telemetry Stack +# +# Docker commands reference the telemetry submodule compose file: +# telemetry/deploy/docker-compose.yml +# +# For local development, append the port override: +# make telemetry-up-local +# +# The telmetry compose file is inside the submodule so paths (volumes, +# build context) are relative to telemetry/ — but we run docker compose +# from the project root using -f. +# ────────────────────────────────────────────────────────────────────────────── + +TELEMETRY_COMPOSE := telemetry/deploy/docker-compose.yml +TELEMETRY_LOCAL := telemetry/deploy/docker-compose.local.yml +TELEMETRY_ZEAVIS := docker-compose.telemetry.yml + +# Start all telemetry services (standalone — cross-VPS production mode) +# Prometheus scrapes ZeaVis Edu via Tailscale IPs, not Docker network. +telemetry-up: + @echo ">> Starting Telemetry stack (standalone)..." + CLICKHOUSE_USER=$${CLICKHOUSE_USER:-telemetry} \ + CLICKHOUSE_PASSWORD=$${CLICKHOUSE_PASSWORD:-telemetry} \ + docker compose -f $(TELEMETRY_COMPOSE) up -d + @echo ">> Telemetry stack started. Use 'make telemetry-logs' to view output." + +# Start telemetry services with ZeaVis Edu network sharing (local single-host dev) +# Prometheus can scrape app services via app-shared-net Docker network. +telemetry-up-local: + @echo ">> Starting Telemetry stack (local dev mode)..." + CLICKHOUSE_USER=$${CLICKHOUSE_USER:-telemetry} \ + CLICKHOUSE_PASSWORD=$${CLICKHOUSE_PASSWORD:-telemetry} \ + docker compose -f $(TELEMETRY_COMPOSE) -f $(TELEMETRY_LOCAL) -f $(TELEMETRY_ZEAVIS) up -d + @echo ">> Telemetry stack started in local dev mode." + +# Stop all telemetry services +telemetry-down: + @echo ">> Stopping Telemetry stack..." + docker compose -f $(TELEMETRY_COMPOSE) -f $(TELEMETRY_ZEAVIS) down + @echo ">> Telemetry stack stopped." + +# Build telemetry components (metric-ingester + telemetry-ui) +# Runs inside the telemetry submodule using its own Makefile. +telemetry-build: + @echo ">> Building Telemetry components..." + $(MAKE) -C telemetry build + @echo ">> Telemetry components built." + +# Tail telemetry logs (optionally filter by service: s=) +telemetry-logs: +ifdef s + CLICKHOUSE_USER=$${CLICKHOUSE_USER:-telemetry} \ + CLICKHOUSE_PASSWORD=$${CLICKHOUSE_PASSWORD:-telemetry} \ + docker compose -f $(TELEMETRY_COMPOSE) -f $(TELEMETRY_ZEAVIS) logs -f $(s) +else + CLICKHOUSE_USER=$${CLICKHOUSE_USER:-telemetry} \ + CLICKHOUSE_PASSWORD=$${CLICKHOUSE_PASSWORD:-telemetry} \ + docker compose -f $(TELEMETRY_COMPOSE) -f $(TELEMETRY_ZEAVIS) logs -f +endif + +# Restart a single telemetry service +telemetry-restart: +ifdef s + @echo ">> Restarting service: $(s)..." + CLICKHOUSE_USER=$${CLICKHOUSE_USER:-telemetry} \ + CLICKHOUSE_PASSWORD=$${CLICKHOUSE_PASSWORD:-telemetry} \ + docker compose -f $(TELEMETRY_COMPOSE) -f $(TELEMETRY_ZEAVIS) restart $(s) + @echo ">> Service $(s) restarted." +else + @echo "Usage: make telemetry-restart s=" + @echo "Services: prometheus metric-ingester vector clickhouse query-proxy telemetry-ui" + @exit 1 +endif + +# Initialize ClickHouse schema +telemetry-init-db: + @echo ">> Initializing ClickHouse schema..." + cd telemetry/clickhouse && DOCKER_CONTAINER=telemetry-clickhouse bash init.sh + @echo ">> Schema initialized." + +# Send a test metric through the pipeline +telemetry-test-metric: + @echo ">> Sending test metric to Vector on port 9001..." + curl -X POST http://localhost:9001/metrics \ + -H "Content-Type: application/json" \ + -d '{"metric_name":"test_zeavis","value":1.0,"timestamp":"$(shell date -u +%Y-%m-%dT%H:%M:%SZ)","labels":{"service":"zeavis-edu"},"env":"dev","region":"local"}' + @echo "" + @echo ">> Metric sent. Check telemetry-logs to verify ingestion." + +# Show service status (health check overview) +telemetry-status: + @echo ">> Telemetry stack status:" + @echo "" + @echo "--- Prometheus ---" + -curl -s --max-time 3 http://localhost:9090/-/healthy && echo " healthy" || echo " unhealthy" + @echo "" + @echo "--- Metric Ingester ---" + -curl -s --max-time 3 http://localhost:9091/health || echo " unhealthy" + @echo "" + @echo "--- Vector ---" + -curl -s --max-time 3 http://localhost:9001/health || echo " unhealthy" + @echo "" + @echo "--- ClickHouse ---" + -curl -s --max-time 3 http://localhost:8123/ping && echo " healthy" || echo " unhealthy" + @echo "" + @echo "--- Query Proxy ---" + -curl -s --max-time 3 http://localhost:9092/health || echo " unhealthy" + @echo "" + @echo "--- Telemetry UI ---" + -curl -s --max-time 3 -o /dev/null -w "%{http_code}" http://localhost:8181/ && echo " ok" || echo " unhealthy" + +# ────────────────────────────────────────────────────────────────────────────── +# Combined +# ────────────────────────────────────────────────────────────────────────────── + +# Start everything (app + telemetry) +up-all: telemetry-up + bun run dev + +# Stop everything +down-all: telemetry-down + @echo ">> All services stopped." diff --git a/README.md b/README.md index ef03ae4..a50dbf4 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,17 @@ Model klasifikasi menargetkan empat label berbahasa Indonesia: - GitHub Container Registry - Traefik labels untuk routing deployment +### Telemetry & Observability + +- Prometheus — metric scraping & remote_write +- Metric Ingester (Go) — enrichment, filtering, aggregation +- Vector — buffering & backpressure +- ClickHouse — columnar analytical storage +- Query Proxy (Go) — read-only SQL proxy +- Telemetry UI (Vue 3) — metrics dashboard +- Semua service ZeaVis Edu (web, api, ml-service) mengekspos metrik Prometheus di `/metrics` +- Client-side Web Vitals (CLS, FCP, INP, LCP, TTFB) dikumpulkan di frontend + ## Prasyarat Untuk menjalankan seluruh project secara lokal, siapkan: @@ -203,6 +214,142 @@ Contoh menjalankan compose setelah environment dan network siap: docker compose up -d ``` +## Telemetry Stack + +Proyek ini menyertakan pipeline telemetry metric sebagai git submodule di `telemetry/`. Pipeline mengalirkan metrik dari seluruh service ZeaVis Edu ke ClickHouse untuk analisis dan visualisasi jangka panjang. + +### Arsitektur (Production) + +Di production, aplikasi dan telemetry berjalan di **VPS terpisah** dan terhubung via **Tailscale** (mesh VPN). Prometheus di VPS telemetry melakukan scrape ke service ZeaVis Edu melalui IP Tailscale masing-masing. + +```mermaid +flowchart LR + subgraph VPS1["VPS — ZeaVis Edu (App)"] + W[Web / React
api-zeavisedu.asepharyana.id] + A[API / Elysia
:3000] + M[ML Service / Axum
:8000] + end + + subgraph VPS2["VPS — Telemetry Stack"] + P[Prometheus
:9090] + MI[Metric Ingester
:9091] + V[Vector
:9001] + CH[ClickHouse
:8123] + QP[Query Proxy
:9092] + TUI[Telemetry UI
:8181] + end + + P -.->|"scrape via Tailscale IP
100.x.x.a:3000/metrics"| A + P -.->|"scrape via Tailscale IP
100.x.x.a:8000/metrics"| M + P -->|remote_write| MI + MI --> V + V --> CH + QP --> CH + TUI --> QP +``` + +Setiap service ZeaVis Edu mengekspos endpoint `/metrics` dalam format Prometheus text: + +| Service | Endpoint | Port (lokal) | +|-----------------------|--------------------|--------------| +| Web (Vite dev) | `GET /metrics` | 5173 | +| API (Elysia) | `GET /metrics` | 3000 | +| ML Service (Axum) | `GET /metrics` | 8000 | + +Prometheus di VPS telemetry melakukan **scrape langsung** ke API dan ML service melalui IP Tailscale mereka, bukan melalui domain publik. Konfigurasi target ada di `telemetry/prometheus/targets/zeavis-edu.json` — isi dengan IP Tailscale dari service yang dituju. + +Lihat [`METRICS.md`](./METRICS.md) untuk daftar lengkap metrik yang diekspos. + +### Service Telemetry + +| # | Service | Peran | Port | +|---|---------|------|------| +| 1 | **Prometheus** | Metric scraping & remote_write | 9090 | +| 2 | **Metric Ingester** | Enrichment, filtering, aggregation | 9091 | +| 3 | **Vector** | Buffering, backpressure, retry | 9001 | +| 4 | **ClickHouse** | Columnar analytical storage | 8123 / 9000 | +| 5 | **Query Proxy** | Read-only SQL proxy, tenant isolation | 9092 | +| 6 | **Telemetry UI** | Vue 3 metrics dashboard | 8181 | + +### Arsitektur (Local Dev) + +Untuk development lokal di satu mesin, telemetry dan app bisa jalan bareng di satu Docker host. Prometheus bisa scrape service lewat Docker network yang sama. + +```bash +# Setup network +docker network create app-shared-net + +# Build & start telemetry (dengan network sharing) +make telemetry-up-local +``` + +### Menjalankan Telemetry Stack + +Semua operasi telemetry dijalankan dari **root proyek** melalui Makefile: + +```bash +# Build komponen telemetry (metric-ingester + telemetry-ui) +make telemetry-build + +# Start semua service telemetry (mode produksi, via Tailscale) +make telemetry-up + +# Start semua service telemetry (mode lokal — port langsung terbuka) +make telemetry-up-local + +# Cek status kesehatan semua service +make telemetry-status + +# Lihat log (semua service, atau filter dengan s=) +make telemetry-logs +make telemetry-logs s=metric-ingester + +# Restart service tertentu +make telemetry-restart s=prometheus + +# Kirim test metric +make telemetry-test-metric + +# Stop semua service +make telemetry-down +``` + +Untuk development lokal: + +```bash +# Setup network jika belum ada +docker network create telemetry-net +docker network create app-shared-net + +# Build & start +make telemetry-build +make telemetry-up-local + +# Buka dashboard di http://localhost:8181 +``` + +### Prometheus Auto-Discovery + +Prometheus menggunakan `file_sd_configs` untuk menemukan target secara dinamis. Cukup letakkan file JSON di `telemetry/prometheus/targets/` dan Prometheus akan otomatis mendeteksinya dalam 15 detik — tanpa restart. + +File template sudah tersedia di [`telemetry/prometheus/targets/zeavis-edu.json`](telemetry/prometheus/targets/zeavis-edu.json). **Sebelum production, isi `__CHANGE_ME__` dengan IP Tailscale masing-masing service:** + +```json +[ + { "targets": ["100.x.x.a:3000"], "labels": { "service": "zeavis-api", "component": "backend", "env": "production" } }, + { "targets": ["100.x.x.a:8000"], "labels": { "service": "zeavis-ml", "component": "inference", "env": "production" } } +] +``` + +> **Catatan:** Aplikasi ZeaVis Edu mengekspose port Docker-nya (`:3000`, `:8000`) langsung ke host via `docker-compose.yml`. Pastikan port-port tersebut terbuka di network Tailscale (biasanya iptables Tailscale mengizinkan koneksi ke port localhost). + +### Environment Variables Telemetry + +| Variable | Default | Deskripsi | +|----------|---------|-----------| +| `CLICKHOUSE_USER` | `telemetry` | User ClickHouse | +| `CLICKHOUSE_PASSWORD` | `telemetry` | Password ClickHouse | + ## Workflow Machine Learning Detail lengkap tersedia di [`Machine_Learning/README.md`](Machine_Learning/README.md). Ringkasnya: diff --git a/apps/api/.gitignore b/apps/api/.gitignore new file mode 100644 index 0000000..34fee9f --- /dev/null +++ b/apps/api/.gitignore @@ -0,0 +1,4 @@ + +.claude/ + +.codegraph/ diff --git a/apps/api/package.json b/apps/api/package.json index 65c4bc6..0995564 100644 --- a/apps/api/package.json +++ b/apps/api/package.json @@ -13,11 +13,17 @@ }, "dependencies": { "@elysiajs/cors": "1.4.2", + "@opentelemetry/api": "1.9.1", + "@opentelemetry/exporter-prometheus": "0.218.0", + "@opentelemetry/instrumentation-http": "0.218.0", + "@opentelemetry/sdk-node": "0.218.0", + "@opentelemetry/semantic-conventions": "1.41.1", "@zeavis/shared": "workspace:*", "bcryptjs": "^3.0.3", "drizzle-orm": "^0.45.2", "elysia": "^1.4.28", - "postgres": "^3.4.9" + "postgres": "^3.4.9", + "prom-client": "15.1.3" }, "devDependencies": { "@types/bcryptjs": "^3.0.0", diff --git a/apps/api/src/index.ts b/apps/api/src/index.ts index 2d80cc4..91d11be 100644 --- a/apps/api/src/index.ts +++ b/apps/api/src/index.ts @@ -9,6 +9,9 @@ import { diagnosisRoutes } from './routes/diagnoses'; import { dashboardRoutes } from './routes/dashboard'; import { authRoutes } from './routes/auth'; import { expertRoutes } from './routes/expert'; +import { metricsRoutes } from './routes/metrics'; +import { httpRequestCounter, httpRequestDuration, httpRequestsActive } from './lib/telemetry'; +import './types'; assertRequiredEnv(); @@ -17,6 +20,24 @@ const app = new Elysia() origin: env.webAppUrl, credentials: true, })) + .use(metricsRoutes) + .onBeforeHandle(({ request, path }) => { + httpRequestsActive.inc(); + request.metricsStart = performance.now(); + request.metricsPath = path; + }) + .onAfterHandle(({ request, set }) => { + const start = (request as any).metricsStart as number | undefined; + const path = (request as any).metricsPath as string | undefined; + if (start && path) { + const duration = (performance.now() - start) / 1000; + const method = request.method; + const status = set.status ?? 200; + httpRequestCounter.labels(method, path, String(status)).inc(); + httpRequestDuration.labels(method, path).observe(duration); + } + httpRequestsActive.dec(); + }) .use(healthRoutes) .use(statusRoutes) .use(authRoutes) diff --git a/apps/api/src/lib/telemetry.ts b/apps/api/src/lib/telemetry.ts new file mode 100644 index 0000000..cd55a90 --- /dev/null +++ b/apps/api/src/lib/telemetry.ts @@ -0,0 +1,62 @@ +import { Registry, Counter, Histogram, Gauge, collectDefaultMetrics } from 'prom-client'; + +const registry = new Registry(); + +// Collect default Node.js metrics (CPU, memory, event loop, etc.) +collectDefaultMetrics({ register: registry }); + +// ── HTTP Metrics ──────────────────────────────────────── + +export const httpRequestCounter = new Counter({ + name: 'zeavis_api_http_requests_total', + help: 'Total number of HTTP requests handled by the API', + labelNames: ['method', 'path', 'status'] as const, + registers: [registry], +}); + +export const httpRequestDuration = new Histogram({ + name: 'zeavis_api_http_request_duration_seconds', + help: 'Histogram of HTTP request durations in seconds', + labelNames: ['method', 'path'] as const, + buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5], + registers: [registry], +}); + +export const httpRequestsActive = new Gauge({ + name: 'zeavis_api_http_requests_active', + help: 'Number of HTTP requests currently being processed', + registers: [registry], +}); + +// ── Business Metrics ──────────────────────────────────── + +export const classificationCounter = new Counter({ + name: 'zeavis_api_classifications_total', + help: 'Total number of classification predictions requested via API', + labelNames: ['result'] as const, + registers: [registry], +}); + +export const diagnosisCounter = new Counter({ + name: 'zeavis_api_diagnoses_total', + help: 'Total number of diagnoses created', + labelNames: ['disease'] as const, + registers: [registry], +}); + +export const authCounter = new Counter({ + name: 'zeavis_api_auth_operations_total', + help: 'Total authentication operations (login, register, refresh)', + labelNames: ['operation', 'success'] as const, + registers: [registry], +}); + +// ── Export ────────────────────────────────────────────── + +export function getMetricsContentType(): string { + return registry.contentType; +} + +export async function getMetrics(): Promise { + return await registry.metrics(); +} diff --git a/apps/api/src/routes/auth.ts b/apps/api/src/routes/auth.ts index 2d4fc81..770d1e5 100644 --- a/apps/api/src/routes/auth.ts +++ b/apps/api/src/routes/auth.ts @@ -16,6 +16,7 @@ import { verifyPassword, } from '../lib/auth'; import { env } from '../config/env'; +import { authCounter } from '../lib/telemetry'; function normalizeEmail(email: unknown) { return typeof email === 'string' ? email.trim().toLowerCase() : ''; @@ -63,6 +64,8 @@ export const authRoutes = new Elysia({ prefix: '/api/v1/auth' }) const token = await createSession(user.id); set.headers['Set-Cookie'] = createSessionCookie(token); + authCounter.labels('register', 'true').inc(); + return { user: { id: user.id, @@ -90,12 +93,15 @@ export const authRoutes = new Elysia({ prefix: '/api/v1/auth' }) const user = rows[0]; if (!user?.passwordHash || !(await verifyPassword(req!.password!, user.passwordHash))) { + authCounter.labels('login', 'false').inc(); return badRequest('Invalid email or password'); } const token = await createSession(user.id); set.headers['Set-Cookie'] = createSessionCookie(token); + authCounter.labels('login', 'true').inc(); + return { user: { id: user.id, diff --git a/apps/api/src/routes/classifications.ts b/apps/api/src/routes/classifications.ts index 6f67dc6..b39d943 100644 --- a/apps/api/src/routes/classifications.ts +++ b/apps/api/src/routes/classifications.ts @@ -16,6 +16,7 @@ import { desc, eq } from 'drizzle-orm'; import { classifyImage } from '../lib/image-model'; import { uploadImageToStorage } from '../lib/uploader-client'; import { toDisease } from '../lib/disease-mappers'; +import { classificationCounter } from '../lib/telemetry'; function toImageClassificationRecord(row: { id: string; @@ -141,6 +142,8 @@ export const classificationRoutes = new Elysia({ prefix: '/api/v1' }) ); } + classificationCounter.labels(classificationResult.predictedDiseaseSlug).inc(); + const db = createDbClient(); let diseaseRow; try { diff --git a/apps/api/src/routes/diagnoses.ts b/apps/api/src/routes/diagnoses.ts index 4d8f1fd..b839f6b 100644 --- a/apps/api/src/routes/diagnoses.ts +++ b/apps/api/src/routes/diagnoses.ts @@ -9,6 +9,7 @@ import { getCurrentUser } from '../lib/auth'; import { classifyImage } from '../lib/image-model'; import { uploadImageToStorage } from '../lib/uploader-client'; import { env } from '../config/env'; +import { diagnosisCounter } from '../lib/telemetry'; interface ReviewRow { reviewId: string | null; @@ -222,6 +223,9 @@ export const diagnosisRoutes = new Elysia({ prefix: '/api/v1' }) const record = await loadDiagnosisRecord(inserted[0].id, user.id, false); if (!record) return serviceUnavailable('Database unavailable'); + + diagnosisCounter.labels(record.predictedDiseaseSlug ?? 'unknown').inc(); + return record; } catch (error) { const inserted = await db @@ -240,6 +244,9 @@ export const diagnosisRoutes = new Elysia({ prefix: '/api/v1' }) const record = await loadDiagnosisRecord(inserted[0].id, user.id, false); if (!record) return serviceUnavailable('Database unavailable'); + + diagnosisCounter.labels('failed').inc(); + return record; } }) diff --git a/apps/api/src/routes/metrics.ts b/apps/api/src/routes/metrics.ts new file mode 100644 index 0000000..86c6ced --- /dev/null +++ b/apps/api/src/routes/metrics.ts @@ -0,0 +1,10 @@ +import { Elysia } from 'elysia'; +import { getMetrics, getMetricsContentType } from '../lib/telemetry'; + +export const metricsRoutes = new Elysia() + .get('/metrics', async () => { + const body = await getMetrics(); + return new Response(body, { + headers: { 'Content-Type': getMetricsContentType() }, + }); + }); diff --git a/apps/api/src/types.ts b/apps/api/src/types.ts new file mode 100644 index 0000000..be30f73 --- /dev/null +++ b/apps/api/src/types.ts @@ -0,0 +1,8 @@ +declare global { + interface Request { + metricsStart?: number; + metricsPath?: string; + } +} + +export {}; diff --git a/apps/ml-service/.gitignore b/apps/ml-service/.gitignore index 6e37796..d31fa60 100644 --- a/apps/ml-service/.gitignore +++ b/apps/ml-service/.gitignore @@ -1,3 +1,6 @@ .venv/ __pycache__/ -target/ \ No newline at end of file +target/ +.claude/ + +.codegraph/ diff --git a/apps/ml-service/Cargo.lock b/apps/ml-service/Cargo.lock index d540e14..7f11a66 100644 --- a/apps/ml-service/Cargo.lock +++ b/apps/ml-service/Cargo.lock @@ -111,7 +111,7 @@ dependencies = [ "num-traits", "pastey", "rayon", - "thiserror", + "thiserror 2.0.18", "v_frame", "y4m", ] @@ -402,7 +402,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" dependencies = [ "libc", - "windows-sys", + "windows-sys 0.61.2", ] [[package]] @@ -457,6 +457,12 @@ dependencies = [ "miniz_oxide", ] +[[package]] +name = "fnv" +version = "1.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1" + [[package]] name = "foldhash" version = "0.1.5" @@ -587,6 +593,12 @@ version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" +[[package]] +name = "hex" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" + [[package]] name = "hmac-sha256" version = "1.1.14" @@ -801,6 +813,12 @@ dependencies = [ "cc", ] +[[package]] +name = "linux-raw-sys" +version = "0.4.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d26c52dbd32dccf2d10cac7725f8eae5296885fb5703b261f7d0a0739ec807ab" + [[package]] name = "linux-raw-sys" version = "0.12.1" @@ -902,7 +920,7 @@ checksum = "50b7e5b27aa02a74bac8c3f23f448f8d87ff11f92d3aac1a6ed369ee08cc56c1" dependencies = [ "libc", "wasi", - "windows-sys", + "windows-sys 0.61.2", ] [[package]] @@ -1000,7 +1018,7 @@ version = "0.50.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5" dependencies = [ - "windows-sys", + "windows-sys 0.61.2", ] [[package]] @@ -1253,6 +1271,28 @@ dependencies = [ "unicode-ident", ] +[[package]] +name = "procfs" +version = "0.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc5b72d8145275d844d4b5f6d4e1eef00c8cd889edb6035c21675d1bb1f45c9f" +dependencies = [ + "bitflags", + "hex", + "procfs-core", + "rustix 0.38.44", +] + +[[package]] +name = "procfs-core" +version = "0.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "239df02d8349b06fc07398a3a1697b06418223b1c7725085e801e7c0fc6a12ec" +dependencies = [ + "bitflags", + "hex", +] + [[package]] name = "profiling" version = "1.0.18" @@ -1272,6 +1312,43 @@ dependencies = [ "syn", ] +[[package]] +name = "prometheus" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ca5326d8d0b950a9acd87e6a3f94745394f62e4dae1b1ee22b2bc0c394af43a" +dependencies = [ + "cfg-if", + "fnv", + "lazy_static", + "libc", + "memchr", + "parking_lot", + "procfs", + "protobuf", + "thiserror 2.0.18", +] + +[[package]] +name = "protobuf" +version = "3.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d65a1d4ddae7d8b5de68153b48f6aa3bba8cb002b243dbdbc55a5afbc98f99f4" +dependencies = [ + "once_cell", + "protobuf-support", + "thiserror 1.0.69", +] + +[[package]] +name = "protobuf-support" +version = "3.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3e36c2f31e0a47f9280fb347ef5e461ffcd2c52dd520d8e216b52f93b0b0d7d6" +dependencies = [ + "thiserror 1.0.69", +] + [[package]] name = "pxfm" version = "0.1.29" @@ -1373,7 +1450,7 @@ dependencies = [ "rand", "rand_chacha", "simd_helpers", - "thiserror", + "thiserror 2.0.18", "v_frame", "wasm-bindgen", ] @@ -1451,6 +1528,19 @@ version = "0.8.53" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "47b34b781b31e5d73e9fbc8689c70551fd1ade9a19e3e28cfec8580a79290cc4" +[[package]] +name = "rustix" +version = "0.38.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154" +dependencies = [ + "bitflags", + "errno", + "libc", + "linux-raw-sys 0.4.15", + "windows-sys 0.59.0", +] + [[package]] name = "rustix" version = "1.1.4" @@ -1460,8 +1550,8 @@ dependencies = [ "bitflags", "errno", "libc", - "linux-raw-sys", - "windows-sys", + "linux-raw-sys 0.12.1", + "windows-sys 0.61.2", ] [[package]] @@ -1491,7 +1581,7 @@ version = "0.1.29" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "91c1b7e4904c873ef0710c1f407dde2e6287de2bebc1bbbf7d430bb7cbffd939" dependencies = [ - "windows-sys", + "windows-sys 0.61.2", ] [[package]] @@ -1644,7 +1734,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3a766e1110788c36f4fa1c2b71b387a7815aa65f88ce0229841826633d93723e" dependencies = [ "libc", - "windows-sys", + "windows-sys 0.61.2", ] [[package]] @@ -1705,8 +1795,17 @@ dependencies = [ "fastrand", "getrandom 0.4.2", "once_cell", - "rustix", - "windows-sys", + "rustix 1.1.4", + "windows-sys 0.61.2", +] + +[[package]] +name = "thiserror" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52" +dependencies = [ + "thiserror-impl 1.0.69", ] [[package]] @@ -1715,7 +1814,18 @@ version = "2.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4" dependencies = [ - "thiserror-impl", + "thiserror-impl 2.0.18", +] + +[[package]] +name = "thiserror-impl" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1" +dependencies = [ + "proc-macro2", + "quote", + "syn", ] [[package]] @@ -1763,7 +1873,7 @@ dependencies = [ "pin-project-lite", "socket2", "tokio-macros", - "windows-sys", + "windows-sys 0.61.2", ] [[package]] @@ -2090,6 +2200,15 @@ version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" +[[package]] +name = "windows-sys" +version = "0.59.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" +dependencies = [ + "windows-targets", +] + [[package]] name = "windows-sys" version = "0.61.2" @@ -2099,6 +2218,70 @@ dependencies = [ "windows-link", ] +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" +dependencies = [ + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", + "windows_i686_gnullvm", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" + +[[package]] +name = "windows_i686_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" + +[[package]] +name = "windows_i686_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + [[package]] name = "wit-bindgen" version = "0.51.0" @@ -2208,6 +2391,7 @@ dependencies = [ "image", "ndarray", "ort", + "prometheus", "serde", "serde_json", "temp-env", diff --git a/apps/ml-service/Cargo.toml b/apps/ml-service/Cargo.toml index 205c16c..5fbf2d4 100644 --- a/apps/ml-service/Cargo.toml +++ b/apps/ml-service/Cargo.toml @@ -9,6 +9,7 @@ axum = { version = "0.7", features = ["multipart"] } image = "0.25" ndarray = "0.17" ort = { version = "2.0.0-rc.10", features = ["download-binaries", "ndarray"] } +prometheus = { version = "0.14.0", features = ["process"] } serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" tokio = { version = "1.0", features = ["macros", "rt-multi-thread", "net"] } diff --git a/apps/ml-service/Dockerfile b/apps/ml-service/Dockerfile index c982036..78e9fee 100644 --- a/apps/ml-service/Dockerfile +++ b/apps/ml-service/Dockerfile @@ -5,7 +5,7 @@ COPY apps/ml-service/Cargo.toml apps/ml-service/Cargo.lock ./ COPY apps/ml-service/src ./src RUN cargo build --locked --release -FROM debian:trixie-slim AS runner +FROM archlinux:latest AS runner WORKDIR /app ENV MODEL_PATH=/app/model/model.onnx @@ -14,9 +14,7 @@ ENV ML_SERVICE_HOST=0.0.0.0 ENV ML_SERVICE_PORT=8000 ENV RUST_LOG=info -RUN apt-get update \ - && apt-get install -y --no-install-recommends ca-certificates \ - && rm -rf /var/lib/apt/lists/* +RUN pacman -Syu --noconfirm ca-certificates 2>/dev/null COPY --from=builder /app/target/release/zeavis-ml-service /usr/local/bin/zeavis-ml-service COPY Machine_Learning/model/model.onnx /app/model/model.onnx diff --git a/apps/ml-service/src/main.rs b/apps/ml-service/src/main.rs index 7621cfa..01dc3a1 100644 --- a/apps/ml-service/src/main.rs +++ b/apps/ml-service/src/main.rs @@ -3,6 +3,7 @@ mod error; mod image; mod model; mod routes; +mod telemetry; use anyhow::Result; use config::Config; @@ -32,6 +33,9 @@ async fn main() -> Result<()> { "Model service initialized" ); + // Set model load status metric + telemetry::model_load_status().set(if model.is_loaded() { 1.0 } else { 0.0 }); + // Create AppState let state = AppState { model }; diff --git a/apps/ml-service/src/routes.rs b/apps/ml-service/src/routes.rs index 2fe5165..edd9033 100644 --- a/apps/ml-service/src/routes.rs +++ b/apps/ml-service/src/routes.rs @@ -3,6 +3,8 @@ use crate::config::{LABELS, SERVICE_NAME, SERVICE_VERSION}; use crate::model::{ModelService, Prediction}; use crate::error::ServiceError; use crate::image::preprocess_image; +use crate::telemetry; +use crate::telemetry::RequestMetricsGuard; use axum::{ extract::{State, Multipart}, routing::{get, post}, @@ -64,22 +66,34 @@ pub fn prediction_response(prediction: Prediction) -> PredictionResponse { } } +pub async fn metrics() -> (axum::http::StatusCode, String) { + (axum::http::StatusCode::OK, telemetry::encode_metrics()) +} + pub async fn health(State(state): State) -> Json { - Json(health_response(state.model.is_loaded())) + let _guard = RequestMetricsGuard::new(); + let res = health_response(state.model.is_loaded()); + _guard.finish(); + Json(res) } pub async fn metadata(State(state): State) -> Json { - Json(metadata_response( + let _guard = RequestMetricsGuard::new(); + let res = metadata_response( state.model.model_path().to_string_lossy().to_string(), state.model.is_loaded(), state.model.input_size(), - )) + ); + _guard.finish(); + Json(res) } pub async fn predict( State(state): State, mut multipart: Multipart, ) -> Result, ServiceError> { + let _guard = RequestMetricsGuard::new(); + // Extract the file field from multipart let mut file_data = None; while let Ok(Some(field)) = multipart.next_field().await { @@ -121,6 +135,10 @@ pub async fn predict( // Run prediction let prediction = state.model.predict(input)?; + // Record business and request telemetry + telemetry::predictions_total().inc(); + _guard.finish(); + Ok(Json(prediction_response(prediction))) } @@ -129,6 +147,7 @@ pub fn router(state: AppState) -> Router { .route("/health", get(health)) .route("/metadata", get(metadata)) .route("/predict", post(predict)) + .route("/metrics", get(metrics)) .with_state(state) } diff --git a/apps/ml-service/src/telemetry.rs b/apps/ml-service/src/telemetry.rs new file mode 100644 index 0000000..6a08d15 --- /dev/null +++ b/apps/ml-service/src/telemetry.rs @@ -0,0 +1,118 @@ +use prometheus::{Counter, Gauge, Histogram, HistogramOpts, Registry, TextEncoder}; +use std::sync::OnceLock; +use std::time::Instant; + +fn global_registry() -> &'static Registry { + static REGISTRY: OnceLock = OnceLock::new(); + REGISTRY.get_or_init(|| { + Registry::new_custom(Some("zeavis_ml".to_string()), None).expect("create registry") + }) +} + +macro_rules! define_metric { + ($name:ident, $ty:ty, $init:expr) => { + pub fn $name() -> &'static $ty { + static METRIC: OnceLock<$ty> = OnceLock::new(); + METRIC.get_or_init(|| { + let m = $init; + global_registry() + .register(Box::new(m.clone())) + .expect(concat!("register ", stringify!($name))); + m + }) + } + }; +} + +// ── HTTP Metrics ──────────────────────────────────────── + +define_metric!( + http_requests_total, + Counter, + Counter::new("zeavis_ml_http_requests_total", "Total number of HTTP requests") + .expect("create counter") +); + +define_metric!( + http_request_duration_seconds, + Histogram, + Histogram::with_opts( + HistogramOpts::new( + "zeavis_ml_http_request_duration_seconds", + "HTTP request duration in seconds", + ) + .buckets(vec![0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0]), + ) + .expect("create histogram") +); + +define_metric!( + http_requests_active, + Gauge, + Gauge::new( + "zeavis_ml_http_requests_active", + "Number of active HTTP requests", + ) + .expect("create gauge") +); + +// ── Business Metrics ──────────────────────────────────── + +define_metric!( + predictions_total, + Counter, + Counter::new( + "zeavis_ml_predictions_total", + "Total number of prediction requests", + ) + .expect("create counter") +); + +define_metric!( + model_load_status, + Gauge, + Gauge::new( + "zeavis_ml_model_load_status", + "Model load status (1 = loaded, 0 = not loaded)", + ) + .expect("create gauge") +); + +// ── Request Guard (Drop-based cleanup for active gauge) ─ + +pub struct RequestMetricsGuard { + start: Instant, +} + +impl RequestMetricsGuard { + pub fn new() -> Self { + http_requests_active().inc(); + Self { + start: Instant::now(), + } + } + + /// Record duration and request count before the guard drops. + pub fn finish(&self) { + http_request_duration_seconds().observe(self.start.elapsed().as_secs_f64()); + http_requests_total().inc(); + } +} + +impl Drop for RequestMetricsGuard { + fn drop(&mut self) { + http_requests_active().dec(); + } +} + +// ── Export ────────────────────────────────────────────── + +pub fn encode_metrics() -> String { + let encoder = TextEncoder::new(); + let mut buffer = String::new(); + let metric_families = global_registry().gather(); + encoder + .encode_utf8(&metric_families, &mut buffer) + .unwrap(); + buffer +} diff --git a/apps/web/.gitignore b/apps/web/.gitignore new file mode 100644 index 0000000..34fee9f --- /dev/null +++ b/apps/web/.gitignore @@ -0,0 +1,4 @@ + +.claude/ + +.codegraph/ diff --git a/apps/web/nginx.conf b/apps/web/nginx.conf index d15888c..11bce60 100644 --- a/apps/web/nginx.conf +++ b/apps/web/nginx.conf @@ -12,6 +12,15 @@ server { proxy_set_header X-Forwarded-Proto $scheme; } + # Expose API metrics through the web endpoint (Prometheus scrape target) + location /metrics { + proxy_pass http://zeavis-api:3000/metrics; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + location / { try_files $uri $uri/ /index.html; } diff --git a/apps/web/package.json b/apps/web/package.json index 51a996d..7df9fac 100644 --- a/apps/web/package.json +++ b/apps/web/package.json @@ -21,6 +21,7 @@ "react-dom": "^19.2.6", "react-router-dom": "^7.15.1", "tailwind-merge": "^3.6.0", + "web-vitals": "5.3.0", "zustand": "^5.0.13" }, "devDependencies": { diff --git a/apps/web/src/app.tsx b/apps/web/src/app.tsx index 93b7301..d3cfce9 100644 --- a/apps/web/src/app.tsx +++ b/apps/web/src/app.tsx @@ -1,3 +1,4 @@ +import { useEffect } from "react"; import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; import { createBrowserRouter, @@ -5,7 +6,6 @@ import { Navigate, } from "react-router-dom"; import { AuthInitializer } from "@/components/auth-initializer"; -// import { AuthGuard } from "@/components/auth-guard"; import { DashboardPage } from "@/pages/dashboard-page"; import { ScanPage } from "@/pages/scan-page"; import { LibraryPage } from "@/pages/library-page"; @@ -14,16 +14,13 @@ import { DiseaseDetailPage } from "@/pages/disease-detail-page"; import { DiagnosisDetailPage } from "@/pages/diagnosis-detail-page"; import { ExpertReviewsPage } from "@/pages/expert-reviews-page"; import { DiagnosesPage } from "@/pages/diagnoses-page"; -// import { LoginPage } from "@/pages/login-page"; -// import { RegisterPage } from "@/pages/register-page"; import { MainLayout } from "@/components/layout/main-layout"; +import { trackPageView } from "./lib/telemetry"; const queryClient = new QueryClient(); const router = createBrowserRouter([ { path: "/", element: }, - // { path: "/login", element: }, - // { path: "/register", element: }, { path: "/dashboard", element: ( @@ -90,10 +87,19 @@ const router = createBrowserRouter([ }, ]); +function PageViewTracker() { + const location = window.location; + useEffect(() => { + trackPageView(location.pathname + location.search); + }, [location.pathname, location.search]); + return null; +} + export function App() { return ( + ); diff --git a/apps/web/src/lib/telemetry.ts b/apps/web/src/lib/telemetry.ts new file mode 100644 index 0000000..46f3255 --- /dev/null +++ b/apps/web/src/lib/telemetry.ts @@ -0,0 +1,52 @@ +/** + * Client‑side telemetry for the ZeaVis Edu web app. + * + * In development, metrics are collected in‑memory and exposed at /metrics + * via a Vite plugin. In production they are sent as HTTP beacons to the + * Telemetry pipeline (see METRICS.md). + */ + +// ── Web Vitals ────────────────────────────────────────── + +export type MetricEntry = { + name: string; + value: number; + rating?: string; +}; + +const vitalsBuffer: MetricEntry[] = []; + +export function reportWebVitals(metric: MetricEntry): void { + vitalsBuffer.push(metric); + // Keep last 20 entries in memory for the /metrics endpoint + if (vitalsBuffer.length > 20) vitalsBuffer.shift(); + console.debug(`[telemetry] ${metric.name}: ${metric.value} (${metric.rating ?? 'n/a'})`); +} + +// ── Page‑view counter ─────────────────────────────────── + +let pageViewCount = 0; + +export function trackPageView(path: string): void { + pageViewCount++; + console.debug(`[telemetry] pageview: ${path} (total: ${pageViewCount})`); +} + +// ── Metrics serialisation (consumed by vite‑plugin) ──── + +export function collectMetrics(): string { + const lines: string[] = []; + + // ── Default process‑like metrics ────────────────────── + lines.push('# HELP zeavis_web_page_views_total Total page views'); + lines.push('# TYPE zeavis_web_page_views_total counter'); + lines.push(`zeavis_web_page_views_total ${pageViewCount}`); + + lines.push('# HELP zeavis_web_vital_bucket Web Vitals observed this session'); + lines.push('# TYPE zeavis_web_vital_bucket gauge'); + for (const v of vitalsBuffer) { + lines.push(`zeavis_web_vital_bucket{name="${v.name}",rating="${v.rating ?? 'unknown'}"} ${v.value}`); + } + + return lines.join('\n') + '\n'; +} diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx index e869dfb..9789fcf 100644 --- a/apps/web/src/main.tsx +++ b/apps/web/src/main.tsx @@ -2,6 +2,15 @@ import React from "react"; import ReactDOM from "react-dom/client"; import { App } from "./app"; import "./index.css"; +import { reportWebVitals } from "./lib/telemetry"; +import { onCLS, onFCP, onINP, onLCP, onTTFB } from "web-vitals"; + +// Report Web Vitals to our in-memory telemetry store +onCLS((m) => reportWebVitals({ name: "CLS", value: m.value, rating: m.rating })); +onFCP((m) => reportWebVitals({ name: "FCP", value: m.value, rating: m.rating })); +onINP((m) => reportWebVitals({ name: "INP", value: m.value, rating: m.rating })); +onLCP((m) => reportWebVitals({ name: "LCP", value: m.value, rating: m.rating })); +onTTFB((m) => reportWebVitals({ name: "TTFB", value: m.value, rating: m.rating })); ReactDOM.createRoot(document.getElementById("root")!).render( diff --git a/apps/web/tsconfig.node.json b/apps/web/tsconfig.node.json index 8237f41..6bd2998 100644 --- a/apps/web/tsconfig.node.json +++ b/apps/web/tsconfig.node.json @@ -7,5 +7,5 @@ "moduleResolution": "Bundler", "types": ["node"] }, - "include": ["vite.config.ts", "tailwind.config.ts"] + "include": ["vite.config.ts", "tailwind.config.ts", "vite-plugin-metrics.ts"] } diff --git a/apps/web/vite-plugin-metrics.ts b/apps/web/vite-plugin-metrics.ts new file mode 100644 index 0000000..f157233 --- /dev/null +++ b/apps/web/vite-plugin-metrics.ts @@ -0,0 +1,42 @@ +import type { Plugin } from 'vite'; + +/** + * Vite plugin that exposes a /metrics endpoint during development. + * + * The endpoint returns Prometheus‑text metrics collected in + * src/lib/telemetry.ts. + */ +export function metricsPlugin(): Plugin { + let telemetryModule: typeof import('./src/lib/telemetry') | null = null; + + return { + name: 'zeavis-metrics', + + configureServer(server) { + server.middlewares.use(async (req, res, next) => { + // Only handle GET /metrics + if (req.method !== 'GET' || !req.url?.startsWith('/metrics')) { + return next(); + } + + // Lazy‑load the telemetry module (ensures the app is bootstrapped first) + if (!telemetryModule) { + try { + telemetryModule = await server.ssrLoadModule('./src/lib/telemetry.ts') as typeof import('./src/lib/telemetry'); + } catch { + // If the module isn't ready yet, return an empty body + res.statusCode = 200; + res.setHeader('Content-Type', 'text/plain; charset=utf-8'); + res.end('# telemetry module not yet loaded\n'); + return; + } + } + + const body = telemetryModule.collectMetrics(); + res.statusCode = 200; + res.setHeader('Content-Type', 'text/plain; charset=utf-8'); + res.end(body); + }); + }, + }; +} diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts index 08b0a15..b596289 100644 --- a/apps/web/vite.config.ts +++ b/apps/web/vite.config.ts @@ -2,13 +2,14 @@ import react from '@vitejs/plugin-react'; import tsconfigPaths from 'vite-tsconfig-paths'; import path from 'node:path'; import { defineConfig, loadEnv } from 'vite'; +import { metricsPlugin } from './vite-plugin-metrics'; export default defineConfig(({ mode }) => { const env = loadEnv(mode, process.cwd(), ''); const apiProxyTarget = env.VITE_API_PROXY_TARGET || 'http://localhost:3000'; return { - plugins: [react(), tsconfigPaths()], + plugins: [react(), tsconfigPaths(), metricsPlugin()], server: { proxy: { '/api': apiProxyTarget, diff --git a/docker-compose.telemetry.yml b/docker-compose.telemetry.yml new file mode 100644 index 0000000..62e1b8e --- /dev/null +++ b/docker-compose.telemetry.yml @@ -0,0 +1,28 @@ +# ============================================================================= +# ZeaVis Edu — Telemetry Stack Integration (LOCAL DEV ONLY) +# +# This override connects the Telemetry submodule docker-compose to the same +# Docker network as ZeaVis Edu services for LOCAL development on a single host. +# +# In PRODUCTION, the app and telemetry run on separate VPS instances +# connected via Tailscale. See telemetry/prometheus/targets/zeavis-edu.json +# for the Tailscale IP configuration. +# +# Usage (local dev only): +# # Ensure app-shared-net exists first: +# docker network create app-shared-net +# +# # Start telemetry with app network access: +# make telemetry-up-local +# ============================================================================= + +networks: + app-shared-net: + external: true + name: app-shared-net + +services: + prometheus: + networks: + - default + - app-shared-net diff --git a/docker-compose.yml b/docker-compose.yml index 699f03f..6dfb16f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -2,6 +2,9 @@ networks: app-shared-net: external: true name: app-shared-net + telemetry-net: + external: true + name: telemetry-net services: web: @@ -10,6 +13,7 @@ services: restart: always networks: - app-shared-net + - telemetry-net env_file: - .env labels: @@ -26,6 +30,7 @@ services: restart: always networks: - app-shared-net + - telemetry-net env_file: - .env environment: @@ -33,6 +38,8 @@ services: API_PORT: "3000" WEB_APP_URL: https://zeavisedu.asepharyana.my.id ML_SERVICE_URL: ${ML_SERVICE_URL:-http://zeavis-ml:8000} + ports: + - "3000:3000" labels: traefik.enable: "true" traefik.http.routers.zeavis-api.rule: Host(`api-zeavisedu.asepharyana.my.id`) @@ -47,11 +54,14 @@ services: restart: always networks: - app-shared-net + - telemetry-net env_file: - .env environment: MODEL_PATH: /app/model/model.onnx MODEL_INPUT_SIZE: "224" + ports: + - "8000:8000" labels: traefik.enable: "true" traefik.http.routers.zeavis-ml.rule: Host(`ml-zeavisedu.asepharyana.my.id`) diff --git a/telemetry b/telemetry new file mode 160000 index 0000000..723693b --- /dev/null +++ b/telemetry @@ -0,0 +1 @@ +Subproject commit 723693b83241a35e0c09437e041fe6d5b391f87c