add prometheus metrics

8 files changed, 1244 insertions, 7 deletions

diff --git a/src/config.rs b/src/config.rs
index d095178..025e020 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -71,6 +71,18 @@ pub struct Config {
     /// Database backend type
     #[arg(long, env = "NGIT_DATABASE_BACKEND", value_enum, default_value_t = DatabaseBackend::Lmdb)]
     pub database_backend: DatabaseBackend,
+
+    /// Enable Prometheus metrics endpoint
+    #[arg(long, env = "NGIT_METRICS_ENABLED", default_value_t = true)]
+    pub metrics_enabled: bool,
+
+    /// Connections per IP before flagging as potential abuse in metrics (display only, no rate limiting)
+    #[arg(long = "metrics-connection-per-ip-abuse-threshold", env = "NGIT_METRICS_CONNECTION_PER_IP_ABUSE_THRESHOLD", default_value_t = 10)]
+    pub metrics_connection_per_ip_abuse_threshold: u32,
+
+    /// Number of top bandwidth repos to track in metrics
+    #[arg(long = "metrics-top-n-repos", env = "NGIT_METRICS_TOP_N_REPOS", default_value_t = 10)]
+    pub metrics_top_n_repos: usize,
 }
 
 impl Config {
@@ -123,6 +135,9 @@ impl Config {
             relay_data_path: "./test_data/relay".to_string(),
             bind_address: "127.0.0.1:8080".to_string(),
             database_backend: DatabaseBackend::Memory,
+            metrics_enabled: true,
+            metrics_connection_per_ip_abuse_threshold: 10,
+            metrics_top_n_repos: 10,
         }
     }
 }
@@ -202,4 +217,25 @@ mod tests {
         };
         assert!(config.owner_npub.is_none());
     }
+
+    #[test]
+    fn test_metrics_config_defaults() {
+        let config = Config::for_testing();
+        assert!(config.metrics_enabled);
+        assert_eq!(config.metrics_connection_per_ip_abuse_threshold, 10);
+        assert_eq!(config.metrics_top_n_repos, 10);
+    }
+
+    #[test]
+    fn test_metrics_config_custom_values() {
+        let config = Config {
+            metrics_enabled: false,
+            metrics_connection_per_ip_abuse_threshold: 50,
+            metrics_top_n_repos: 25,
+            ..Config::for_testing()
+        };
+        assert!(!config.metrics_enabled);
+        assert_eq!(config.metrics_connection_per_ip_abuse_threshold, 50);
+        assert_eq!(config.metrics_top_n_repos, 25);
+    }
 }
diff --git a/src/http/mod.rs b/src/http/mod.rs
index 8b1f687..f584e03 100644
--- a/src/http/mod.rs
+++ b/src/http/mod.rs
@@ -7,6 +7,7 @@ pub mod nip11;
 use std::future::Future;
 use std::net::SocketAddr;
 use std::pin::Pin;
+use std::sync::Arc;
 
 use base64::Engine;
 use http_body_util::{BodyExt, Full};
@@ -24,6 +25,7 @@ use tokio::net::TcpListener;
 
 use crate::config::Config;
 use crate::git;
+use crate::metrics::Metrics;
 use crate::nostr::builder::SharedDatabase;
 
 /// CORS headers required by GRASP-01 specification (lines 40-47)
@@ -90,6 +92,8 @@ struct HttpService {
     remote: SocketAddr,
     /// Database reference for direct queries (e.g., push authorization)
     database: SharedDatabase,
+    /// Optional metrics for Prometheus endpoint
+    metrics: Option<Arc<Metrics>>,
 }
 
 impl HttpService {
@@ -98,12 +102,14 @@ impl HttpService {
         config: Config,
         remote: SocketAddr,
         database: SharedDatabase,
+        metrics: Option<Arc<Metrics>>,
     ) -> Self {
         Self {
             relay,
             config,
             remote,
             database,
+            metrics,
         }
     }
 }
@@ -150,6 +156,7 @@ impl Service<Request<Incoming>> for HttpService {
             );
 
             let repo_path = git::resolve_repo_path(&git_data_path, &npub, &identifier);
+            let metrics_clone = self.metrics.clone();
 
             return Box::pin(async move {
                 // Collect request body once before the match statement
@@ -170,14 +177,31 @@ impl Service<Request<Incoming>> for HttpService {
                             .and_then(git::protocol::GitService::from_query_param);
 
                         match service {
-                            Some(svc) => git::handlers::handle_info_refs(repo_path, svc).await,
+                            Some(svc) => {
+                                let result = git::handlers::handle_info_refs(repo_path, svc).await;
+                                // Track operation
+                                if let Some(ref m) = metrics_clone {
+                                    let status = if result.is_ok() { "success" } else { "error" };
+                                    let operation = match svc {
+                                        git::protocol::GitService::UploadPack => "fetch",
+                                        git::protocol::GitService::ReceivePack => "push",
+                                    };
+                                    m.record_git_operation(operation, status);
+                                }
+                                result
+                            }
                             None => Err(git::handlers::GitError::RepositoryNotFound),
                         }
                     }
 
                     // POST /git-upload-pack (clone/fetch)
                     (m, "git-upload-pack") if m == Method::POST => {
-                        git::handlers::handle_upload_pack(repo_path, body_bytes).await
+                        let result = git::handlers::handle_upload_pack(repo_path, body_bytes).await;
+                        if let Some(ref m) = metrics_clone {
+                            let status = if result.is_ok() { "success" } else { "error" };
+                            m.record_git_operation("clone", status);
+                        }
+                        result
                     }
 
                     // POST /git-receive-pack (push) - with GRASP authorization via database
@@ -187,6 +211,10 @@ impl Service<Request<Incoming>> for HttpService {
                             Ok(pk) => pk.to_hex(),
                             Err(e) => {
                                 tracing::warn!("Invalid npub in URL {}: {}", npub, e);
+                                // Track failed push due to invalid npub
+                                if let Some(ref m) = metrics_clone {
+                                    m.record_git_operation("push", "error");
+                                }
                                 return Ok(add_cors_headers(Response::builder())
                                     .status(hyper::StatusCode::BAD_REQUEST)
                                     .body(Full::new(Bytes::from(format!("Invalid npub: {}", e))))
@@ -194,14 +222,21 @@ impl Service<Request<Incoming>> for HttpService {
                             }
                         };
 
-                        git::handlers::handle_receive_pack(
+                        let result = git::handlers::handle_receive_pack(
                             repo_path,
                             body_bytes.clone(),
                             Some(database.clone()),
                             &identifier,
                             &owner_pubkey_hex,
                         )
-                        .await
+                        .await;
+
+                        if let Some(ref m) = metrics_clone {
+                            let status = if result.is_ok() { "success" } else { "error" };
+                            m.record_git_operation("push", status);
+                        }
+
+                        result
                     }
 
                     _ => Err(git::handlers::GitError::RepositoryNotFound),
@@ -333,17 +368,27 @@ impl Service<Request<Incoming>> for HttpService {
 
                 let addr = self.remote;
                 let relay = self.relay.clone();
+                let metrics_clone = self.metrics.clone();
 
                 tokio::spawn(async move {
                     match hyper::upgrade::on(req).await {
                         Ok(upgraded) => {
                             tracing::info!("WebSocket connection established from {}", addr);
+                            // Track connection
+                            if let Some(ref m) = metrics_clone {
+                                m.connection_tracker().on_connect(addr.ip());
+                                m.record_websocket_connection();
+                            }
                             if let Err(e) =
                                 relay.take_connection(TokioIo::new(upgraded), addr).await
                             {
                                 tracing::error!("Relay error for {}: {}", addr, e);
                             }
                             tracing::info!("WebSocket connection closed for {}", addr);
+                            // Untrack connection
+                            if let Some(ref m) = metrics_clone {
+                                m.connection_tracker().on_disconnect(addr.ip());
+                            }
                         }
                         Err(e) => tracing::error!("Upgrade error: {}", e),
                     }
@@ -361,6 +406,33 @@ impl Service<Request<Incoming>> for HttpService {
             }
         }
 
+        // Serve Prometheus metrics if enabled
+        if path == "/metrics" {
+            if let Some(ref metrics) = self.metrics {
+                let metrics = metrics.clone();
+                return Box::pin(async move {
+                    let output = metrics.render();
+                    Ok(
+                        add_cors_headers(Response::builder().header("server", "ngit-grasp"))
+                            .status(200)
+                            .header("content-type", "text/plain; version=0.0.4; charset=utf-8")
+                            .body(Full::new(Bytes::from(output)))
+                            .unwrap(),
+                    )
+                });
+            } else {
+                // Metrics disabled
+                return Box::pin(async move {
+                    Ok(
+                        add_cors_headers(Response::builder().header("server", "ngit-grasp"))
+                            .status(404)
+                            .body(Full::new(Bytes::from("Metrics disabled")))
+                            .unwrap(),
+                    )
+                });
+            }
+        }
+
         // Serve static icon at /icon.png
         if path == "/icon.png" {
             return Box::pin(async move {
@@ -419,10 +491,12 @@ fn derive_accept_key(request_key: &[u8]) -> String {
 /// * `config` - Server configuration
 /// * `relay` - The LocalRelay for WebSocket connections
 /// * `database` - The database for direct queries (e.g., push authorization)
+/// * `metrics` - Optional metrics for Prometheus endpoint
 pub async fn run_server(
     config: Config,
     relay: LocalRelay,
     database: SharedDatabase,
+    metrics: Option<Arc<Metrics>>,
 ) -> anyhow::Result<()> {
     let bind_addr: SocketAddr = config.bind_address.parse()?;
 
@@ -435,7 +509,7 @@ pub async fn run_server(
     loop {
         let (socket, addr) = listener.accept().await?;
         let io = TokioIo::new(socket);
-        let service = HttpService::new(relay.clone(), config.clone(), addr, database.clone());
+        let service = HttpService::new(relay.clone(), config.clone(), addr, database.clone(), metrics.clone());
 
         tokio::spawn(async move {
             if let Err(e) = http1::Builder::new()
diff --git a/src/http/nip11.rs b/src/http/nip11.rs
index 1ed80de..1723601 100644
--- a/src/http/nip11.rs
+++ b/src/http/nip11.rs
@@ -102,6 +102,9 @@ mod tests {
             relay_data_path: "./data/relay".to_string(),
             bind_address: "127.0.0.1:8080".to_string(),
             database_backend: crate::config::DatabaseBackend::Memory,
+            metrics_enabled: true,
+            metrics_connection_per_ip_abuse_threshold: 10,
+            metrics_top_n_repos: 10,
         };
 
         let doc = RelayInformationDocument::from_config(&config);
@@ -133,6 +136,9 @@ mod tests {
             relay_data_path: "./data/relay".to_string(),
             bind_address: "127.0.0.1:8080".to_string(),
             database_backend: crate::config::DatabaseBackend::Memory,
+            metrics_enabled: true,
+            metrics_connection_per_ip_abuse_threshold: 10,
+            metrics_top_n_repos: 10,
         };
 
         let doc = RelayInformationDocument::from_config(&config);
diff --git a/src/lib.rs b/src/lib.rs
index 9ccc212..4d5aab0 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,4 +1,5 @@
 pub mod config;
 pub mod git;
 pub mod http;
+pub mod metrics;
 pub mod nostr;
diff --git a/src/main.rs b/src/main.rs
index f80e920..9200cc2 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,10 +1,14 @@
+use std::sync::Arc;
+
 use anyhow::Result;
 use tracing::{info, Level};
 use tracing_subscriber::FmtSubscriber;
 
 use ngit_grasp::{
     config::{Config, DatabaseBackend},
-    http, nostr,
+    http,
+    metrics::Metrics,
+    nostr,
 };
 
 #[tokio::main]
@@ -29,6 +33,15 @@ async fn main() -> Result<()> {
     }
     info!("Database backend: {}", config.database_backend);
 
+    // Initialize metrics if enabled
+    let metrics = if config.metrics_enabled {
+        info!("Metrics enabled on /metrics endpoint");
+        Some(Arc::new(Metrics::new(config.metrics_connection_per_ip_abuse_threshold)))
+    } else {
+        info!("Metrics disabled");
+        None
+    };
+
     // Create Nostr relay with NIP-34 validation
     // Returns both the relay and database for direct queries in handlers
     if let Ok(relay_with_db) = nostr::builder::create_relay(&config) {
@@ -39,7 +52,7 @@ async fn main() -> Result<()> {
 
         // Start HTTP server with integrated relay and database
         info!("Starting HTTP server on {}", config.bind_address);
-        http::run_server(config, relay_with_db.relay, relay_with_db.database).await?;
+        http::run_server(config, relay_with_db.relay, relay_with_db.database, metrics).await?;
     }
 
     Ok(())
diff --git a/src/metrics/bandwidth.rs b/src/metrics/bandwidth.rs
new file mode 100644
index 0000000..d2c53e8
--- /dev/null
+++ b/src/metrics/bandwidth.rs
@@ -0,0 +1,301 @@
+//! Repository bandwidth tracking with cardinality control.
+//!
+//! This module tracks bandwidth per repository but only exposes the top N
+//! repositories to Prometheus to prevent cardinality explosion with many repos.
+//!
+//! # Cardinality Control
+//!
+//! - All per-repo bandwidth is tracked internally in a `DashMap<RepoId, u64>`
+//! - Every 60 seconds, the top 10 are calculated and exposed to Prometheus
+//! - Previous repo labels are cleared before setting new ones
+//! - Prometheus only ever sees ~10 label values, keeping cardinality low
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{Duration, Instant};
+
+use dashmap::DashMap;
+use prometheus::{GaugeVec, Opts, Registry};
+
+/// Default number of top repositories to expose in metrics
+const DEFAULT_TOP_N: usize = 10;
+
+/// Default refresh interval for top-N calculation (60 seconds)
+const DEFAULT_REFRESH_INTERVAL: Duration = Duration::from_secs(60);
+
+/// Tracks bandwidth per repository with top-N exposure to Prometheus.
+///
+/// # Design
+///
+/// All repositories are tracked internally for accurate total bandwidth,
+/// but only the top N by bytes transferred are exposed to Prometheus.
+/// This prevents cardinality explosion when hosting thousands of repositories.
+///
+/// # Thread Safety
+///
+/// Uses `DashMap` for lock-free concurrent access and atomics for
+/// the refresh timestamp.
+pub struct BandwidthTracker {
+    /// Internal: tracks ALL repos (memory only, not exposed)
+    all_repos: DashMap<String, u64>,
+
+    /// Exposed to Prometheus: only top N repos
+    top_repos_gauge: GaugeVec,
+
+    /// Last refresh timestamp (stored as nanos since some epoch)
+    last_refresh_nanos: AtomicU64,
+
+    /// Instant when the tracker was created (for relative timing)
+    start_instant: Instant,
+
+    /// Number of top repos to expose
+    top_n: usize,
+
+    /// Refresh interval
+    refresh_interval: Duration,
+}
+
+impl BandwidthTracker {
+    /// Creates a new BandwidthTracker and registers metrics with Prometheus.
+    ///
+    /// Uses default settings:
+    /// - Top 10 repositories exposed
+    /// - 60 second refresh interval
+    pub fn new(registry: &Registry) -> Self {
+        Self::with_config(registry, DEFAULT_TOP_N, DEFAULT_REFRESH_INTERVAL)
+    }
+
+    /// Creates a new BandwidthTracker with custom configuration.
+    ///
+    /// # Arguments
+    ///
+    /// * `registry` - Prometheus registry to register metrics with
+    /// * `top_n` - Number of top repositories to expose in metrics
+    /// * `refresh_interval` - How often to recalculate the top-N list
+    pub fn with_config(registry: &Registry, top_n: usize, refresh_interval: Duration) -> Self {
+        let top_repos_gauge = GaugeVec::new(
+            Opts::new(
+                "ngit_git_top_repos_bytes",
+                "Top repositories by bandwidth (refreshed periodically)",
+            ),
+            &["repo"],
+        )
+        .unwrap();
+        registry.register(Box::new(top_repos_gauge.clone())).unwrap();
+
+        Self {
+            all_repos: DashMap::new(),
+            top_repos_gauge,
+            last_refresh_nanos: AtomicU64::new(0),
+            start_instant: Instant::now(),
+            top_n,
+            refresh_interval,
+        }
+    }
+
+    /// Records bytes transferred for a repository.
+    ///
+    /// # Arguments
+    ///
+    /// * `repo_id` - Repository identifier (e.g., npub or repo name)
+    /// * `bytes` - Number of bytes transferred
+    pub fn record_transfer(&self, repo_id: &str, bytes: u64) {
+        self.all_repos
+            .entry(repo_id.to_string())
+            .and_modify(|v| *v = v.saturating_add(bytes))
+            .or_insert(bytes);
+    }
+
+    /// Conditionally refreshes the top-N list if the refresh interval has elapsed.
+    ///
+    /// This method is designed to be called frequently (e.g., on every
+    /// `/metrics` request) without performance impact - it only does work
+    /// when the refresh interval has elapsed.
+    pub fn maybe_refresh_top_n(&self) {
+        let elapsed_nanos = self.start_instant.elapsed().as_nanos() as u64;
+        let last_refresh = self.last_refresh_nanos.load(Ordering::Relaxed);
+        let interval_nanos = self.refresh_interval.as_nanos() as u64;
+
+        // Check if enough time has passed since last refresh
+        if elapsed_nanos.saturating_sub(last_refresh) >= interval_nanos {
+            // Try to update the timestamp atomically to prevent concurrent refreshes
+            if self
+                .last_refresh_nanos
+                .compare_exchange(last_refresh, elapsed_nanos, Ordering::SeqCst, Ordering::Relaxed)
+                .is_ok()
+            {
+                self.refresh_top_n();
+            }
+        }
+    }
+
+    /// Forces a refresh of the top-N list.
+    ///
+    /// This recalculates which repositories are in the top N by bandwidth
+    /// and updates the Prometheus gauges accordingly.
+    pub fn refresh_top_n(&self) {
+        // Collect all repo data
+        let mut sorted: Vec<_> = self
+            .all_repos
+            .iter()
+            .map(|r| (r.key().clone(), *r.value()))
+            .collect();
+
+        // Sort by bytes descending
+        sorted.sort_by(|a, b| b.1.cmp(&a.1));
+
+        // Clear old labels and set new top N
+        self.top_repos_gauge.reset();
+        for (repo, bytes) in sorted.into_iter().take(self.top_n) {
+            self.top_repos_gauge
+                .with_label_values(&[&repo])
+                .set(bytes as f64);
+        }
+    }
+
+    /// Returns the total bytes transferred for a specific repository.
+    ///
+    /// Returns `None` if the repository has not been seen.
+    pub fn get_repo_bytes(&self, repo_id: &str) -> Option<u64> {
+        self.all_repos.get(repo_id).map(|v| *v)
+    }
+
+    /// Returns the total bytes transferred across all repositories.
+    pub fn total_bytes(&self) -> u64 {
+        self.all_repos.iter().map(|r| *r.value()).sum()
+    }
+
+    /// Returns the number of repositories being tracked.
+    pub fn repo_count(&self) -> usize {
+        self.all_repos.len()
+    }
+
+    /// Returns the top N repositories by bandwidth.
+    ///
+    /// This is a snapshot and may not match the Prometheus gauges if
+    /// a refresh hasn't occurred recently.
+    pub fn get_top_repos(&self) -> Vec<(String, u64)> {
+        let mut sorted: Vec<_> = self
+            .all_repos
+            .iter()
+            .map(|r| (r.key().clone(), *r.value()))
+            .collect();
+
+        sorted.sort_by(|a, b| b.1.cmp(&a.1));
+        sorted.truncate(self.top_n);
+        sorted
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn test_registry() -> Registry {
+        Registry::new()
+    }
+
+    #[test]
+    fn test_bandwidth_tracking() {
+        let registry = test_registry();
+        let tracker = BandwidthTracker::new(&registry);
+
+        // Record transfers
+        tracker.record_transfer("repo-a", 1000);
+        tracker.record_transfer("repo-b", 2000);
+        tracker.record_transfer("repo-a", 500); // Additional transfer to repo-a
+
+        assert_eq!(tracker.get_repo_bytes("repo-a"), Some(1500));
+        assert_eq!(tracker.get_repo_bytes("repo-b"), Some(2000));
+        assert_eq!(tracker.get_repo_bytes("repo-c"), None);
+        assert_eq!(tracker.total_bytes(), 3500);
+        assert_eq!(tracker.repo_count(), 2);
+    }
+
+    #[test]
+    fn test_top_n_repos() {
+        let registry = test_registry();
+        let tracker = BandwidthTracker::with_config(&registry, 3, Duration::from_secs(60));
+
+        // Create 5 repos with different bandwidth
+        tracker.record_transfer("repo-1", 100);
+        tracker.record_transfer("repo-2", 500);
+        tracker.record_transfer("repo-3", 200);
+        tracker.record_transfer("repo-4", 800);
+        tracker.record_transfer("repo-5", 300);
+
+        let top = tracker.get_top_repos();
+        assert_eq!(top.len(), 3);
+        assert_eq!(top[0], ("repo-4".to_string(), 800));
+        assert_eq!(top[1], ("repo-2".to_string(), 500));
+        assert_eq!(top[2], ("repo-5".to_string(), 300));
+    }
+
+    #[test]
+    fn test_refresh_updates_gauge() {
+        let registry = test_registry();
+        let tracker = BandwidthTracker::new(&registry);
+
+        tracker.record_transfer("high-bandwidth-repo", 10_000_000);
+        tracker.record_transfer("low-bandwidth-repo", 1000);
+
+        // Force a refresh
+        tracker.refresh_top_n();
+
+        // Verify the gauge values (we can't easily access them directly,
+        // but we can verify the tracker state is correct)
+        assert_eq!(tracker.repo_count(), 2);
+        assert_eq!(tracker.total_bytes(), 10_001_000);
+    }
+
+    #[test]
+    fn test_saturating_add() {
+        let registry = test_registry();
+        let tracker = BandwidthTracker::new(&registry);
+
+        // Test that we don't overflow
+        tracker.record_transfer("huge-repo", u64::MAX - 100);
+        tracker.record_transfer("huge-repo", 200);
+
+        // Should saturate to MAX, not overflow
+        assert_eq!(tracker.get_repo_bytes("huge-repo"), Some(u64::MAX));
+    }
+
+    #[test]
+    fn test_maybe_refresh_respects_interval() {
+        let registry = test_registry();
+        // Use a very short interval for testing
+        let tracker = BandwidthTracker::with_config(&registry, 10, Duration::from_millis(10));
+
+        tracker.record_transfer("repo-a", 1000);
+
+        // First call should trigger refresh (no previous refresh)
+        tracker.maybe_refresh_top_n();
+
+        // Add more data
+        tracker.record_transfer("repo-b", 2000);
+
+        // Immediate second call should NOT trigger refresh
+        let count_before = tracker.repo_count();
+        tracker.maybe_refresh_top_n();
+        assert_eq!(tracker.repo_count(), count_before);
+
+        // Wait for interval to pass
+        std::thread::sleep(Duration::from_millis(15));
+
+        // Now it should refresh
+        tracker.maybe_refresh_top_n();
+    }
+
+    #[test]
+    fn test_empty_tracker() {
+        let registry = test_registry();
+        let tracker = BandwidthTracker::new(&registry);
+
+        assert_eq!(tracker.total_bytes(), 0);
+        assert_eq!(tracker.repo_count(), 0);
+        assert!(tracker.get_top_repos().is_empty());
+
+        // Refresh should not panic on empty data
+        tracker.refresh_top_n();
+    }
+}
\ No newline at end of file
diff --git a/src/metrics/connection.rs b/src/metrics/connection.rs
new file mode 100644
index 0000000..6a7f406
--- /dev/null
+++ b/src/metrics/connection.rs
@@ -0,0 +1,337 @@
+//! Connection tracking with privacy-preserving abuse detection.
+//!
+//! This module tracks WebSocket connections per IP address internally for abuse
+//! detection, but NEVER exposes IP addresses in Prometheus metrics. Only aggregate
+//! counts are exposed.
+//!
+//! # Privacy Model
+//!
+//! | Data | Location | Exposed? |
+//! |------|----------|----------|
+//! | Total connections | Prometheus | ✅ Yes |
+//! | Unique IP count | Prometheus | ✅ Yes |
+//! | Flagged abuser count | Prometheus | ✅ Yes |
+//! | Actual IP addresses | Internal HashMap | ❌ No |
+//! | IP + abuse flag | Logs (when flagged) | ⚠️ Logs only |
+
+use std::net::IpAddr;
+use std::time::Instant;
+
+use dashmap::DashMap;
+use prometheus::{IntGauge, Opts, Registry};
+use tracing::warn;
+
+/// Information about connections from a specific IP address.
+struct ConnectionInfo {
+    /// Number of active connections from this IP
+    count: u32,
+    /// When the first connection from this IP was established
+    first_seen: Instant,
+    /// Whether this IP has been flagged as potentially abusive
+    flagged_as_abuse: bool,
+}
+
+/// Tracks WebSocket connections per IP with abuse detection.
+///
+/// # Thread Safety
+///
+/// Uses `DashMap` for lock-free concurrent access, as connection tracking
+/// happens across multiple tokio tasks.
+///
+/// # Privacy
+///
+/// IP addresses are stored internally only for abuse detection and are
+/// NEVER exposed in Prometheus metrics. Only aggregate counts are exposed:
+/// - Total active connections
+/// - Number of unique IPs
+/// - Number of IPs flagged as potential abusers
+pub struct ConnectionTracker {
+    /// Active connections per IP (INTERNAL ONLY - never exposed to metrics)
+    connections: DashMap<IpAddr, ConnectionInfo>,
+    
+    /// Threshold for abuse flagging (connections per IP)
+    abuse_threshold: u32,
+    
+    /// Prometheus gauge: total active connections
+    active_connections: IntGauge,
+    
+    /// Prometheus gauge: number of unique IPs connected
+    unique_ips: IntGauge,
+    
+    /// Prometheus gauge: number of IPs flagged as potential abusers
+    flagged_abusers: IntGauge,
+}
+
+impl ConnectionTracker {
+    /// Creates a new ConnectionTracker and registers metrics with Prometheus.
+    ///
+    /// # Arguments
+    ///
+    /// * `abuse_threshold` - Number of connections from a single IP before flagging
+    /// * `registry` - Prometheus registry to register metrics with
+    pub fn new(abuse_threshold: u32, registry: &Registry) -> Self {
+        let active_connections = IntGauge::with_opts(
+            Opts::new(
+                "ngit_websocket_connections_active",
+                "Current active WebSocket connections",
+            )
+        ).unwrap();
+        registry.register(Box::new(active_connections.clone())).unwrap();
+
+        let unique_ips = IntGauge::with_opts(
+            Opts::new(
+                "ngit_websocket_unique_ips",
+                "Number of unique IP addresses connected (NOT the IPs themselves)",
+            )
+        ).unwrap();
+        registry.register(Box::new(unique_ips.clone())).unwrap();
+
+        let flagged_abusers = IntGauge::with_opts(
+            Opts::new(
+                "ngit_websocket_flagged_abusers",
+                "Number of IPs exceeding connection threshold",
+            )
+        ).unwrap();
+        registry.register(Box::new(flagged_abusers.clone())).unwrap();
+
+        Self {
+            connections: DashMap::new(),
+            abuse_threshold,
+            active_connections,
+            unique_ips,
+            flagged_abusers,
+        }
+    }
+
+    /// Called when a new WebSocket connection is established.
+    ///
+    /// This method:
+    /// 1. Increments the connection count for this IP
+    /// 2. Checks if the IP has exceeded the abuse threshold
+    /// 3. Logs a warning if abuse is detected (IP is logged here only)
+    /// 4. Updates Prometheus metrics (aggregate counts only)
+    ///
+    /// # Privacy
+    ///
+    /// The IP address is logged only when abuse is detected. It is NEVER
+    /// exposed in Prometheus metrics.
+    pub fn on_connect(&self, ip: IpAddr) {
+        let mut is_new_ip = false;
+        let mut newly_flagged = false;
+
+        self.connections
+            .entry(ip)
+            .and_modify(|info| {
+                info.count += 1;
+                // Check if this connection pushes us over the threshold
+                if !info.flagged_as_abuse && info.count >= self.abuse_threshold {
+                    info.flagged_as_abuse = true;
+                    newly_flagged = true;
+                }
+            })
+            .or_insert_with(|| {
+                is_new_ip = true;
+                ConnectionInfo {
+                    count: 1,
+                    first_seen: Instant::now(),
+                    flagged_as_abuse: false,
+                }
+            });
+
+        // Update Prometheus metrics (aggregate counts only)
+        self.active_connections.inc();
+        
+        if is_new_ip {
+            self.unique_ips.inc();
+        }
+
+        if newly_flagged {
+            self.flagged_abusers.inc();
+            // Log the abuse detection - IP is only exposed in logs, not metrics
+            warn!(
+                ip = %ip,
+                threshold = self.abuse_threshold,
+                "Potential abuse detected: IP exceeded connection threshold"
+            );
+        }
+    }
+
+    /// Called when a WebSocket connection is closed.
+    ///
+    /// This method:
+    /// 1. Decrements the connection count for this IP
+    /// 2. Removes the IP from tracking if count reaches 0
+    /// 3. Updates the abuse flag count if the IP was flagged
+    /// 4. Updates Prometheus metrics (aggregate counts only)
+    pub fn on_disconnect(&self, ip: IpAddr) {
+        let mut remove_entry = false;
+        let mut was_flagged = false;
+        let mut had_connection = false;
+
+        if let Some(mut entry) = self.connections.get_mut(&ip) {
+            had_connection = true;
+            entry.count = entry.count.saturating_sub(1);
+            if entry.count == 0 {
+                remove_entry = true;
+                was_flagged = entry.flagged_as_abuse;
+            }
+        }
+
+        // Remove the entry if count is 0
+        if remove_entry {
+            self.connections.remove(&ip);
+            self.unique_ips.dec();
+            if was_flagged {
+                self.flagged_abusers.dec();
+            }
+        }
+
+        // Update total connections only if this IP had a tracked connection
+        if had_connection {
+            self.active_connections.dec();
+        }
+    }
+
+    /// Returns the current number of active connections.
+    pub fn active_connections(&self) -> u64 {
+        self.active_connections.get() as u64
+    }
+
+    /// Returns the current number of unique IPs.
+    pub fn unique_ip_count(&self) -> u64 {
+        self.unique_ips.get() as u64
+    }
+
+    /// Returns the current number of flagged abusers.
+    pub fn flagged_abuser_count(&self) -> u64 {
+        self.flagged_abusers.get() as u64
+    }
+
+    /// Returns the connection count for a specific IP (for internal use only).
+    ///
+    /// # Privacy
+    ///
+    /// This is an internal method. The returned data should NEVER be exposed
+    /// in metrics or logs without privacy consideration.
+    #[cfg(test)]
+    pub(crate) fn connection_count(&self, ip: &IpAddr) -> Option<u32> {
+        self.connections.get(ip).map(|info| info.count)
+    }
+
+    /// Returns whether an IP is flagged as abusive (for internal use only).
+    #[cfg(test)]
+    pub(crate) fn is_flagged(&self, ip: &IpAddr) -> bool {
+        self.connections
+            .get(ip)
+            .map(|info| info.flagged_as_abuse)
+            .unwrap_or(false)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::net::{Ipv4Addr, Ipv6Addr};
+
+    fn test_registry() -> Registry {
+        Registry::new()
+    }
+
+    #[test]
+    fn test_connection_tracking() {
+        let registry = test_registry();
+        let tracker = ConnectionTracker::new(5, &registry);
+        let ip = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 1));
+
+        // Connect
+        tracker.on_connect(ip);
+        assert_eq!(tracker.active_connections(), 1);
+        assert_eq!(tracker.unique_ip_count(), 1);
+        assert_eq!(tracker.connection_count(&ip), Some(1));
+
+        // Connect again from same IP
+        tracker.on_connect(ip);
+        assert_eq!(tracker.active_connections(), 2);
+        assert_eq!(tracker.unique_ip_count(), 1); // Still 1 unique IP
+        assert_eq!(tracker.connection_count(&ip), Some(2));
+
+        // Disconnect one
+        tracker.on_disconnect(ip);
+        assert_eq!(tracker.active_connections(), 1);
+        assert_eq!(tracker.unique_ip_count(), 1);
+        assert_eq!(tracker.connection_count(&ip), Some(1));
+
+        // Disconnect last
+        tracker.on_disconnect(ip);
+        assert_eq!(tracker.active_connections(), 0);
+        assert_eq!(tracker.unique_ip_count(), 0);
+        assert_eq!(tracker.connection_count(&ip), None);
+    }
+
+    #[test]
+    fn test_multiple_ips() {
+        let registry = test_registry();
+        let tracker = ConnectionTracker::new(5, &registry);
+        let ip1 = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 1));
+        let ip2 = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 2));
+        let ip3 = IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1));
+
+        tracker.on_connect(ip1);
+        tracker.on_connect(ip2);
+        tracker.on_connect(ip3);
+
+        assert_eq!(tracker.active_connections(), 3);
+        assert_eq!(tracker.unique_ip_count(), 3);
+
+        tracker.on_disconnect(ip2);
+        assert_eq!(tracker.active_connections(), 2);
+        assert_eq!(tracker.unique_ip_count(), 2);
+    }
+
+    #[test]
+    fn test_abuse_detection() {
+        let registry = test_registry();
+        let threshold = 3;
+        let tracker = ConnectionTracker::new(threshold, &registry);
+        let abuser_ip = IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1));
+        let normal_ip = IpAddr::V4(Ipv4Addr::new(10, 0, 0, 2));
+
+        // Normal user with 1 connection
+        tracker.on_connect(normal_ip);
+        assert!(!tracker.is_flagged(&normal_ip));
+        assert_eq!(tracker.flagged_abuser_count(), 0);
+
+        // Abuser approaching threshold
+        tracker.on_connect(abuser_ip);
+        tracker.on_connect(abuser_ip);
+        assert!(!tracker.is_flagged(&abuser_ip));
+        assert_eq!(tracker.flagged_abuser_count(), 0);
+
+        // Abuser hits threshold
+        tracker.on_connect(abuser_ip);
+        assert!(tracker.is_flagged(&abuser_ip));
+        assert_eq!(tracker.flagged_abuser_count(), 1);
+
+        // Normal user still not flagged
+        assert!(!tracker.is_flagged(&normal_ip));
+
+        // Abuser disconnects all - should be removed from flagged count
+        tracker.on_disconnect(abuser_ip);
+        tracker.on_disconnect(abuser_ip);
+        tracker.on_disconnect(abuser_ip);
+        assert_eq!(tracker.flagged_abuser_count(), 0);
+        assert_eq!(tracker.active_connections(), 1); // Only normal user remains
+    }
+
+    #[test]
+    fn test_disconnect_without_connect() {
+        let registry = test_registry();
+        let tracker = ConnectionTracker::new(5, &registry);
+        let ip = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 1));
+
+        // Disconnect without connect should not panic or go negative
+        tracker.on_disconnect(ip);
+        assert_eq!(tracker.active_connections(), 0);
+        assert_eq!(tracker.unique_ip_count(), 0);
+    }
+}
\ No newline at end of file
diff --git a/src/metrics/mod.rs b/src/metrics/mod.rs
new file mode 100644
index 0000000..4a4fe57
--- /dev/null
+++ b/src/metrics/mod.rs
@@ -0,0 +1,469 @@
+//! Prometheus metrics for ngit-grasp relay.
+//!
+//! This module provides comprehensive monitoring metrics including:
+//! - WebSocket connection tracking (with privacy-preserving IP aggregation)
+//! - Git operation metrics (clone, fetch, push)
+//! - Repository bandwidth tracking (top-N only for cardinality control)
+//! - Nostr event metrics
+//!
+//! # Privacy
+//! IP addresses are NEVER exposed in metrics. The `ConnectionTracker` maintains
+//! per-IP counts internally only for abuse detection. Only aggregate counts
+//! are exposed to Prometheus.
+
+pub mod bandwidth;
+pub mod connection;
+
+use std::sync::Arc;
+use std::time::Instant;
+
+use lazy_static::lazy_static;
+use prometheus::{
+    Counter, CounterVec, Encoder, Gauge, GaugeVec, Histogram, HistogramOpts, HistogramVec, Opts,
+    Registry, TextEncoder,
+};
+
+use bandwidth::BandwidthTracker;
+use connection::ConnectionTracker;
+
+lazy_static! {
+    /// Global Prometheus registry for ngit-grasp metrics
+    pub static ref REGISTRY: Registry = Registry::new();
+}
+
+/// Central metrics collection for ngit-grasp relay.
+///
+/// Thread-safe and designed for concurrent access from multiple tokio tasks.
+#[derive(Clone)]
+pub struct Metrics {
+    inner: Arc<MetricsInner>,
+}
+
+struct MetricsInner {
+    /// Connection tracking with abuse detection
+    pub connection_tracker: ConnectionTracker,
+
+    /// Repository bandwidth tracking (top-N only)
+    pub bandwidth_tracker: BandwidthTracker,
+
+    // === WebSocket Metrics ===
+    /// Total WebSocket connections since startup
+    pub websocket_connections_total: Counter,
+    /// Connection duration histogram
+    pub websocket_connection_duration: Histogram,
+    /// Messages received by type (REQ, EVENT, CLOSE)
+    pub websocket_messages_received: CounterVec,
+    /// Messages sent by type (EVENT, EOSE, OK, NOTICE)
+    pub websocket_messages_sent: CounterVec,
+
+    // === Git Operation Metrics ===
+    /// Git operations by type and status
+    pub git_operations_total: CounterVec,
+    /// Git operation duration histogram
+    pub git_operation_duration: HistogramVec,
+    /// Total bytes transferred
+    pub git_bytes_total: CounterVec,
+    /// Push authorization results
+    pub git_push_authorization: CounterVec,
+
+    // === Nostr Event Metrics ===
+    /// Events received by kind
+    pub events_received_total: CounterVec,
+    /// Events successfully stored by kind
+    pub events_stored_total: CounterVec,
+    /// Events rejected by kind and reason
+    pub events_rejected_total: CounterVec,
+
+    // === Repository Metrics ===
+    /// Total repositories hosted
+    pub repositories_total: Gauge,
+
+    // === System Health Metrics ===
+    /// Server start time for uptime calculation
+    pub start_time: Instant,
+    /// Build information gauge
+    pub build_info: GaugeVec,
+}
+
+impl Metrics {
+    /// Creates a new Metrics instance and registers all metrics with Prometheus.
+    ///
+    /// # Arguments
+    /// * `abuse_threshold` - Number of connections from a single IP before flagging as abuse
+    pub fn new(abuse_threshold: u32) -> Self {
+        let inner = MetricsInner::new(abuse_threshold);
+        Self {
+            inner: Arc::new(inner),
+        }
+    }
+
+    /// Returns the connection tracker for WebSocket connection management.
+    pub fn connection_tracker(&self) -> &ConnectionTracker {
+        &self.inner.connection_tracker
+    }
+
+    /// Returns the bandwidth tracker for repository bandwidth tracking.
+    pub fn bandwidth_tracker(&self) -> &BandwidthTracker {
+        &self.inner.bandwidth_tracker
+    }
+
+    // === WebSocket Recording Methods ===
+
+    /// Record a new WebSocket connection
+    pub fn record_websocket_connection(&self) {
+        self.inner.websocket_connections_total.inc();
+    }
+
+    /// Start timing a WebSocket connection, returns timer that records on drop
+    pub fn start_connection_timer(&self) -> HistogramTimer {
+        HistogramTimer::new(self.inner.websocket_connection_duration.clone())
+    }
+
+    /// Record a received WebSocket message
+    pub fn record_message_received(&self, msg_type: &str) {
+        self.inner
+            .websocket_messages_received
+            .with_label_values(&[msg_type])
+            .inc();
+    }
+
+    /// Record a sent WebSocket message
+    pub fn record_message_sent(&self, msg_type: &str) {
+        self.inner
+            .websocket_messages_sent
+            .with_label_values(&[msg_type])
+            .inc();
+    }
+
+    // === Git Operation Recording Methods ===
+
+    /// Record a git operation completion
+    pub fn record_git_operation(&self, operation: &str, status: &str) {
+        self.inner
+            .git_operations_total
+            .with_label_values(&[operation, status])
+            .inc();
+    }
+
+    /// Start timing a git operation, returns a timer
+    pub fn start_git_operation_timer(&self, operation: &str) -> GitOperationTimer {
+        GitOperationTimer::new(self.inner.git_operation_duration.clone(), operation.to_string())
+    }
+
+    /// Record bytes transferred for a git operation
+    pub fn record_git_bytes(&self, direction: &str, bytes: u64) {
+        self.inner
+            .git_bytes_total
+            .with_label_values(&[direction])
+            .inc_by(bytes as f64);
+    }
+
+    /// Record a push authorization result
+    pub fn record_push_authorization(&self, result: &str) {
+        self.inner
+            .git_push_authorization
+            .with_label_values(&[result])
+            .inc();
+    }
+
+    // === Nostr Event Recording Methods ===
+
+    /// Record a received Nostr event
+    pub fn record_event_received(&self, kind: u64) {
+        self.inner
+            .events_received_total
+            .with_label_values(&[&kind.to_string()])
+            .inc();
+    }
+
+    /// Record a stored Nostr event
+    pub fn record_event_stored(&self, kind: u64) {
+        self.inner
+            .events_stored_total
+            .with_label_values(&[&kind.to_string()])
+            .inc();
+    }
+
+    /// Record a rejected Nostr event
+    pub fn record_event_rejected(&self, kind: u64, reason: &str) {
+        self.inner
+            .events_rejected_total
+            .with_label_values(&[&kind.to_string(), reason])
+            .inc();
+    }
+
+    // === Repository Metrics ===
+
+    /// Set the total number of repositories
+    pub fn set_repositories_total(&self, count: u64) {
+        self.inner.repositories_total.set(count as f64);
+    }
+
+    /// Increment the repository count
+    pub fn inc_repositories_total(&self) {
+        self.inner.repositories_total.inc();
+    }
+
+    // === Rendering ===
+
+    /// Render all metrics in Prometheus text format.
+    ///
+    /// This method:
+    /// 1. Refreshes the top-N bandwidth metrics if needed
+    /// 2. Updates uptime
+    /// 3. Gathers all metrics from the registry
+    /// 4. Encodes them in Prometheus text format
+    pub fn render(&self) -> String {
+        // Refresh top-N bandwidth repos if needed
+        self.inner.bandwidth_tracker.maybe_refresh_top_n();
+
+        // Gather and encode metrics
+        let encoder = TextEncoder::new();
+        let metric_families = REGISTRY.gather();
+        let mut buffer = Vec::new();
+        encoder.encode(&metric_families, &mut buffer).unwrap();
+
+        // Add uptime as a comment (it's derived, not a registered metric)
+        let uptime = self.inner.start_time.elapsed().as_secs();
+        let mut output = String::from_utf8(buffer).unwrap();
+        output.push_str(&format!(
+            "\n# HELP ngit_uptime_seconds Seconds since server startup\n# TYPE ngit_uptime_seconds counter\nngit_uptime_seconds {}\n",
+            uptime
+        ));
+
+        output
+    }
+
+    /// Check if the system is under high load (for sync scheduling)
+    pub fn is_high_load(&self, threshold: u64) -> bool {
+        self.inner.connection_tracker.active_connections() > threshold
+    }
+}
+
+impl MetricsInner {
+    fn new(abuse_threshold: u32) -> Self {
+        // Create connection tracker
+        let connection_tracker = ConnectionTracker::new(abuse_threshold, &REGISTRY);
+
+        // Create bandwidth tracker
+        let bandwidth_tracker = BandwidthTracker::new(&REGISTRY);
+
+        // WebSocket metrics
+        let websocket_connections_total = Counter::with_opts(
+            Opts::new(
+                "ngit_websocket_connections_total",
+                "Total WebSocket connections since startup",
+            )
+        ).unwrap();
+        REGISTRY.register(Box::new(websocket_connections_total.clone())).unwrap();
+
+        let websocket_connection_duration = Histogram::with_opts(
+            HistogramOpts::new(
+                "ngit_websocket_connection_duration_seconds",
+                "Duration of WebSocket connections",
+            )
+            .buckets(vec![1.0, 5.0, 15.0, 30.0, 60.0, 300.0, 900.0, 3600.0]),
+        ).unwrap();
+        REGISTRY.register(Box::new(websocket_connection_duration.clone())).unwrap();
+
+        let websocket_messages_received = CounterVec::new(
+            Opts::new(
+                "ngit_websocket_messages_received_total",
+                "WebSocket messages received by type",
+            ),
+            &["type"],
+        ).unwrap();
+        REGISTRY.register(Box::new(websocket_messages_received.clone())).unwrap();
+
+        let websocket_messages_sent = CounterVec::new(
+            Opts::new(
+                "ngit_websocket_messages_sent_total",
+                "WebSocket messages sent by type",
+            ),
+            &["type"],
+        ).unwrap();
+        REGISTRY.register(Box::new(websocket_messages_sent.clone())).unwrap();
+
+        // Git operation metrics
+        let git_operations_total = CounterVec::new(
+            Opts::new(
+                "ngit_git_operations_total",
+                "Git operations by type and status",
+            ),
+            &["operation", "status"],
+        ).unwrap();
+        REGISTRY.register(Box::new(git_operations_total.clone())).unwrap();
+
+        let git_operation_duration = HistogramVec::new(
+            HistogramOpts::new(
+                "ngit_git_operation_duration_seconds",
+                "Duration of git operations",
+            )
+            .buckets(vec![0.1, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0]),
+            &["operation"],
+        ).unwrap();
+        REGISTRY.register(Box::new(git_operation_duration.clone())).unwrap();
+
+        let git_bytes_total = CounterVec::new(
+            Opts::new(
+                "ngit_git_bytes_total",
+                "Total bytes transferred for git operations",
+            ),
+            &["direction"],
+        ).unwrap();
+        REGISTRY.register(Box::new(git_bytes_total.clone())).unwrap();
+
+        let git_push_authorization = CounterVec::new(
+            Opts::new(
+                "ngit_git_push_authorization_total",
+                "Push authorization results",
+            ),
+            &["result"],
+        ).unwrap();
+        REGISTRY.register(Box::new(git_push_authorization.clone())).unwrap();
+
+        // Nostr event metrics
+        let events_received_total = CounterVec::new(
+            Opts::new(
+                "ngit_events_received_total",
+                "Nostr events received by kind",
+            ),
+            &["kind"],
+        ).unwrap();
+        REGISTRY.register(Box::new(events_received_total.clone())).unwrap();
+
+        let events_stored_total = CounterVec::new(
+            Opts::new(
+                "ngit_events_stored_total",
+                "Nostr events successfully stored by kind",
+            ),
+            &["kind"],
+        ).unwrap();
+        REGISTRY.register(Box::new(events_stored_total.clone())).unwrap();
+
+        let events_rejected_total = CounterVec::new(
+            Opts::new(
+                "ngit_events_rejected_total",
+                "Nostr events rejected by kind and reason",
+            ),
+            &["kind", "reason"],
+        ).unwrap();
+        REGISTRY.register(Box::new(events_rejected_total.clone())).unwrap();
+
+        // Repository metrics
+        let repositories_total = Gauge::with_opts(
+            Opts::new(
+                "ngit_repositories_total",
+                "Total repositories hosted",
+            )
+        ).unwrap();
+        REGISTRY.register(Box::new(repositories_total.clone())).unwrap();
+
+        // Build info
+        let build_info = GaugeVec::new(
+            Opts::new(
+                "ngit_build_info",
+                "Build information",
+            ),
+            &["version", "commit"],
+        ).unwrap();
+        REGISTRY.register(Box::new(build_info.clone())).unwrap();
+        
+        // Set build info gauge to 1 (it's just for labels)
+        build_info
+            .with_label_values(&[env!("CARGO_PKG_VERSION"), option_env!("GIT_HASH").unwrap_or("unknown")])
+            .set(1.0);
+
+        Self {
+            connection_tracker,
+            bandwidth_tracker,
+            websocket_connections_total,
+            websocket_connection_duration,
+            websocket_messages_received,
+            websocket_messages_sent,
+            git_operations_total,
+            git_operation_duration,
+            git_bytes_total,
+            git_push_authorization,
+            events_received_total,
+            events_stored_total,
+            events_rejected_total,
+            repositories_total,
+            start_time: Instant::now(),
+            build_info,
+        }
+    }
+}
+
+/// Timer for tracking WebSocket connection duration.
+/// Records the elapsed time when dropped.
+pub struct HistogramTimer {
+    histogram: Histogram,
+    start: Instant,
+}
+
+impl HistogramTimer {
+    fn new(histogram: Histogram) -> Self {
+        Self {
+            histogram,
+            start: Instant::now(),
+        }
+    }
+}
+
+impl Drop for HistogramTimer {
+    fn drop(&mut self) {
+        let elapsed = self.start.elapsed().as_secs_f64();
+        self.histogram.observe(elapsed);
+    }
+}
+
+/// Timer for tracking Git operation duration.
+/// Records the elapsed time when dropped.
+pub struct GitOperationTimer {
+    histogram_vec: HistogramVec,
+    operation: String,
+    start: Instant,
+}
+
+impl GitOperationTimer {
+    fn new(histogram_vec: HistogramVec, operation: String) -> Self {
+        Self {
+            histogram_vec,
+            operation,
+            start: Instant::now(),
+        }
+    }
+}
+
+impl Drop for GitOperationTimer {
+    fn drop(&mut self) {
+        let elapsed = self.start.elapsed().as_secs_f64();
+        self.histogram_vec
+            .with_label_values(&[&self.operation])
+            .observe(elapsed);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_metrics_creation() {
+        // Note: This test may fail if run with other tests due to global registry
+        // In production, consider using a test-specific registry
+        let metrics = Metrics::new(10);
+        
+        // Test that we can record metrics without panicking
+        metrics.record_websocket_connection();
+        metrics.record_message_received("REQ");
+        metrics.record_message_sent("EVENT");
+        metrics.record_git_operation("clone", "success");
+        metrics.record_git_bytes("in", 1024);
+        metrics.record_event_received(1);
+        metrics.record_event_stored(1);
+        metrics.record_event_rejected(1, "invalid_signature");
+        metrics.set_repositories_total(5);
+    }
+}
\ No newline at end of file