✨ feat(observability): add configurable Prometheus metrics endpoint, keep default enabled (#740)

Signed-off-by: samzong <samzong.lu@gmail.com>

Author: samzong

config/config.yaml

@@ -506,6 +506,8 @@ embedding_models:
 
 # Observability Configuration
 observability:
+  metrics:
+    enabled: true  # Set to false to disable the Prometheus /metrics endpoint
   tracing:
     enabled: true  # Enable distributed tracing for docker-compose stack
     provider: "opentelemetry"  # Provider: opentelemetry, openinference, openllmetry

config/observability/config.tracing.yaml

@@ -123,6 +123,8 @@ api:
       enabled: true
 
 observability:
+  metrics:
+    enabled: true  # Set to false to disable the Prometheus /metrics endpoint
   tracing:
     enabled: true
     provider: "opentelemetry"

src/semantic-router/cmd/main.go

@@ -102,15 +102,26 @@ func main() {
 		os.Exit(0)
 	}()
 
-	// Start metrics server
-	go func() {
-		http.Handle("/metrics", promhttp.Handler())
-		metricsAddr := fmt.Sprintf(":%d", *metricsPort)
-		logging.Infof("Starting metrics server on %s", metricsAddr)
-		if metricsErr := http.ListenAndServe(metricsAddr, nil); metricsErr != nil {
-			logging.Errorf("Metrics server error: %v", metricsErr)
-		}
-	}()
+	// Start metrics server if enabled
+	metricsEnabled := true
+	if cfg.Observability.Metrics.Enabled != nil {
+		metricsEnabled = *cfg.Observability.Metrics.Enabled
+	}
+	if *metricsPort <= 0 {
+		metricsEnabled = false
+	}
+	if metricsEnabled {
+		go func() {
+			http.Handle("/metrics", promhttp.Handler())
+			metricsAddr := fmt.Sprintf(":%d", *metricsPort)
+			logging.Infof("Starting metrics server on %s", metricsAddr)
+			if metricsErr := http.ListenAndServe(metricsAddr, nil); metricsErr != nil {
+				logging.Errorf("Metrics server error: %v", metricsErr)
+			}
+		}()
+	} else {
+		logging.Infof("Metrics server disabled")
+	}
 
 	// Create and start the ExtProc server
 	server, err := extproc.NewServer(*configPath, *port, *secure, *certPath)

src/semantic-router/pkg/config/config.go

@@ -262,6 +262,15 @@ type APIConfig struct {
 type ObservabilityConfig struct {
 	// Tracing configuration for distributed tracing
 	Tracing TracingConfig `yaml:"tracing"`
+	// Metrics configuration for Prometheus metrics endpoint
+	Metrics MetricsConfig `yaml:"metrics"`
+}
+
+// MetricsConfig represents configuration for metrics endpoint
+type MetricsConfig struct {
+	// Enabled controls whether the Prometheus metrics endpoint is served
+	// When omitted, defaults to true
+	Enabled *bool `yaml:"enabled,omitempty"`
 }
 
 // TracingConfig represents configuration for distributed tracing

src/semantic-router/pkg/config/config_test.go

@@ -206,6 +206,56 @@ tools:
 			})
 		})
 
+		Context("with observability metrics configuration", func() {
+			It("should default to enabled when metrics block is omitted", func() {
+				configContent := `
+observability:
+  tracing:
+    enabled: false
+`
+				err := os.WriteFile(configFile, []byte(configContent), 0o644)
+				Expect(err).NotTo(HaveOccurred())
+
+				cfg, err := Load(configFile)
+				Expect(err).NotTo(HaveOccurred())
+				Expect(cfg.Observability.Metrics.Enabled).To(BeNil())
+			})
+
+			It("should honor explicit metrics disable flag", func() {
+				configContent := `
+observability:
+  metrics:
+    enabled: false
+  tracing:
+    enabled: false
+`
+				err := os.WriteFile(configFile, []byte(configContent), 0o644)
+				Expect(err).NotTo(HaveOccurred())
+
+				cfg, err := Load(configFile)
+				Expect(err).NotTo(HaveOccurred())
+				Expect(cfg.Observability.Metrics.Enabled).NotTo(BeNil())
+				Expect(*cfg.Observability.Metrics.Enabled).To(BeFalse())
+			})
+
+			It("should honor explicit metrics enable flag", func() {
+				configContent := `
+observability:
+  metrics:
+    enabled: true
+  tracing:
+    enabled: false
+`
+				err := os.WriteFile(configFile, []byte(configContent), 0o644)
+				Expect(err).NotTo(HaveOccurred())
+
+				cfg, err := Load(configFile)
+				Expect(err).NotTo(HaveOccurred())
+				Expect(cfg.Observability.Metrics.Enabled).NotTo(BeNil())
+				Expect(*cfg.Observability.Metrics.Enabled).To(BeTrue())
+			})
+		})
+
 		Context("with invalid YAML syntax", func() {
 			BeforeEach(func() {
 				invalidYAML := `