feature: metrics

Cargo.lock

···
 checksum = "d71b6127be86fdcfddb610f7182ac57211d4b18a3e9c82eb2d17662f2227ad6a"
 
 [[package]]
+name = "cadence"
+version = "1.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3075f133bee430b7644c54fb629b9b4420346ffa275a45c81a6babe8b09b4f51"
+dependencies = [
+ "crossbeam-channel",
+]
+
+[[package]]
 name = "cbor4ii"
 version = "0.2.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
···
  "atproto-identity",
  "axum",
  "bincode",
+ "cadence",
  "deadpool-redis",
  "httpdate",
  "metrohash",

Cargo.toml

···
 atproto-identity = { version = "0.11.3" }
 axum = { version = "0.8" }
 bincode = { version = "2.0.1", features = ["serde"] }
+cadence = "1.6.0"
 deadpool-redis = { version = "0.22", features = ["connection-manager", "tokio-comp", "tokio-rustls-comp"] }
 httpdate = "1.0"
 metrohash = "1.0.7"

src/bin/quickdid.rs

···
     },
     handle_resolver_task::{HandleResolverTaskConfig, create_handle_resolver_task_with_config},
     http::{AppContext, create_router},
+    metrics::create_metrics_publisher,
     queue::{
         HandleResolutionWork, QueueAdapter, create_mpsc_queue_from_channel, create_noop_queue,
         create_redis_queue, create_sqlite_queue, create_sqlite_queue_with_max_size,
···
                     "    RESOLVER_MAX_CONCURRENT_TIMEOUT_MS Timeout for acquiring permits in ms (default: 0 = no timeout)"
                 );
                 println!();
+                println!("    METRICS:");
+                println!(
+                    "    METRICS_ADAPTER     Metrics adapter: 'noop' or 'statsd' (default: noop)"
+                );
+                println!(
+                    "    METRICS_STATSD_HOST StatsD host when using statsd adapter (e.g., localhost:8125)"
+                );
+                println!(
+                    "    METRICS_PREFIX      Prefix for all metrics (default: quickdid)"
+                );
+                println!(
+                    "    METRICS_TAGS        Default tags for metrics (comma-separated key:value pairs)"
+                );
+                println!();
                 println!(
                     "For more information, visit: https://github.com/smokesignal.events/quickdid"
                 );
···
     // Create DNS resolver Arc for sharing
     let dns_resolver_arc = Arc::new(dns_resolver);
 
+    // Create metrics publisher based on configuration
+    let metrics_publisher = create_metrics_publisher(&config).map_err(|e| {
+        tracing::error!("Failed to create metrics publisher: {}", e);
+        anyhow::anyhow!("Failed to create metrics publisher: {}", e)
+    })?;
+    
+    tracing::info!(
+        "Metrics publisher created with {} adapter",
+        config.metrics_adapter
+    );
+
+    metrics_publisher.gauge("server", 1).await;
+
     // Create base handle resolver using factory function
     let mut base_handle_resolver =
-        create_base_resolver(dns_resolver_arc.clone(), http_client.clone());
+        create_base_resolver(dns_resolver_arc.clone(), http_client.clone(), metrics_publisher.clone());
 
     // Apply rate limiting if configured
     if config.resolver_max_concurrent > 0 {
···
             base_handle_resolver,
             config.resolver_max_concurrent,
             config.resolver_max_concurrent_timeout_ms,
+            metrics_publisher.clone(),
         );
     }
 
···
                 "Using Redis-backed handle resolver with {}-second cache TTL",
                 config.cache_ttl_redis
             );
-            create_redis_resolver_with_ttl(base_handle_resolver, pool, config.cache_ttl_redis)
+            create_redis_resolver_with_ttl(base_handle_resolver, pool, config.cache_ttl_redis, metrics_publisher.clone())
         } else if let Some(pool) = sqlite_pool {
             tracing::info!(
                 "Using SQLite-backed handle resolver with {}-second cache TTL",
                 config.cache_ttl_sqlite
             );
-            create_sqlite_resolver_with_ttl(base_handle_resolver, pool, config.cache_ttl_sqlite)
+            create_sqlite_resolver_with_ttl(base_handle_resolver, pool, config.cache_ttl_sqlite, metrics_publisher.clone())
         } else {
             tracing::info!(
                 "Using in-memory handle resolver with {}-second cache TTL",
                 config.cache_ttl_memory
             );
-            create_caching_resolver(base_handle_resolver, config.cache_ttl_memory)
+            create_caching_resolver(base_handle_resolver, config.cache_ttl_memory, metrics_publisher.clone())
         };
 
     // Create task tracker and cancellation token
···
                 handle_resolver.clone(),
                 token.clone(),
                 handle_task_config,
+                metrics_publisher.clone(),
             );
 
             // Spawn the handle resolver task
···
         config.service_did.clone(),
         handle_resolver.clone(),
         handle_queue,
+        metrics_publisher,
         config.etag_seed.clone(),
         config.cache_control_header.clone(),
     );

src/config.rs

···
     /// Calculated at startup for efficiency.
     /// None if cache_max_age is 0 (disabled).
     pub cache_control_header: Option<String>,
+
+    /// Metrics adapter type: "noop" or "statsd"
+    /// Default: "noop" (no metrics collection)
+    pub metrics_adapter: String,
+
+    /// StatsD host for metrics collection (e.g., "localhost:8125")
+    /// Required when metrics_adapter is "statsd"
+    pub metrics_statsd_host: Option<String>,
+
+    /// Metrics prefix for all metrics (e.g., "quickdid")
+    /// Default: "quickdid"
+    pub metrics_prefix: String,
+
+    /// Default tags for all metrics (comma-separated key:value pairs)
+    /// Example: "env:production,service:quickdid"
+    pub metrics_tags: Option<String>,
 }
 
 impl Config {
···
             cache_max_stale: parse_env("CACHE_MAX_STALE", 172800)?, // 48 hours
             cache_min_fresh: parse_env("CACHE_MIN_FRESH", 3600)?,   // 1 hour
             cache_control_header: None,                             // Will be calculated below
+            metrics_adapter: get_env_or_default("METRICS_ADAPTER", Some("noop")).unwrap(),
+            metrics_statsd_host: get_env_or_default("METRICS_STATSD_HOST", None),
+            metrics_prefix: get_env_or_default("METRICS_PREFIX", Some("quickdid")).unwrap(),
+            metrics_tags: get_env_or_default("METRICS_TAGS", None),
         };
 
         // Calculate the Cache-Control header value if enabled
···
                 "RESOLVER_MAX_CONCURRENT_TIMEOUT_MS must be <= 60000 (60 seconds)".to_string(),
             ));
         }
+        
+        // Validate metrics configuration
+        match self.metrics_adapter.as_str() {
+            "noop" | "statsd" => {}
+            _ => {
+                return Err(ConfigError::InvalidValue(format!(
+                    "Invalid METRICS_ADAPTER '{}', must be 'noop' or 'statsd'",
+                    self.metrics_adapter
+                )));
+            }
+        }
+        
+        // If statsd is configured, ensure host is provided
+        if self.metrics_adapter == "statsd" && self.metrics_statsd_host.is_none() {
+            return Err(ConfigError::MissingRequired(
+                "METRICS_STATSD_HOST is required when METRICS_ADAPTER is 'statsd'".to_string(),
+            ));
+        }
+        
         Ok(())
     }
 }

src/handle_resolver/base.rs

···
 
 use super::errors::HandleResolverError;
 use super::traits::HandleResolver;
+use crate::metrics::SharedMetricsPublisher;
 use async_trait::async_trait;
 use atproto_identity::resolve::{DnsResolver, resolve_subject};
 use reqwest::Client;
···
 /// use reqwest::Client;
 /// use atproto_identity::resolve::HickoryDnsResolver;
 /// use quickdid::handle_resolver::{create_base_resolver, HandleResolver};
+/// use quickdid::metrics::NoOpMetricsPublisher;
 ///
 /// # async fn example() {
 /// let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
 /// let http_client = Client::new();
+/// let metrics = Arc::new(NoOpMetricsPublisher);
 ///
 /// let resolver = create_base_resolver(
 ///     dns_resolver,
 ///     http_client,
+///     metrics,
 /// );
 ///
 /// let (did, timestamp) = resolver.resolve("alice.bsky.social").await.unwrap();
···
 
     /// HTTP client for DID document retrieval and well-known endpoint queries.
     http_client: Client,
+
+    /// Metrics publisher for telemetry.
+    metrics: SharedMetricsPublisher,
 }
 
 #[async_trait]
 impl HandleResolver for BaseHandleResolver {
     async fn resolve(&self, s: &str) -> Result<(String, u64), HandleResolverError> {
-        let did = resolve_subject(&self.http_client, &*self.dns_resolver, s)
+        let start_time = std::time::Instant::now();
+        
+        // Perform DNS/HTTP resolution
+        let result = resolve_subject(&self.http_client, &*self.dns_resolver, s)
             .await
-            .map_err(|e| HandleResolverError::ResolutionFailed(e.to_string()))?;
+            .map_err(|e| HandleResolverError::ResolutionFailed(e.to_string()));
 
-        let timestamp = SystemTime::now()
-            .duration_since(UNIX_EPOCH)
-            .map_err(|e| {
-                HandleResolverError::ResolutionFailed(format!("System time error: {}", e))
-            })?
-            .as_secs();
+        let duration_ms = start_time.elapsed().as_millis() as u64;
+        
+        // Publish metrics
+        
+        match result {
+            Ok(did) => {
+                self.metrics.time_with_tags("resolver.base.duration_ms", duration_ms, &[("success", "1")]).await;
+                
+                let timestamp = SystemTime::now()
+                    .duration_since(UNIX_EPOCH)
+                    .map_err(|e| {
+                        HandleResolverError::ResolutionFailed(format!("System time error: {}", e))
+                    })?
+                    .as_secs();
 
-        Ok((did, timestamp))
+                Ok((did, timestamp))
+            }
+            Err(e) => {
+                self.metrics.time_with_tags("resolver.base.duration_ms", duration_ms, &[("success", "0")]).await;
+                Err(e)
+            }
+        }
     }
 }
 
···
 ///
 /// * `dns_resolver` - DNS resolver for TXT record lookups
 /// * `http_client` - HTTP client for well-known endpoint queries
+/// * `metrics` - Metrics publisher for telemetry
 pub fn create_base_resolver(
     dns_resolver: Arc<dyn DnsResolver>,
     http_client: Client,
+    metrics: SharedMetricsPublisher,
 ) -> Arc<dyn HandleResolver> {
     Arc::new(BaseHandleResolver {
         dns_resolver,
         http_client,
+        metrics,
     })
 }

src/handle_resolver/memory.rs

···
 
 use super::errors::HandleResolverError;
 use super::traits::HandleResolver;
+use crate::metrics::SharedMetricsPublisher;
 use async_trait::async_trait;
 use std::collections::HashMap;
 use std::sync::Arc;
···
 /// ```no_run
 /// use std::sync::Arc;
 /// use quickdid::handle_resolver::{create_caching_resolver, create_base_resolver, HandleResolver};
+/// use quickdid::metrics::NoOpMetricsPublisher;
 ///
 /// # async fn example() {
 /// # use atproto_identity::resolve::HickoryDnsResolver;
 /// # use reqwest::Client;
 /// # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
 /// # let http_client = Client::new();
-/// let base_resolver = create_base_resolver(dns_resolver, http_client);
+/// # let metrics = Arc::new(NoOpMetricsPublisher);
+/// let base_resolver = create_base_resolver(dns_resolver, http_client, metrics.clone());
 /// let caching_resolver = create_caching_resolver(
 ///     base_resolver,
-///     300  // 5 minute TTL
+///     300,  // 5 minute TTL
+///     metrics
 /// );
 ///
 /// // First call hits the underlying resolver
···
     inner: Arc<dyn HandleResolver>,
     cache: Arc<RwLock<HashMap<String, ResolveHandleResult>>>,
     ttl_seconds: u64,
+    metrics: SharedMetricsPublisher,
 }
 
 impl CachingHandleResolver {
···
     ///
     /// * `inner` - The underlying resolver to use for actual resolution
     /// * `ttl_seconds` - How long to cache results in seconds
-    pub fn new(inner: Arc<dyn HandleResolver>, ttl_seconds: u64) -> Self {
+    /// * `metrics` - Metrics publisher for telemetry
+    pub fn new(inner: Arc<dyn HandleResolver>, ttl_seconds: u64, metrics: SharedMetricsPublisher) -> Self {
         Self {
             inner,
             cache: Arc::new(RwLock::new(HashMap::new())),
             ttl_seconds,
+            metrics,
         }
     }
 
···
                     ResolveHandleResult::Found(timestamp, did) => {
                         if !self.is_expired(*timestamp) {
                             tracing::debug!("Cache hit for handle {}: {}", handle, did);
+                            self.metrics.incr("resolver.memory.cache_hit").await;
                             return Ok((did.clone(), *timestamp));
                         }
                         tracing::debug!("Cache entry expired for handle {}", handle);
+                        self.metrics.incr("resolver.memory.cache_expired").await;
                     }
                     ResolveHandleResult::NotFound(timestamp, error) => {
                         if !self.is_expired(*timestamp) {
···
                                 handle,
                                 error
                             );
+                            self.metrics.incr("resolver.memory.cache_hit_not_resolved").await;
                             return Err(HandleResolverError::HandleNotFoundCached(error.clone()));
                         }
                         tracing::debug!("Cache entry expired for handle {}", handle);
+                        self.metrics.incr("resolver.memory.cache_expired").await;
                     }
                 }
             }
···
 
         // Not in cache or expired, resolve through inner resolver
         tracing::debug!("Cache miss for handle {}, resolving...", handle);
+        self.metrics.incr("resolver.memory.cache_miss").await;
         let result = self.inner.resolve(s).await;
 
         // Store in cache
···
                         handle.clone(),
                         ResolveHandleResult::Found(*timestamp, did.clone()),
                     );
+                    self.metrics.incr("resolver.memory.cache_set").await;
                     tracing::debug!(
                         "Cached successful resolution for handle {}: {}",
                         handle,
···
                         handle.clone(),
                         ResolveHandleResult::NotFound(timestamp, e.to_string()),
                     );
+                    self.metrics.incr("resolver.memory.cache_set_error").await;
                     tracing::debug!("Cached failed resolution for handle {}: {}", handle, e);
                 }
             }
+            
+            // Track cache size
+            let cache_size = cache.len() as u64;
+            self.metrics.gauge("resolver.memory.cache_entries", cache_size).await;
         }
 
         result
···
 ///
 /// * `inner` - The underlying resolver to use for actual resolution
 /// * `ttl_seconds` - How long to cache results in seconds
+/// * `metrics` - Metrics publisher for telemetry
 ///
 /// # Example
 ///
 /// ```no_run
 /// use std::sync::Arc;
 /// use quickdid::handle_resolver::{create_base_resolver, create_caching_resolver, HandleResolver};
+/// use quickdid::metrics::NoOpMetricsPublisher;
 ///
 /// # async fn example() {
 /// # use atproto_identity::resolve::HickoryDnsResolver;
 /// # use reqwest::Client;
 /// # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
 /// # let http_client = Client::new();
+/// # let metrics = Arc::new(NoOpMetricsPublisher);
 /// let base = create_base_resolver(
 ///     dns_resolver,
 ///     http_client,
+///     metrics.clone(),
 /// );
 ///
-/// let resolver = create_caching_resolver(base, 300);  // 5 minute TTL
+/// let resolver = create_caching_resolver(base, 300, metrics);  // 5 minute TTL
 /// let did = resolver.resolve("alice.bsky.social").await.unwrap();
 /// # }
 /// ```
 pub fn create_caching_resolver(
     inner: Arc<dyn HandleResolver>,
     ttl_seconds: u64,
+    metrics: SharedMetricsPublisher,
 ) -> Arc<dyn HandleResolver> {
-    Arc::new(CachingHandleResolver::new(inner, ttl_seconds))
+    Arc::new(CachingHandleResolver::new(inner, ttl_seconds, metrics))
 }

src/handle_resolver/mod.rs

···
 //! ```no_run
 //! use std::sync::Arc;
 //! use quickdid::handle_resolver::{create_base_resolver, create_caching_resolver, HandleResolver};
+//! use quickdid::metrics::NoOpMetricsPublisher;
 //!
 //! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
 //! # use atproto_identity::resolve::HickoryDnsResolver;
 //! # use reqwest::Client;
 //! # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
 //! # let http_client = Client::new();
+//! # let metrics = Arc::new(NoOpMetricsPublisher);
 //! // Create base resolver using factory function
 //! let base = create_base_resolver(
 //!     dns_resolver,
 //!     http_client,
+//!     metrics.clone(),
 //! );
 //!
 //! // Wrap with in-memory caching
-//! let resolver = create_caching_resolver(base, 300);
+//! let resolver = create_caching_resolver(base, 300, metrics);
 //!
 //! // Resolve a handle
 //! let did = resolver.resolve("alice.bsky.social").await?;

src/handle_resolver/rate_limited.rs

···
 
 use super::errors::HandleResolverError;
 use super::traits::HandleResolver;
+use crate::metrics::SharedMetricsPublisher;
 use async_trait::async_trait;
 use std::sync::Arc;
 use std::time::Duration;
···
 ///     create_rate_limited_resolver,
 ///     HandleResolver,
 /// };
+/// use quickdid::metrics::NoOpMetricsPublisher;
 ///
 /// # async fn example() {
 /// # use atproto_identity::resolve::HickoryDnsResolver;
 /// # use reqwest::Client;
 /// # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
 /// # let http_client = Client::new();
+/// # let metrics = Arc::new(NoOpMetricsPublisher);
 /// // Create base resolver
-/// let base = create_base_resolver(dns_resolver, http_client);
+/// let base = create_base_resolver(dns_resolver, http_client, metrics.clone());
 ///
 /// // Wrap with rate limiting (max 10 concurrent resolutions)
-/// let rate_limited = create_rate_limited_resolver(base, 10);
+/// let rate_limited = create_rate_limited_resolver(base, 10, metrics);
 ///
 /// // Use the rate-limited resolver
 /// let (did, timestamp) = rate_limited.resolve("alice.bsky.social").await.unwrap();
···
     /// Optional timeout for acquiring permits (in milliseconds).
     /// When None or 0, no timeout is applied.
     timeout_ms: Option<u64>,
+
+    /// Metrics publisher for telemetry.
+    metrics: SharedMetricsPublisher,
 }
 
 impl RateLimitedHandleResolver {
···
     ///
     /// * `inner` - The inner resolver to wrap
     /// * `max_concurrent` - Maximum number of concurrent resolutions allowed
-    pub fn new(inner: Arc<dyn HandleResolver>, max_concurrent: usize) -> Self {
+    /// * `metrics` - Metrics publisher for telemetry
+    pub fn new(inner: Arc<dyn HandleResolver>, max_concurrent: usize, metrics: SharedMetricsPublisher) -> Self {
         Self {
             inner,
             semaphore: Arc::new(Semaphore::new(max_concurrent)),
             timeout_ms: None,
+            metrics,
         }
     }
 
···
     /// * `inner` - The inner resolver to wrap
     /// * `max_concurrent` - Maximum number of concurrent resolutions allowed
     /// * `timeout_ms` - Timeout in milliseconds for acquiring permits (0 = no timeout)
+    /// * `metrics` - Metrics publisher for telemetry
     pub fn new_with_timeout(
         inner: Arc<dyn HandleResolver>,
         max_concurrent: usize,
         timeout_ms: u64,
+        metrics: SharedMetricsPublisher,
     ) -> Self {
         Self {
             inner,
···
             } else {
                 None
             },
+            metrics,
         }
     }
 }
···
 #[async_trait]
 impl HandleResolver for RateLimitedHandleResolver {
     async fn resolve(&self, s: &str) -> Result<(String, u64), HandleResolverError> {
+        let permit_start = std::time::Instant::now();
+        
+        // Track rate limiter queue depth
+        let available_permits = self.semaphore.available_permits();
+        self.metrics.gauge("resolver.rate_limit.available_permits", available_permits as u64).await;
+        
         // Acquire a permit from the semaphore, with optional timeout
         let _permit = match self.timeout_ms {
             Some(timeout_ms) if timeout_ms > 0 => {
                 // Apply timeout when acquiring permit
                 let duration = Duration::from_millis(timeout_ms);
                 match timeout(duration, self.semaphore.acquire()).await {
-                    Ok(Ok(permit)) => permit,
+                    Ok(Ok(permit)) => {
+                        let wait_ms = permit_start.elapsed().as_millis() as u64;
+                        self.metrics.time("resolver.rate_limit.permit_acquired", wait_ms).await;
+                        permit
+                    }
                     Ok(Err(e)) => {
                         // Semaphore error (e.g., closed)
+                        self.metrics.incr("resolver.rate_limit.permit_error").await;
                         return Err(HandleResolverError::ResolutionFailed(format!(
                             "Failed to acquire rate limit permit: {}",
                             e
···
                     }
                     Err(_) => {
                         // Timeout occurred
+                        self.metrics.incr("resolver.rate_limit.permit_timeout").await;
                         return Err(HandleResolverError::ResolutionFailed(format!(
                             "Rate limit permit acquisition timed out after {}ms",
                             timeout_ms
···
             }
             _ => {
                 // No timeout configured, wait indefinitely
-                self.semaphore.acquire().await.map_err(|e| {
-                    HandleResolverError::ResolutionFailed(format!(
-                        "Failed to acquire rate limit permit: {}",
-                        e
-                    ))
-                })?
+                match self.semaphore.acquire().await {
+                    Ok(permit) => {
+                        let wait_ms = permit_start.elapsed().as_millis() as u64;
+                        self.metrics.time("resolver.rate_limit.permit_acquired", wait_ms).await;
+                        permit
+                    }
+                    Err(e) => {
+                        self.metrics.incr("resolver.rate_limit.permit_error").await;
+                        return Err(HandleResolverError::ResolutionFailed(format!(
+                            "Failed to acquire rate limit permit: {}",
+                            e
+                        )));
+                    }
+                }
             }
         };
 
···
 ///
 /// * `inner` - The resolver to wrap with rate limiting
 /// * `max_concurrent` - Maximum number of concurrent resolutions allowed
+/// * `metrics` - Metrics publisher for telemetry
 ///
 /// # Returns
 ///
···
 /// # async fn example() {
 /// # use atproto_identity::resolve::HickoryDnsResolver;
 /// # use reqwest::Client;
+/// # use quickdid::metrics::NoOpMetricsPublisher;
 /// # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
 /// # let http_client = Client::new();
-/// let base = create_base_resolver(dns_resolver, http_client);
-/// let rate_limited = create_rate_limited_resolver(base, 10);
+/// # let metrics = Arc::new(NoOpMetricsPublisher);
+/// let base = create_base_resolver(dns_resolver, http_client, metrics.clone());
+/// let rate_limited = create_rate_limited_resolver(base, 10, metrics);
 /// # }
 /// ```
 pub fn create_rate_limited_resolver(
     inner: Arc<dyn HandleResolver>,
     max_concurrent: usize,
+    metrics: SharedMetricsPublisher,
 ) -> Arc<dyn HandleResolver> {
-    Arc::new(RateLimitedHandleResolver::new(inner, max_concurrent))
+    Arc::new(RateLimitedHandleResolver::new(inner, max_concurrent, metrics))
 }
 
 /// Create a rate-limited handle resolver with timeout.
···
 /// * `inner` - The resolver to wrap with rate limiting
 /// * `max_concurrent` - Maximum number of concurrent resolutions allowed
 /// * `timeout_ms` - Timeout in milliseconds for acquiring permits (0 = no timeout)
+/// * `metrics` - Metrics publisher for telemetry
 ///
 /// # Returns
 ///
···
 /// # async fn example() {
 /// # use atproto_identity::resolve::HickoryDnsResolver;
 /// # use reqwest::Client;
+/// # use quickdid::metrics::NoOpMetricsPublisher;
 /// # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
 /// # let http_client = Client::new();
-/// let base = create_base_resolver(dns_resolver, http_client);
+/// # let metrics = Arc::new(NoOpMetricsPublisher);
+/// let base = create_base_resolver(dns_resolver, http_client, metrics.clone());
 /// // Rate limit with 10 concurrent resolutions and 5 second timeout
-/// let rate_limited = create_rate_limited_resolver_with_timeout(base, 10, 5000);
+/// let rate_limited = create_rate_limited_resolver_with_timeout(base, 10, 5000, metrics);
 /// # }
 /// ```
 pub fn create_rate_limited_resolver_with_timeout(
     inner: Arc<dyn HandleResolver>,
     max_concurrent: usize,
     timeout_ms: u64,
+    metrics: SharedMetricsPublisher,
 ) -> Arc<dyn HandleResolver> {
     Arc::new(RateLimitedHandleResolver::new_with_timeout(
         inner,
         max_concurrent,
         timeout_ms,
+        metrics,
     ))
 }

src/handle_resolver/redis.rs

···
 use super::errors::HandleResolverError;
 use super::traits::HandleResolver;
 use crate::handle_resolution_result::HandleResolutionResult;
+use crate::metrics::SharedMetricsPublisher;
 use async_trait::async_trait;
 use deadpool_redis::{Pool as RedisPool, redis::AsyncCommands};
 use metrohash::MetroHash64;
···
 /// use std::sync::Arc;
 /// use deadpool_redis::Pool;
 /// use quickdid::handle_resolver::{create_base_resolver, create_redis_resolver, HandleResolver};
+/// use quickdid::metrics::NoOpMetricsPublisher;
 ///
 /// # async fn example() {
 /// # use atproto_identity::resolve::HickoryDnsResolver;
 /// # use reqwest::Client;
 /// # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
 /// # let http_client = Client::new();
-/// # let base_resolver = create_base_resolver(dns_resolver, http_client);
+/// # let metrics = Arc::new(NoOpMetricsPublisher);
+/// # let base_resolver = create_base_resolver(dns_resolver, http_client, metrics.clone());
 /// # let redis_pool: Pool = todo!();
 /// // Create with default 90-day TTL
 /// let resolver = create_redis_resolver(
 ///     base_resolver,
-///     redis_pool
+///     redis_pool,
+///     metrics
 /// );
 /// # }
 /// ```
···
     key_prefix: String,
     /// TTL for cache entries in seconds
     ttl_seconds: u64,
+    /// Metrics publisher for telemetry
+    metrics: SharedMetricsPublisher,
 }
 
 impl RedisHandleResolver {
     /// Create a new Redis-backed handle resolver with default 90-day TTL.
-    fn new(inner: Arc<dyn HandleResolver>, pool: RedisPool) -> Self {
-        Self::with_ttl(inner, pool, 90 * 24 * 60 * 60) // 90 days default
+    fn new(inner: Arc<dyn HandleResolver>, pool: RedisPool, metrics: SharedMetricsPublisher) -> Self {
+        Self::with_ttl(inner, pool, 90 * 24 * 60 * 60, metrics) // 90 days default
     }
 
     /// Create a new Redis-backed handle resolver with custom TTL.
-    fn with_ttl(inner: Arc<dyn HandleResolver>, pool: RedisPool, ttl_seconds: u64) -> Self {
-        Self::with_full_config(inner, pool, "handle:".to_string(), ttl_seconds)
+    fn with_ttl(inner: Arc<dyn HandleResolver>, pool: RedisPool, ttl_seconds: u64, metrics: SharedMetricsPublisher) -> Self {
+        Self::with_full_config(inner, pool, "handle:".to_string(), ttl_seconds, metrics)
     }
 
     /// Create a new Redis-backed handle resolver with full configuration.
···
         pool: RedisPool,
         key_prefix: String,
         ttl_seconds: u64,
+        metrics: SharedMetricsPublisher,
     ) -> Self {
         Self {
             inner,
             pool,
             key_prefix,
             ttl_seconds,
+            metrics,
         }
     }
 
···
                 let cached: Option<Vec<u8>> = match conn.get(&key).await {
                     Ok(value) => value,
                     Err(e) => {
+                        self.metrics.incr("resolver.redis.get_error").await;
                         tracing::warn!("Failed to get handle from Redis cache: {}", e);
                         None
                     }
···
                         Ok(cached_result) => {
                             if let Some(did) = cached_result.to_did() {
                                 tracing::debug!("Cache hit for handle {}: {}", handle, did);
+                                self.metrics.incr("resolver.redis.cache_hit").await;
                                 return Ok((did, cached_result.timestamp));
                             } else {
                                 tracing::debug!("Cache hit (not resolved) for handle {}", handle);
+                                self.metrics.incr("resolver.redis.cache_hit_not_resolved").await;
                                 return Err(HandleResolverError::HandleNotFound);
                             }
                         }
···
                                 handle,
                                 e
                             );
+                            self.metrics.incr("resolver.redis.deserialize_error").await;
                             // Fall through to re-resolve if deserialization fails
                         }
                     }
···
 
                 // Not in cache, resolve through inner resolver
                 tracing::debug!("Cache miss for handle {}, resolving...", handle);
+                self.metrics.incr("resolver.redis.cache_miss").await;
                 let result = self.inner.resolve(s).await;
 
                 // Create and serialize resolution result
···
                             Ok(res) => res,
                             Err(e) => {
                                 tracing::warn!("Failed to create resolution result: {}", e);
+                                self.metrics.incr("resolver.redis.result_create_error").await;
                                 return result;
                             }
                         }
···
                             Ok(res) => res,
                             Err(err) => {
                                 tracing::warn!("Failed to create not_resolved result: {}", err);
+                                self.metrics.incr("resolver.redis.result_create_error").await;
                                 return result;
                             }
                         }
···
                             .await
                         {
                             tracing::warn!("Failed to cache handle resolution in Redis: {}", e);
+                            self.metrics.incr("resolver.redis.cache_set_error").await;
+                        } else {
+                            self.metrics.incr("resolver.redis.cache_set").await;
                         }
                     }
                     Err(e) => {
···
                             handle,
                             e
                         );
+                        self.metrics.incr("resolver.redis.serialize_error").await;
                     }
                 }
 
···
                     "Failed to get Redis connection, falling back to uncached resolution: {}",
                     e
                 );
+                self.metrics.incr("resolver.redis.connection_error").await;
                 self.inner.resolve(s).await
             }
         }
···
 ///
 /// * `inner` - The underlying resolver to use for actual resolution
 /// * `pool` - Redis connection pool
+/// * `metrics` - Metrics publisher for telemetry
 ///
 /// # Example
 ///
···
 /// use std::sync::Arc;
 /// use quickdid::handle_resolver::{create_base_resolver, create_redis_resolver, HandleResolver};
 /// use quickdid::cache::create_redis_pool;
+/// use quickdid::metrics::NoOpMetricsPublisher;
 ///
 /// # async fn example() -> anyhow::Result<()> {
 /// # use atproto_identity::resolve::HickoryDnsResolver;
 /// # use reqwest::Client;
 /// # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
 /// # let http_client = Client::new();
+/// # let metrics = Arc::new(NoOpMetricsPublisher);
 /// let base = create_base_resolver(
 ///     dns_resolver,
 ///     http_client,
+///     metrics.clone(),
 /// );
 ///
 /// let pool = create_redis_pool("redis://localhost:6379")?;
-/// let resolver = create_redis_resolver(base, pool);
+/// let resolver = create_redis_resolver(base, pool, metrics);
 /// let (did, timestamp) = resolver.resolve("alice.bsky.social").await.unwrap();
 /// # Ok(())
 /// # }
···
 pub fn create_redis_resolver(
     inner: Arc<dyn HandleResolver>,
     pool: RedisPool,
+    metrics: SharedMetricsPublisher,
 ) -> Arc<dyn HandleResolver> {
-    Arc::new(RedisHandleResolver::new(inner, pool))
+    Arc::new(RedisHandleResolver::new(inner, pool, metrics))
 }
 
 /// Create a new Redis-backed handle resolver with custom TTL.
···
 /// * `inner` - The underlying resolver to use for actual resolution
 /// * `pool` - Redis connection pool
 /// * `ttl_seconds` - TTL for cache entries in seconds
+/// * `metrics` - Metrics publisher for telemetry
 pub fn create_redis_resolver_with_ttl(
     inner: Arc<dyn HandleResolver>,
     pool: RedisPool,
     ttl_seconds: u64,
+    metrics: SharedMetricsPublisher,
 ) -> Arc<dyn HandleResolver> {
-    Arc::new(RedisHandleResolver::with_ttl(inner, pool, ttl_seconds))
+    Arc::new(RedisHandleResolver::with_ttl(inner, pool, ttl_seconds, metrics))
 }
 
 #[cfg(test)]
···
             expected_did: "did:plc:testuser123".to_string(),
         });
 
+        // Create metrics publisher
+        let metrics = Arc::new(crate::metrics::NoOpMetricsPublisher);
+        
         // Create Redis-backed resolver with a unique key prefix for testing
         let test_prefix = format!(
             "test:handle:{}:",
···
             pool.clone(),
             test_prefix.clone(),
             3600,
+            metrics,
         );
 
         let test_handle = "alice.bsky.social";
···
             expected_did: String::new(),
         });
 
+        // Create metrics publisher
+        let metrics = Arc::new(crate::metrics::NoOpMetricsPublisher);
+        
         // Create Redis-backed resolver with a unique key prefix for testing
         let test_prefix = format!(
             "test:handle:{}:",
···
             pool.clone(),
             test_prefix.clone(),
             3600,
+            metrics,
         );
 
         let test_handle = "error.bsky.social";

src/handle_resolver/sqlite.rs

···
 use super::errors::HandleResolverError;
 use super::traits::HandleResolver;
 use crate::handle_resolution_result::HandleResolutionResult;
+use crate::metrics::SharedMetricsPublisher;
 use async_trait::async_trait;
 use metrohash::MetroHash64;
 use sqlx::{Row, SqlitePool};
···
 /// use std::sync::Arc;
 /// use sqlx::SqlitePool;
 /// use quickdid::handle_resolver::{create_base_resolver, create_sqlite_resolver, HandleResolver};
+/// use quickdid::metrics::NoOpMetricsPublisher;
 ///
 /// # async fn example() {
 /// # use atproto_identity::resolve::HickoryDnsResolver;
 /// # use reqwest::Client;
 /// # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
 /// # let http_client = Client::new();
-/// # let base_resolver = create_base_resolver(dns_resolver, http_client);
+/// # let metrics = Arc::new(NoOpMetricsPublisher);
+/// # let base_resolver = create_base_resolver(dns_resolver, http_client, metrics.clone());
 /// # let sqlite_pool: SqlitePool = todo!();
 /// // Create with default 90-day TTL
 /// let resolver = create_sqlite_resolver(
 ///     base_resolver,
-///     sqlite_pool
+///     sqlite_pool,
+///     metrics
 /// );
 /// # }
 /// ```
···
     pool: SqlitePool,
     /// TTL for cache entries in seconds
     ttl_seconds: u64,
+    /// Metrics publisher for telemetry
+    metrics: SharedMetricsPublisher,
 }
 
 impl SqliteHandleResolver {
     /// Create a new SQLite-backed handle resolver with default 90-day TTL.
-    fn new(inner: Arc<dyn HandleResolver>, pool: SqlitePool) -> Self {
-        Self::with_ttl(inner, pool, 90 * 24 * 60 * 60) // 90 days default
+    fn new(inner: Arc<dyn HandleResolver>, pool: SqlitePool, metrics: SharedMetricsPublisher) -> Self {
+        Self::with_ttl(inner, pool, 90 * 24 * 60 * 60, metrics) // 90 days default
     }
 
     /// Create a new SQLite-backed handle resolver with custom TTL.
-    fn with_ttl(inner: Arc<dyn HandleResolver>, pool: SqlitePool, ttl_seconds: u64) -> Self {
+    fn with_ttl(inner: Arc<dyn HandleResolver>, pool: SqlitePool, ttl_seconds: u64, metrics: SharedMetricsPublisher) -> Self {
         Self {
             inner,
             pool,
             ttl_seconds,
+            metrics,
         }
     }
 
···
                         Ok(cached_result) => {
                             if let Some(did) = cached_result.to_did() {
                                 tracing::debug!("Cache hit for handle {}: {}", handle, did);
+                                self.metrics.incr("resolver.sqlite.cache_hit").await;
                                 return Ok((did, cached_result.timestamp));
                             } else {
                                 tracing::debug!("Cache hit (not resolved) for handle {}", handle);
+                                self.metrics.incr("resolver.sqlite.cache_hit_not_resolved").await;
                                 return Err(HandleResolverError::HandleNotFound);
                             }
                         }
···
                                 handle,
                                 e
                             );
+                            self.metrics.incr("resolver.sqlite.deserialize_error").await;
                             // Fall through to re-resolve if deserialization fails
                         }
                     }
                 } else {
                     tracing::debug!("Cache entry expired for handle {}", handle);
+                    self.metrics.incr("resolver.sqlite.cache_expired").await;
                     // Entry is expired, we'll re-resolve and update it
                 }
             }
             Ok(None) => {
                 tracing::debug!("Cache miss for handle {}, resolving...", handle);
+                self.metrics.incr("resolver.sqlite.cache_miss").await;
             }
             Err(e) => {
                 tracing::warn!("Failed to query SQLite cache for handle {}: {}", handle, e);
+                self.metrics.incr("resolver.sqlite.query_error").await;
                 // Fall through to resolve without caching on database error
             }
         }
···
                     Ok(res) => res,
                     Err(e) => {
                         tracing::warn!("Failed to create resolution result: {}", e);
+                        self.metrics.incr("resolver.sqlite.result_create_error").await;
                         return result;
                     }
                 }
···
                     Ok(res) => res,
                     Err(err) => {
                         tracing::warn!("Failed to create not_resolved result: {}", err);
+                        self.metrics.incr("resolver.sqlite.result_create_error").await;
                         return result;
                     }
                 }
···
 
                 if let Err(e) = query_result {
                     tracing::warn!("Failed to cache handle resolution in SQLite: {}", e);
+                    self.metrics.incr("resolver.sqlite.cache_set_error").await;
+                } else {
+                    self.metrics.incr("resolver.sqlite.cache_set").await;
                 }
             }
             Err(e) => {
···
                     handle,
                     e
                 );
+                self.metrics.incr("resolver.sqlite.serialize_error").await;
             }
         }
 
···
 ///
 /// * `inner` - The underlying resolver to use for actual resolution
 /// * `pool` - SQLite connection pool
+/// * `metrics` - Metrics publisher for telemetry
 ///
 /// # Example
 ///
···
 /// use std::sync::Arc;
 /// use quickdid::handle_resolver::{create_base_resolver, create_sqlite_resolver, HandleResolver};
 /// use quickdid::sqlite_schema::create_sqlite_pool;
+/// use quickdid::metrics::NoOpMetricsPublisher;
 ///
 /// # async fn example() -> anyhow::Result<()> {
 /// # use atproto_identity::resolve::HickoryDnsResolver;
 /// # use reqwest::Client;
 /// # let dns_resolver = Arc::new(HickoryDnsResolver::create_resolver(&[]));
 /// # let http_client = Client::new();
+/// # let metrics = Arc::new(NoOpMetricsPublisher);
 /// let base = create_base_resolver(
 ///     dns_resolver,
 ///     http_client,
+///     metrics.clone(),
 /// );
 ///
 /// let pool = create_sqlite_pool("sqlite:./quickdid.db").await?;
-/// let resolver = create_sqlite_resolver(base, pool);
+/// let resolver = create_sqlite_resolver(base, pool, metrics);
 /// let (did, timestamp) = resolver.resolve("alice.bsky.social").await.unwrap();
 /// # Ok(())
 /// # }
···
 pub fn create_sqlite_resolver(
     inner: Arc<dyn HandleResolver>,
     pool: SqlitePool,
+    metrics: SharedMetricsPublisher,
 ) -> Arc<dyn HandleResolver> {
-    Arc::new(SqliteHandleResolver::new(inner, pool))
+    Arc::new(SqliteHandleResolver::new(inner, pool, metrics))
 }
 
 /// Create a new SQLite-backed handle resolver with custom TTL.
···
 /// * `inner` - The underlying resolver to use for actual resolution
 /// * `pool` - SQLite connection pool
 /// * `ttl_seconds` - TTL for cache entries in seconds
+/// * `metrics` - Metrics publisher for telemetry
 pub fn create_sqlite_resolver_with_ttl(
     inner: Arc<dyn HandleResolver>,
     pool: SqlitePool,
     ttl_seconds: u64,
+    metrics: SharedMetricsPublisher,
 ) -> Arc<dyn HandleResolver> {
-    Arc::new(SqliteHandleResolver::with_ttl(inner, pool, ttl_seconds))
+    Arc::new(SqliteHandleResolver::with_ttl(inner, pool, ttl_seconds, metrics))
 }
 
 #[cfg(test)]
···
             expected_did: "did:plc:testuser123".to_string(),
         });
 
+        // Create metrics publisher
+        let metrics = Arc::new(crate::metrics::NoOpMetricsPublisher);
+        
         // Create SQLite-backed resolver
-        let sqlite_resolver = SqliteHandleResolver::with_ttl(mock_resolver, pool.clone(), 3600);
+        let sqlite_resolver = SqliteHandleResolver::with_ttl(mock_resolver, pool.clone(), 3600, metrics);
 
         let test_handle = "alice.bsky.social";
         let expected_key = sqlite_resolver.make_key(test_handle) as i64;
···
             expected_did: String::new(),
         });
 
+        // Create metrics publisher
+        let metrics = Arc::new(crate::metrics::NoOpMetricsPublisher);
+        
         // Create SQLite-backed resolver
-        let sqlite_resolver = SqliteHandleResolver::with_ttl(mock_resolver, pool.clone(), 3600);
+        let sqlite_resolver = SqliteHandleResolver::with_ttl(mock_resolver, pool.clone(), 3600, metrics);
 
         let test_handle = "error.bsky.social";
         let expected_key = sqlite_resolver.make_key(test_handle) as i64;

src/handle_resolver_task.rs

···
 //! and ensures resolved handles are cached for efficient subsequent lookups.
 
 use crate::handle_resolver::HandleResolver;
+use crate::metrics::SharedMetricsPublisher;
 use crate::queue::{HandleResolutionWork, QueueAdapter};
 use anyhow::Result;
 use std::sync::Arc;
···
     cancel_token: CancellationToken,
     config: HandleResolverTaskConfig,
     metrics: Arc<HandleResolverMetrics>,
+    metrics_publisher: SharedMetricsPublisher,
 }
 
 impl HandleResolverTask {
···
         adapter: Arc<dyn QueueAdapter<HandleResolutionWork>>,
         handle_resolver: Arc<dyn HandleResolver>,
         cancel_token: CancellationToken,
+        metrics_publisher: SharedMetricsPublisher,
     ) -> Self {
         let config = HandleResolverTaskConfig::default();
         Self {
···
             cancel_token,
             config,
             metrics: Arc::new(HandleResolverMetrics::default()),
+            metrics_publisher,
         }
     }
 
···
         handle_resolver: Arc<dyn HandleResolver>,
         cancel_token: CancellationToken,
         config: HandleResolverTaskConfig,
+        metrics_publisher: SharedMetricsPublisher,
     ) -> Self {
         Self {
             adapter,
···
             cancel_token,
             config,
             metrics: Arc::new(HandleResolverMetrics::default()),
+            metrics_publisher,
         }
     }
 
···
             .total_processed
             .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
 
+        // Publish metrics
+        self.metrics_publisher.incr("task.handle_resolution.processed").await;
+        self.metrics_publisher.time("task.handle_resolution.duration_ms", duration_ms).await;
+
         match result {
             Ok(Ok((did, _timestamp))) => {
                 self.metrics
···
                     .total_cached
                     .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
 
+                // Publish success metrics
+                self.metrics_publisher.incr("task.handle_resolution.success").await;
+                self.metrics_publisher.incr("task.handle_resolution.cached").await;
+
                 info!(
                     handle = %work.handle,
                     did = %did,
···
                     .total_failed
                     .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
 
+                // Publish failure metrics
+                self.metrics_publisher.incr("task.handle_resolution.failed").await;
+
                 error!(
                     handle = %work.handle,
                     error = %e,
···
                 self.metrics
                     .total_failed
                     .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+
+                // Publish timeout metrics
+                self.metrics_publisher.incr("task.handle_resolution.timeout").await;
 
                 error!(
                     handle = %work.handle,
···
 /// * `adapter` - Queue adapter for work items
 /// * `handle_resolver` - Handle resolver implementation
 /// * `cancel_token` - Token for graceful shutdown
+/// * `metrics_publisher` - Metrics publisher for telemetry
 pub fn create_handle_resolver_task(
     adapter: Arc<dyn QueueAdapter<HandleResolutionWork>>,
     handle_resolver: Arc<dyn HandleResolver>,
     cancel_token: CancellationToken,
+    metrics_publisher: SharedMetricsPublisher,
 ) -> HandleResolverTaskHandle {
     HandleResolverTaskHandle {
-        task: HandleResolverTask::new(adapter, handle_resolver, cancel_token),
+        task: HandleResolverTask::new(adapter, handle_resolver, cancel_token, metrics_publisher),
     }
 }
 
···
 /// * `handle_resolver` - Handle resolver implementation
 /// * `cancel_token` - Token for graceful shutdown
 /// * `config` - Task configuration
+/// * `metrics_publisher` - Metrics publisher for telemetry
 pub fn create_handle_resolver_task_with_config(
     adapter: Arc<dyn QueueAdapter<HandleResolutionWork>>,
     handle_resolver: Arc<dyn HandleResolver>,
     cancel_token: CancellationToken,
     config: HandleResolverTaskConfig,
+    metrics_publisher: SharedMetricsPublisher,
 ) -> HandleResolverTaskHandle {
     HandleResolverTaskHandle {
-        task: HandleResolverTask::with_config(adapter, handle_resolver, cancel_token, config),
+        task: HandleResolverTask::with_config(adapter, handle_resolver, cancel_token, config, metrics_publisher),
     }
 }
 
···
         // Create cancellation token
         let cancel_token = CancellationToken::new();
 
+        // Create metrics publisher
+        let metrics_publisher = Arc::new(crate::metrics::NoOpMetricsPublisher);
+
         // Create task with custom config
         let config = HandleResolverTaskConfig {
             default_timeout_ms: 5000,
···
             handle_resolver,
             cancel_token.clone(),
             config,
+            metrics_publisher,
         );
 
         // Create handle resolution work

src/http/handle_xrpc_resolve_handle.rs

···
 use crate::{
     handle_resolver::HandleResolver,
     http::AppContext,
+    metrics::SharedMetricsPublisher,
     queue::{HandleResolutionWork, QueueAdapter},
 };
 
···
     State(app_context): State<AppContext>,
     State(handle_resolver): State<Arc<dyn HandleResolver>>,
     State(queue): State<Arc<dyn QueueAdapter<HandleResolutionWork>>>,
+    State(metrics): State<SharedMetricsPublisher>,
 ) -> impl IntoResponse {
     let validating = params.validate.is_some();
     let queueing = params.queue.is_some();
···
     let handle = match params.handle {
         Some(h) => h,
         None => {
+            metrics.incr_with_tags("xrpc.com.atproto.identity.resolveHandle.invalid_handle", &[("reason", "missing")]).await;
             return (
                 StatusCode::BAD_REQUEST,
                 Json(ErrorResponse {
···
         Ok(InputType::Handle(value)) => value,
         Ok(InputType::Plc(_)) | Ok(InputType::Web(_)) => {
             // It's a DID, not a handle
+            metrics.incr_with_tags("xrpc.com.atproto.identity.resolveHandle.invalid_handle", &[("reason", "did")]).await;
             return (
                 StatusCode::BAD_REQUEST,
                 Json(ErrorResponse {
···
                 .into_response();
         }
         Err(_) => {
+            metrics.incr_with_tags("xrpc.com.atproto.identity.resolveHandle.invalid_handle", &[("reason", "error")]).await;
             return (
                 StatusCode::BAD_REQUEST,
                 Json(ErrorResponse {
···
     };
 
     if validating {
+        metrics.incr("xrpc.com.atproto.identity.resolveHandle").await;
         return StatusCode::NO_CONTENT.into_response();
     }
 
···
         // Queue the work
         match queue.push(work).await {
             Ok(()) => {
+                metrics.incr("xrpc.com.atproto.identity.resolveHandle").await;
                 tracing::debug!("Queued handle resolution for {}", handle);
             }
             Err(e) => {
+                metrics.incr("xrpc.com.atproto.identity.resolveHandle.queue_failure").await;
                 tracing::error!("Failed to queue handle resolution: {}", e);
             }
         }
···
     let result = match handle_resolver.resolve(&handle).await {
         Ok((did, timestamp)) => {
             tracing::debug!(handle, did, "Found cached DID for handle");
+
+            metrics.incr_with_tags("handle.resolution.request", &[("success", "1")]).await;
+
             let etag = calculate_etag(&did, app_context.etag_seed());
             ResolutionResult::Success {
                 did,
···
         }
         Err(err) => {
             tracing::debug!(error = ?err, handle, "Error resolving handle");
+            metrics.incr_with_tags("handle.resolution.request", &[("success", "0")]).await;
             let error_content = format!("error:{}:{}", handle, err);
             let etag = calculate_etag(&error_content, app_context.etag_seed());
             let timestamp = SystemTime::now()

src/http/server.rs

···
 use crate::handle_resolver::HandleResolver;
+use crate::metrics::SharedMetricsPublisher;
 use crate::queue::{HandleResolutionWork, QueueAdapter};
 use axum::{
     Router,
-    extract::State,
-    http::StatusCode,
+    extract::{MatchedPath, State},
+    http::{Request, StatusCode},
+    middleware::{self, Next},
     response::{Html, IntoResponse, Json, Response},
     routing::get,
 };
 use serde_json::json;
 use std::sync::Arc;
+use std::time::Instant;
 
 pub(crate) struct InnerAppContext {
     pub(crate) service_document: serde_json::Value,
     pub(crate) service_did: String,
     pub(crate) handle_resolver: Arc<dyn HandleResolver>,
     pub(crate) handle_queue: Arc<dyn QueueAdapter<HandleResolutionWork>>,
+    pub(crate) metrics: SharedMetricsPublisher,
     pub(crate) etag_seed: String,
     pub(crate) cache_control_header: Option<String>,
 }
···
         service_did: String,
         handle_resolver: Arc<dyn HandleResolver>,
         handle_queue: Arc<dyn QueueAdapter<HandleResolutionWork>>,
+        metrics: SharedMetricsPublisher,
         etag_seed: String,
         cache_control_header: Option<String>,
     ) -> Self {
···
             service_did,
             handle_resolver,
             handle_queue,
+            metrics,
             etag_seed,
             cache_control_header,
         }))
···
     handle_queue,
     Arc<dyn QueueAdapter<HandleResolutionWork>>
 );
+impl_from_ref!(AppContext, metrics, SharedMetricsPublisher);
+
+/// Middleware to track HTTP request metrics
+async fn metrics_middleware(
+    State(metrics): State<SharedMetricsPublisher>,
+    matched_path: Option<MatchedPath>,
+    request: Request<axum::body::Body>,
+    next: Next,
+) -> Response {
+    let start = Instant::now();
+    let method = request.method().to_string();
+    let path = matched_path
+        .as_ref()
+        .map(|p| p.as_str().to_string())
+        .unwrap_or_else(|| "unknown".to_string());
+
+    // Process the request
+    let response = next.run(request).await;
+    
+    // Calculate duration
+    let duration_ms = start.elapsed().as_millis() as u64;
+    let status_code = response.status().as_u16().to_string();
+    
+    // Publish metrics with tags
+    metrics.time_with_tags(
+        "http.request.duration_ms",
+        duration_ms,
+        &[
+            ("method", &method),
+            ("path", &path),
+            ("status", &status_code),
+        ],
+    ).await;
+
+    response
+}
 
 pub fn create_router(app_context: AppContext) -> Router {
     Router::new()
···
             get(super::handle_xrpc_resolve_handle::handle_xrpc_resolve_handle)
                 .options(super::handle_xrpc_resolve_handle::handle_xrpc_resolve_handle_options),
         )
+        .layer(middleware::from_fn_with_state(
+            app_context.0.metrics.clone(),
+            metrics_middleware,
+        ))
         .with_state(app_context)
 }
 

src/lib.rs

···
 // Semi-public modules - needed by binary but with limited exposure
 pub mod cache; // Only create_redis_pool exposed
 pub mod handle_resolver_task; // Factory functions and TaskConfig exposed
+pub mod metrics; // Metrics publishing trait and implementations
 pub mod queue; // Queue adapter system with trait and factory functions
 pub mod sqlite_schema; // SQLite schema management functions exposed
 pub mod task_manager; // Only spawn_cancellable_task exposed

src/metrics.rs

···
+use crate::config::Config;
+use async_trait::async_trait;
+use cadence::{BufferedUdpMetricSink, Counted, CountedExt, Gauged, Metric, QueuingMetricSink, StatsdClient, Timed};
+use std::net::UdpSocket;
+use std::sync::Arc;
+use thiserror::Error;
+use tracing::{debug, error};
+
+/// Trait for publishing metrics with counter and gauge support
+/// Designed for minimal compatibility with cadence-style metrics
+#[async_trait]
+pub trait MetricsPublisher: Send + Sync {
+    /// Increment a counter by 1
+    async fn incr(&self, key: &str);
+
+    /// Increment a counter by a specific value
+    async fn count(&self, key: &str, value: u64);
+
+    /// Increment a counter with tags
+    async fn incr_with_tags(&self, key: &str, tags: &[(&str, &str)]);
+
+    /// Increment a counter by a specific value with tags
+    async fn count_with_tags(&self, key: &str, value: u64, tags: &[(&str, &str)]);
+
+    /// Record a gauge value
+    async fn gauge(&self, key: &str, value: u64);
+
+    /// Record a gauge value with tags
+    async fn gauge_with_tags(&self, key: &str, value: u64, tags: &[(&str, &str)]);
+
+    /// Record a timing in milliseconds
+    async fn time(&self, key: &str, millis: u64);
+
+    /// Record a timing with tags
+    async fn time_with_tags(&self, key: &str, millis: u64, tags: &[(&str, &str)]);
+}
+
+/// No-op implementation for development and testing
+#[derive(Debug, Clone, Default)]
+pub struct NoOpMetricsPublisher;
+
+impl NoOpMetricsPublisher {
+    pub fn new() -> Self {
+        Self
+    }
+}
+
+#[async_trait]
+impl MetricsPublisher for NoOpMetricsPublisher {
+    async fn incr(&self, _key: &str) {
+        // No-op
+    }
+
+    async fn count(&self, _key: &str, _value: u64) {
+        // No-op
+    }
+
+    async fn incr_with_tags(&self, _key: &str, _tags: &[(&str, &str)]) {
+        // No-op
+    }
+
+    async fn count_with_tags(&self, _key: &str, _value: u64, _tags: &[(&str, &str)]) {
+        // No-op
+    }
+
+    async fn gauge(&self, _key: &str, _value: u64) {
+        // No-op
+    }
+
+    async fn gauge_with_tags(&self, _key: &str, _value: u64, _tags: &[(&str, &str)]) {
+        // No-op
+    }
+
+    async fn time(&self, _key: &str, _millis: u64) {
+        // No-op
+    }
+
+    async fn time_with_tags(&self, _key: &str, _millis: u64, _tags: &[(&str, &str)]) {
+        // No-op
+    }
+}
+
+/// Statsd-backed metrics publisher using cadence
+pub struct StatsdMetricsPublisher {
+    client: StatsdClient,
+    default_tags: Vec<(String, String)>,
+}
+
+impl StatsdMetricsPublisher {
+    /// Create a new StatsdMetricsPublisher with default configuration
+    pub fn new(host: &str, prefix: &str) -> Result<Self, Box<dyn std::error::Error>> {
+        Self::new_with_tags(host, prefix, vec![])
+    }
+    
+    /// Create a new StatsdMetricsPublisher with default tags
+    pub fn new_with_tags(
+        host: &str, 
+        prefix: &str, 
+        default_tags: Vec<(String, String)>
+    ) -> Result<Self, Box<dyn std::error::Error>> {
+        tracing::info!("Creating StatsdMetricsPublisher: host={}, prefix={}, tags={:?}", host, prefix, default_tags);
+        
+        let socket = UdpSocket::bind("0.0.0.0:0")?;
+        socket.set_nonblocking(true)?;
+        
+        let buffered_sink = BufferedUdpMetricSink::from(host, socket)?;
+        let queuing_sink = QueuingMetricSink::builder()
+            .with_error_handler(move |error| {
+                error!("Failed to send metric via sink: {}", error);
+            })
+            .build(buffered_sink);
+        let client = StatsdClient::from_sink(prefix, queuing_sink);
+        
+        tracing::info!("StatsdMetricsPublisher created successfully");
+        Ok(Self { client, default_tags })
+    }
+    
+    /// Create from an existing StatsdClient
+    pub fn from_client(client: StatsdClient) -> Self {
+        Self::from_client_with_tags(client, vec![])
+    }
+    
+    /// Create from an existing StatsdClient with default tags
+    pub fn from_client_with_tags(client: StatsdClient, default_tags: Vec<(String, String)>) -> Self {
+        Self { client, default_tags }
+    }
+    
+    /// Apply default tags to a builder
+    fn apply_default_tags<'a, M>(&'a self, mut builder: cadence::MetricBuilder<'a, 'a, M>) -> cadence::MetricBuilder<'a, 'a, M> 
+    where
+        M: Metric + From<String>,
+    {
+        for (k, v) in &self.default_tags {
+            builder = builder.with_tag(k.as_str(), v.as_str());
+        }
+        builder
+    }
+}
+
+#[async_trait]
+impl MetricsPublisher for StatsdMetricsPublisher {
+    async fn incr(&self, key: &str) {
+        debug!("Sending metric incr: {}", key);
+        if self.default_tags.is_empty() {
+            match self.client.incr(key) {
+                Ok(_) => debug!("Successfully sent metric: {}", key),
+                Err(e) => error!("Failed to send metric {}: {}", key, e),
+            }
+        } else {
+            let builder = self.client.incr_with_tags(key);
+            let builder = self.apply_default_tags(builder);
+            let _ = builder.send();
+            debug!("Sent metric with tags: {}", key);
+        }
+    }
+
+    async fn count(&self, key: &str, value: u64) {
+        if self.default_tags.is_empty() {
+            let _ = self.client.count(key, value);
+        } else {
+            let builder = self.client.count_with_tags(key, value);
+            let builder = self.apply_default_tags(builder);
+            let _ = builder.send();
+        }
+    }
+
+    async fn incr_with_tags(&self, key: &str, tags: &[(&str, &str)]) {
+        let mut builder = self.client.incr_with_tags(key);
+        builder = self.apply_default_tags(builder);
+        for (k, v) in tags {
+            builder = builder.with_tag(k, v);
+        }
+        let _ = builder.send();
+    }
+
+    async fn count_with_tags(&self, key: &str, value: u64, tags: &[(&str, &str)]) {
+        let mut builder = self.client.count_with_tags(key, value);
+        builder = self.apply_default_tags(builder);
+        for (k, v) in tags {
+            builder = builder.with_tag(k, v);
+        }
+        let _ = builder.send();
+    }
+
+    async fn gauge(&self, key: &str, value: u64) {
+        debug!("Sending metric gauge: {} = {}", key, value);
+        if self.default_tags.is_empty() {
+            match self.client.gauge(key, value) {
+                Ok(_) => debug!("Successfully sent gauge: {} = {}", key, value),
+                Err(e) => error!("Failed to send gauge {} = {}: {}", key, value, e),
+            }
+        } else {
+            let builder = self.client.gauge_with_tags(key, value);
+            let builder = self.apply_default_tags(builder);
+            builder.send();
+            debug!("Sent gauge with tags: {} = {}", key, value);
+        }
+    }
+
+    async fn gauge_with_tags(&self, key: &str, value: u64, tags: &[(&str, &str)]) {
+        let mut builder = self.client.gauge_with_tags(key, value);
+        builder = self.apply_default_tags(builder);
+        for (k, v) in tags {
+            builder = builder.with_tag(k, v);
+        }
+        let _ = builder.send();
+    }
+
+    async fn time(&self, key: &str, millis: u64) {
+        if self.default_tags.is_empty() {
+            let _ = self.client.time(key, millis);
+        } else {
+            let builder = self.client.time_with_tags(key, millis);
+            let builder = self.apply_default_tags(builder);
+            let _ = builder.send();
+        }
+    }
+
+    async fn time_with_tags(&self, key: &str, millis: u64, tags: &[(&str, &str)]) {
+        let mut builder = self.client.time_with_tags(key, millis);
+        builder = self.apply_default_tags(builder);
+        for (k, v) in tags {
+            builder = builder.with_tag(k, v);
+        }
+        let _ = builder.send();
+    }
+}
+
+/// Type alias for shared metrics publisher
+pub type SharedMetricsPublisher = Arc<dyn MetricsPublisher>;
+
+/// Metrics-specific errors
+#[derive(Debug, Error)]
+pub enum MetricsError {
+    /// Failed to create metrics publisher
+    #[error("error-quickdid-metrics-1 Failed to create metrics publisher: {0}")]
+    CreationFailed(String),
+    
+    /// Invalid configuration for metrics
+    #[error("error-quickdid-metrics-2 Invalid metrics configuration: {0}")]
+    InvalidConfig(String),
+}
+
+/// Create a metrics publisher based on configuration
+///
+/// Returns either a no-op publisher or a StatsD publisher based on the
+/// `metrics_adapter` configuration value.
+///
+/// ## Example
+/// 
+/// ```rust,no_run
+/// use quickdid::config::Config;
+/// use quickdid::metrics::create_metrics_publisher;
+/// 
+/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+/// let config = Config::from_env()?;
+/// let metrics = create_metrics_publisher(&config)?;
+/// 
+/// // Use the metrics publisher
+/// metrics.incr("request.count").await;
+/// # Ok(())
+/// # }
+/// ```
+pub fn create_metrics_publisher(config: &Config) -> Result<SharedMetricsPublisher, MetricsError> {
+    match config.metrics_adapter.as_str() {
+        "noop" => {
+            Ok(Arc::new(NoOpMetricsPublisher::new()))
+        }
+        "statsd" => {
+            let host = config.metrics_statsd_host.as_ref()
+                .ok_or_else(|| MetricsError::InvalidConfig(
+                    "METRICS_STATSD_HOST is required when using statsd adapter".to_string()
+                ))?;
+            
+            // Parse tags from comma-separated key:value pairs
+            let default_tags = if let Some(tags_str) = &config.metrics_tags {
+                tags_str
+                    .split(',')
+                    .filter_map(|tag| {
+                        let parts: Vec<&str> = tag.trim().split(':').collect();
+                        if parts.len() == 2 {
+                            Some((parts[0].to_string(), parts[1].to_string()))
+                        } else {
+                            error!("Invalid tag format: {}", tag);
+                            None
+                        }
+                    })
+                    .collect()
+            } else {
+                vec![]
+            };
+            
+            let publisher = StatsdMetricsPublisher::new_with_tags(
+                host,
+                &config.metrics_prefix,
+                default_tags
+            ).map_err(|e| MetricsError::CreationFailed(e.to_string()))?;
+            
+            Ok(Arc::new(publisher))
+        }
+        _ => {
+            Err(MetricsError::InvalidConfig(format!(
+                "Unknown metrics adapter: {}",
+                config.metrics_adapter
+            )))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn test_noop_metrics() {
+        let metrics = NoOpMetricsPublisher::new();
+        
+        // These should all be no-ops and not panic
+        metrics.incr("test.counter").await;
+        metrics.count("test.counter", 5).await;
+        metrics.incr_with_tags("test.counter", &[("env", "test")]).await;
+        metrics.count_with_tags("test.counter", 10, &[("env", "test"), ("service", "quickdid")]).await;
+        metrics.gauge("test.gauge", 100).await;
+        metrics.gauge_with_tags("test.gauge", 200, &[("host", "localhost")]).await;
+        metrics.time("test.timing", 42).await;
+        metrics.time_with_tags("test.timing", 84, &[("endpoint", "/resolve")]).await;
+    }
+
+    #[tokio::test]
+    async fn test_shared_metrics() {
+        let metrics: SharedMetricsPublisher = Arc::new(NoOpMetricsPublisher::new());
+        
+        // Verify it can be used as a shared reference
+        metrics.incr("shared.counter").await;
+        metrics.gauge("shared.gauge", 50).await;
+        
+        // Verify it can be cloned
+        let metrics2 = Arc::clone(&metrics);
+        metrics2.count("cloned.counter", 3).await;
+    }
+    
+    #[test]
+    fn test_create_noop_publisher() {
+        use std::env;
+        
+        // Clean up any existing environment variables first
+        unsafe {
+            env::remove_var("METRICS_ADAPTER");
+            env::remove_var("METRICS_STATSD_HOST");
+            env::remove_var("METRICS_PREFIX");
+            env::remove_var("METRICS_TAGS");
+        }
+        
+        // Set up environment for noop adapter
+        unsafe {
+            env::set_var("HTTP_EXTERNAL", "test.example.com");
+            env::set_var("SERVICE_KEY", "did:key:test");
+            env::set_var("METRICS_ADAPTER", "noop");
+        }
+        
+        let config = Config::from_env().unwrap();
+        let metrics = create_metrics_publisher(&config).unwrap();
+        
+        // Should create successfully - actual type checking happens at compile time
+        assert!(Arc::strong_count(&metrics) == 1);
+        
+        // Clean up
+        unsafe {
+            env::remove_var("METRICS_ADAPTER");
+        }
+    }
+    
+    #[test]
+    fn test_create_statsd_publisher() {
+        use std::env;
+        
+        // Clean up any existing environment variables first
+        unsafe {
+            env::remove_var("METRICS_ADAPTER");
+            env::remove_var("METRICS_STATSD_HOST");
+            env::remove_var("METRICS_PREFIX");
+            env::remove_var("METRICS_TAGS");
+        }
+        
+        // Set up environment for statsd adapter
+        unsafe {
+            env::set_var("HTTP_EXTERNAL", "test.example.com");
+            env::set_var("SERVICE_KEY", "did:key:test");
+            env::set_var("METRICS_ADAPTER", "statsd");
+            env::set_var("METRICS_STATSD_HOST", "localhost:8125");
+            env::set_var("METRICS_PREFIX", "test");
+            env::set_var("METRICS_TAGS", "env:test,service:quickdid");
+        }
+        
+        let config = Config::from_env().unwrap();
+        let metrics = create_metrics_publisher(&config).unwrap();
+        
+        // Should create successfully
+        assert!(Arc::strong_count(&metrics) == 1);
+        
+        // Clean up
+        unsafe {
+            env::remove_var("METRICS_ADAPTER");
+            env::remove_var("METRICS_STATSD_HOST");
+            env::remove_var("METRICS_PREFIX");
+            env::remove_var("METRICS_TAGS");
+        }
+    }
+    
+    #[test]
+    fn test_missing_statsd_host() {
+        use std::env;
+        
+        // Clean up any existing environment variables first
+        unsafe {
+            env::remove_var("METRICS_ADAPTER");
+            env::remove_var("METRICS_STATSD_HOST");
+            env::remove_var("METRICS_PREFIX");
+            env::remove_var("METRICS_TAGS");
+        }
+        
+        // Set up environment for statsd adapter without host
+        unsafe {
+            env::set_var("HTTP_EXTERNAL", "test.example.com");
+            env::set_var("SERVICE_KEY", "did:key:test");
+            env::set_var("METRICS_ADAPTER", "statsd");
+            env::remove_var("METRICS_STATSD_HOST");
+        }
+        
+        let config = Config::from_env().unwrap();
+        let result = create_metrics_publisher(&config);
+        
+        // Should fail with invalid config error
+        assert!(result.is_err());
+        if let Err(e) = result {
+            assert!(matches!(e, MetricsError::InvalidConfig(_)));
+        }
+        
+        // Clean up
+        unsafe {
+            env::remove_var("METRICS_ADAPTER");
+        }
+    }
+    
+    #[test]
+    fn test_invalid_adapter() {
+        use std::env;
+        
+        // Clean up any existing environment variables first
+        unsafe {
+            env::remove_var("METRICS_ADAPTER");
+            env::remove_var("METRICS_STATSD_HOST");
+            env::remove_var("METRICS_PREFIX");
+            env::remove_var("METRICS_TAGS");
+        }
+        
+        // Set up environment with invalid adapter
+        unsafe {
+            env::set_var("HTTP_EXTERNAL", "test.example.com");
+            env::set_var("SERVICE_KEY", "did:key:test");
+            env::set_var("METRICS_ADAPTER", "invalid");
+            env::remove_var("METRICS_STATSD_HOST"); // Clean up from other tests
+        }
+        
+        let config = Config::from_env().unwrap();
+        
+        // Config validation should catch this
+        let validation_result = config.validate();
+        assert!(validation_result.is_err());
+        
+        // Clean up
+        unsafe {
+            env::remove_var("METRICS_ADAPTER");
+        }
+    }
+}