Add config validation flag and cache Prometheus metrics (#439)

- Add -t/--test flag for configuration validation without starting server
  - Returns exit code 0 if valid, 1 if invalid
  - Useful for CI/CD pipelines and pre-deployment checks

- Add Prometheus metrics for cache monitoring:
  - dns_cache_hits_total: Total cache hits
  - dns_cache_misses_total: Total cache misses
  - dns_cache_evictions_total: Total cache evictions
  - dns_cache_prefetches_total: Total prefetch operations
  - dns_cache_size{type}: Current cache size (positive/negative)
  - dns_cache_hit_rate: Cache hit rate percentage

- Update README with new flag and cache metrics documentation

Closes #411, Closes #424

Author: semihalev

README.md

@@ -90,6 +90,7 @@ $ make test
 | Flag              | Description                                                                    |
 | ----------------- | ------------------------------------------------------------------------------ |
 | -c, --config PATH | Location of the config file. If it doesn't exist, a new one will be generated. Default: /sdns.conf  |
+| -t, --test        | Test configuration file and exit. Returns exit code 0 if valid, 1 if invalid  |
 | -v, --version     | Show the SDNS version                                                          |
 | -h, --help        | Show help information and exit                                                 |
 
@@ -224,6 +225,33 @@ When `killer_mode` is enabled:
 
 For detailed information, see the [Kubernetes middleware documentation](middleware/kubernetes/README.md).
 
+#### Cache Metrics
+
+SDNS exports comprehensive cache metrics via the Prometheus `/metrics` endpoint for monitoring cache performance.
+
+**Prometheus Metrics:**
+- `dns_cache_hits_total` - Total number of cache hits
+- `dns_cache_misses_total` - Total number of cache misses
+- `dns_cache_evictions_total` - Total number of cache evictions
+- `dns_cache_prefetches_total` - Total number of prefetch operations
+- `dns_cache_size{type="positive|negative"}` - Current number of entries in the cache
+- `dns_cache_hit_rate` - Cache hit rate percentage
+
+**Example Prometheus Queries:**
+```promql
+# Cache hit rate
+dns_cache_hit_rate
+
+# Cache hit ratio (alternative calculation)
+rate(dns_cache_hits_total[5m]) / (rate(dns_cache_hits_total[5m]) + rate(dns_cache_misses_total[5m]))
+
+# Total cache size
+sum(dns_cache_size)
+
+# Cache operations per second
+rate(dns_cache_hits_total[1m]) + rate(dns_cache_misses_total[1m])
+```
+
 ### External Plugins
 
 SDNS supports custom plugins to extend its functionality. The execution order of plugins and middlewares affects their behavior. Configuration keys must be strings, while values can be any type. Plugins are loaded before the cache middleware in the order specified.

middleware/cache/cache.go

@@ -101,6 +101,10 @@ func New(cfg *config.Config) *Cache {
 	c.pcache = c.positive
 	c.ncache = c.negative
 
+	// Register metrics instance for Prometheus hit rate calculation
+	SetMetricsInstance(c.metrics)
+	SetCacheSizeFuncs(c.positive.Len, c.negative.Len)
+
 	return c
 }
 

middleware/cache/prometheus.go

@@ -0,0 +1,90 @@
+package cache
+
+import (
+	"github.com/prometheus/client_golang/prometheus"
+)
+
+var (
+	cacheHits = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "dns_cache_hits_total",
+		Help: "Total number of DNS cache hits",
+	})
+
+	cacheMisses = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "dns_cache_misses_total",
+		Help: "Total number of DNS cache misses",
+	})
+
+	cacheEvictions = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "dns_cache_evictions_total",
+		Help: "Total number of DNS cache evictions",
+	})
+
+	cachePrefetches = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "dns_cache_prefetches_total",
+		Help: "Total number of DNS cache prefetches",
+	})
+
+	cacheSize = prometheus.NewGaugeVec(prometheus.GaugeOpts{
+		Name: "dns_cache_size",
+		Help: "Current number of entries in the DNS cache",
+	}, []string{"type"})
+
+	// cacheHitRate is calculated as hits / (hits + misses) * 100
+	cacheHitRate = prometheus.NewGaugeFunc(prometheus.GaugeOpts{
+		Name: "dns_cache_hit_rate",
+		Help: "DNS cache hit rate percentage",
+	}, calculateHitRate)
+)
+
+// cacheInstance holds references to cache components for metrics
+var (
+	metricsInstance  *CacheMetrics
+	positiveCacheLen func() int
+	negativeCacheLen func() int
+)
+
+func init() {
+	prometheus.MustRegister(cacheHits)
+	prometheus.MustRegister(cacheMisses)
+	prometheus.MustRegister(cacheEvictions)
+	prometheus.MustRegister(cachePrefetches)
+	prometheus.MustRegister(cacheSize)
+	prometheus.MustRegister(cacheHitRate)
+}
+
+// SetMetricsInstance sets the metrics instance for hit rate calculation
+func SetMetricsInstance(m *CacheMetrics) {
+	metricsInstance = m
+}
+
+// SetCacheSizeFuncs sets the functions to get cache sizes
+func SetCacheSizeFuncs(positive, negative func() int) {
+	positiveCacheLen = positive
+	negativeCacheLen = negative
+}
+
+// UpdateCacheSizeMetrics updates the cache size gauges
+func UpdateCacheSizeMetrics() {
+	if positiveCacheLen != nil {
+		cacheSize.WithLabelValues("positive").Set(float64(positiveCacheLen()))
+	}
+	if negativeCacheLen != nil {
+		cacheSize.WithLabelValues("negative").Set(float64(negativeCacheLen()))
+	}
+}
+
+func calculateHitRate() float64 {
+	// Update cache size metrics while calculating hit rate
+	UpdateCacheSizeMetrics()
+
+	if metricsInstance == nil {
+		return 0
+	}
+	hits, misses, _, _ := metricsInstance.Stats()
+	total := float64(hits + misses)
+	if total == 0 {
+		return 0
+	}
+	return float64(hits) / total * 100
+}

middleware/cache/types.go

@@ -261,21 +261,25 @@ type CacheMetrics struct {
 // (*CacheMetrics).Hit hit records a cache hit.
 func (m *CacheMetrics) Hit() {
 	m.hits.Add(1)
+	cacheHits.Inc()
 }
 
 // (*CacheMetrics).Miss miss records a cache miss.
 func (m *CacheMetrics) Miss() {
 	m.misses.Add(1)
+	cacheMisses.Inc()
 }
 
 // (*CacheMetrics).Eviction eviction records a cache eviction.
 func (m *CacheMetrics) Eviction() {
 	m.evictions.Add(1)
+	cacheEvictions.Inc()
 }
 
 // (*CacheMetrics).Prefetch prefetch records a prefetch operation.
 func (m *CacheMetrics) Prefetch() {
 	m.prefetches.Add(1)
+	cachePrefetches.Inc()
 }
 
 // (*CacheMetrics).Stats stats returns current metrics.

sdns.go

@@ -22,8 +22,9 @@ import (
 const version = "1.6.1"
 
 var (
-	cfgPath string
-	cfg     *config.Config
+	cfgPath    string
+	testConfig bool
+	cfg        *config.Config
 
 	rootCmd = &cobra.Command{
 		Use:   "sdns",
@@ -42,6 +43,7 @@ focused on preserving privacy. For more information, visit https://sdns.dev`,
 
 func init() {
 	rootCmd.PersistentFlags().StringVarP(&cfgPath, "config", "c", "sdns.conf", "Location of the config file. If it doesn't exist, a new one will be generated.")
+	rootCmd.PersistentFlags().BoolVarP(&testConfig, "test", "t", false, "Test configuration file and exit. Returns exit code 0 if valid, 1 if invalid.")
 	rootCmd.AddCommand(versionCmd)
 }
 
@@ -86,6 +88,11 @@ func setup() error {
 }
 
 func runServer(cmd *cobra.Command, args []string) error {
+	// Handle config test mode
+	if testConfig {
+		return validateConfiguration()
+	}
+
 	zlog.Info("Starting sdns...", "version", version)
 
 	if err := setup(); err != nil {
@@ -149,6 +156,28 @@ func runServer(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+func validateConfiguration() error {
+	var err error
+
+	if cfg, err = config.Load(cfgPath, version); err != nil {
+		fmt.Fprintf(os.Stderr, "Configuration test failed: %v\n", err)
+		return err
+	}
+
+	// Validate log level
+	switch cfg.LogLevel {
+	case "", "debug", "info", "warn", "error":
+		// Valid log levels
+	default:
+		err := fmt.Errorf("log verbosity level unknown: %s", cfg.LogLevel)
+		fmt.Fprintf(os.Stderr, "Configuration test failed: %v\n", err)
+		return err
+	}
+
+	fmt.Printf("Configuration file %s test successful\n", cfgPath)
+	return nil
+}
+
 func printVersion(cmd *cobra.Command, args []string) {
 	buildInfo, _ := debug.ReadBuildInfo()