Merge pull request #24 from MythEclipse/main

feat/metrics
2026-06-07 21:44:41 +07:00
parent c1fc244c73 1106cbf62f
commit 791273ce35
35 changed files with 1117 additions and 29 deletions
@@ -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
@@ -11,3 +11,5 @@ coverage/
 *.tsbuildinfo

 .DS_Store
+
+.claude/
@@ -0,0 +1,3 @@
+[submodule "telemetry"]
+	path = telemetry
+	url = https://github.com/MythEclipse/Telemetry.git
@@ -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=<service>]
+
+# 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:
@@ -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.
@@ -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=<name>)
+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=<service-name>"
+	@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."
@@ -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<br/>api-zeavisedu.asepharyana.id]
+        A[API / Elysia<br/>:3000]
+        M[ML Service / Axum<br/>:8000]
+    end
+
+    subgraph VPS2["VPS — Telemetry Stack"]
+        P[Prometheus<br/>:9090]
+        MI[Metric Ingester<br/>:9091]
+        V[Vector<br/>:9001]
+        CH[ClickHouse<br/>:8123]
+        QP[Query Proxy<br/>:9092]
+        TUI[Telemetry UI<br/>:8181]
+    end
+
+    P -.->|"scrape via Tailscale IP<br/>100.x.x.a:3000/metrics"| A
+    P -.->|"scrape via Tailscale IP<br/>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:
@@ -0,0 +1,4 @@
+
+.claude/
+
+.codegraph/
@@ -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",
@@ -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)
@@ -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<string> {
+  return await registry.metrics();
+}
@@ -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,
@@ -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 {
@@ -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;
    }
  })
@@ -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() },
+    });
+  });
@@ -0,0 +1,8 @@
+declare global {
+  interface Request {
+    metricsStart?: number;
+    metricsPath?: string;
+  }
+}
+
+export {};
@@ -1,3 +1,6 @@
 .venv/
 __pycache__/
-target/
+target/
+.claude/
+
+.codegraph/
@@ -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",
@@ -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"] }
@@ -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
@@ -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 };

@@ -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<AppState>) -> Json<HealthResponse> {
-    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<AppState>) -> Json<MetadataResponse> {
-    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<AppState>,
    mut multipart: Multipart,
 ) -> Result<Json<PredictionResponse>, 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)
 }

@@ -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<Registry> = 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
+}
@@ -0,0 +1,4 @@
+
+.claude/
+
+.codegraph/
@@ -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;
  }
@@ -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": {
@@ -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: <Navigate to="/dashboard" replace /> },
-  // { path: "/login", element: <LoginPage /> },
-  // { path: "/register", element: <RegisterPage /> },
  {
    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 (
    <QueryClientProvider client={queryClient}>
      <AuthInitializer />
+      <PageViewTracker />
      <RouterProvider router={router} />
    </QueryClientProvider>
  );
@@ -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';
+}
@@ -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(
  <React.StrictMode>
@@ -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"]
 }
@@ -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);
+      });
+    },
+  };
+}
@@ -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,
@@ -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
@@ -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`)