feat: add observability middleware plugin and --trace-sampling CLI flag

- Remove dead x-barbacane-observability extension (was parsed but never used)
- Implement observability as a middleware plugin with:
  - SLO monitoring with violation metrics
  - Detailed request/response logging
  - Per-operation latency histograms
- Add --trace-sampling CLI flag for global trace sampling control (0.0-1.0)
- Update documentation for new middleware-based approach

Author: ndreno

CHANGELOG.md

@@ -62,12 +62,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Type-aware index response separating OpenAPI and AsyncAPI specs
 - Internal `x-barbacane-*` extensions stripped from served specs
 
+#### Plugins
+- New `observability` middleware plugin for per-operation observability:
+  - Latency SLO monitoring with `latency_slo_ms` config
+  - Detailed request/response logging with `detailed_request_logs` and `detailed_response_logs`
+  - Custom latency histogram emission with `emit_latency_histogram`
+  - Emits `barbacane_plugin_observability_slo_violation` counter when SLO exceeded
+
 #### Other
 - HTTP/2 support with automatic protocol detection via ALPN
 - API lifecycle support with `deprecated` flag and `x-sunset` extension (RFC 8594)
 - `Deprecation` and `Sunset` response headers for deprecated routes
 - Fixture-based test specs for comprehensive integration testing
-- SLO violation metrics (`barbacane_slo_violation_total`)
 - Deprecation metrics (`barbacane_deprecated_route_requests_total`)
 
 ### Changed
@@ -79,6 +85,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CORS plugin now includes JSON Schema (`config-schema.json`) for UI configuration
 - Plugin deletion errors now display user-friendly messages in the UI
 
+### Removed
+- `x-barbacane-observability` extension (dead code - was parsed but never used at runtime)
+  - Per-operation observability should be achieved via the middleware plugin system
+  - Global trace sampling remains configurable via `--trace-sampling` CLI flag
+
 ## [0.1.0] - 2026-01-28
 
 ### Added

Cargo.toml

@@ -15,6 +15,7 @@ members = [
 exclude = [
     "plugins/mock",
     "plugins/lambda",
+    "plugins/observability",
 ]
 resolver = "2"
 

crates/barbacane-compiler/src/manifest.rs

@@ -470,7 +470,6 @@ plugins:
                 name: "rate-limit".to_string(),
                 config: serde_json::json!({}),
             }],
-            observability: Default::default(),
             extensions: BTreeMap::new(),
             operations: vec![
                 Operation {
@@ -484,7 +483,6 @@ plugins:
                         config: serde_json::json!({}),
                     }),
                     middlewares: None,
-                    observability: None,
                     deprecated: false,
                     sunset: None,
                     extensions: BTreeMap::new(),
@@ -505,7 +503,6 @@ plugins:
                         name: "jwt-auth@1.0.0".to_string(),
                         config: serde_json::json!({}),
                     }]),
-                    observability: None,
                     deprecated: false,
                     sunset: None,
                     extensions: BTreeMap::new(),
@@ -538,7 +535,6 @@ plugins:
             title: "Test".to_string(),
             api_version: "1.0.0".to_string(),
             global_middlewares: vec![],
-            observability: Default::default(),
             extensions: BTreeMap::new(),
             operations: vec![Operation {
                 path: "/health".to_string(),
@@ -551,7 +547,6 @@ plugins:
                     config: serde_json::json!({}),
                 }),
                 middlewares: None,
-                observability: None,
                 deprecated: false,
                 sunset: None,
                 extensions: BTreeMap::new(),
@@ -583,7 +578,6 @@ plugins:
             title: "Test".to_string(),
             api_version: "1.0.0".to_string(),
             global_middlewares: vec![],
-            observability: Default::default(),
             extensions: BTreeMap::new(),
             operations: vec![Operation {
                 path: "/proxy".to_string(),
@@ -596,7 +590,6 @@ plugins:
                     config: serde_json::json!({}),
                 }),
                 middlewares: None,
-                observability: None,
                 deprecated: false,
                 sunset: None,
                 extensions: BTreeMap::new(),

crates/barbacane-spec-parser/src/lib.rs

@@ -10,6 +10,6 @@ pub mod parser;
 pub use error::ParseError;
 pub use model::{
     ApiSpec, AsyncAction, Channel, ContentSchema, DispatchConfig, Message, MiddlewareConfig,
-    ObservabilityConfig, Operation, Parameter, RequestBody, SpecFormat,
+    Operation, Parameter, RequestBody, SpecFormat,
 };
 pub use parser::{parse_spec, parse_spec_file};

crates/barbacane-spec-parser/src/model.rs

@@ -18,9 +18,6 @@ pub struct ApiSpec {
     pub operations: Vec<Operation>,
     /// Global middlewares from root-level `x-barbacane-middlewares`.
     pub global_middlewares: Vec<MiddlewareConfig>,
-    /// Global observability config from root-level `x-barbacane-observability`.
-    #[serde(default)]
-    pub observability: ObservabilityConfig,
     /// Raw `x-barbacane-*` extensions at root level.
     pub extensions: BTreeMap<String, serde_json::Value>,
 }
@@ -50,9 +47,6 @@ pub struct Operation {
     pub dispatch: Option<DispatchConfig>,
     /// Operation-level middlewares (replaces global chain if present).
     pub middlewares: Option<Vec<MiddlewareConfig>>,
-    /// Operation-level observability config (overrides global).
-    #[serde(default)]
-    pub observability: Option<ObservabilityConfig>,
     /// Whether this operation is deprecated (OpenAPI `deprecated` field).
     #[serde(default)]
     pub deprecated: bool,
@@ -118,23 +112,6 @@ pub struct ContentSchema {
     pub schema: Option<serde_json::Value>,
 }
 
-/// Observability configuration from `x-barbacane-observability`.
-#[derive(Debug, Clone, Default, Serialize, Deserialize)]
-pub struct ObservabilityConfig {
-    /// Override trace sampling rate (0.0 to 1.0).
-    #[serde(default)]
-    pub trace_sampling: Option<f64>,
-
-    /// Enable detailed validation failure logging.
-    #[serde(default)]
-    pub detailed_validation_logs: Option<bool>,
-
-    /// Latency SLO threshold in milliseconds.
-    /// Emit `barbacane_slo_violation_total` metric when exceeded.
-    #[serde(default)]
-    pub latency_slo_ms: Option<u64>,
-}
-
 /// AsyncAPI message definition.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Message {

crates/barbacane-spec-parser/src/parser.rs

@@ -4,8 +4,8 @@ use serde_json::Value;
 
 use crate::error::ParseError;
 use crate::model::{
-    ApiSpec, ContentSchema, DispatchConfig, Message, MiddlewareConfig, ObservabilityConfig,
-    Operation, Parameter, RequestBody, SpecFormat,
+    ApiSpec, ContentSchema, DispatchConfig, Message, MiddlewareConfig, Operation, Parameter,
+    RequestBody, SpecFormat,
 };
 
 /// HTTP methods we recognize in OpenAPI paths.
@@ -50,9 +50,6 @@ pub fn parse_spec(input: &str) -> Result<ApiSpec, ParseError> {
     // Extract global middlewares
     let global_middlewares = extract_middlewares(root_obj);
 
-    // Extract global observability config
-    let observability = extract_observability(root_obj);
-
     // Parse operations based on format
     let operations = match format {
         SpecFormat::OpenApi => parse_openapi_paths(root_obj)?,
@@ -67,7 +64,6 @@ pub fn parse_spec(input: &str) -> Result<ApiSpec, ParseError> {
         api_version,
         operations,
         global_middlewares,
-        observability,
         extensions,
     })
 }
@@ -134,19 +130,6 @@ fn extract_dispatch(obj: &serde_json::Map<String, Value>) -> Option<DispatchConf
         .and_then(|v| serde_json::from_value(v.clone()).ok())
 }
 
-/// Extract x-barbacane-observability from an object.
-fn extract_observability(obj: &serde_json::Map<String, Value>) -> ObservabilityConfig {
-    obj.get("x-barbacane-observability")
-        .and_then(|v| serde_json::from_value(v.clone()).ok())
-        .unwrap_or_default()
-}
-
-/// Extract optional x-barbacane-observability from an object.
-fn extract_observability_opt(obj: &serde_json::Map<String, Value>) -> Option<ObservabilityConfig> {
-    obj.get("x-barbacane-observability")
-        .and_then(|v| serde_json::from_value(v.clone()).ok())
-}
-
 /// Parse OpenAPI 3.x paths into operations.
 fn parse_openapi_paths(
     root: &serde_json::Map<String, Value>,
@@ -195,8 +178,6 @@ fn parse_openapi_paths(
                     None
                 };
 
-                let observability = extract_observability_opt(op_obj);
-
                 // Extract deprecated flag (standard OpenAPI field)
                 let deprecated = op_obj
                     .get("deprecated")
@@ -219,7 +200,6 @@ fn parse_openapi_paths(
                     request_body,
                     dispatch,
                     middlewares,
-                    observability,
                     deprecated,
                     sunset,
                     extensions,
@@ -375,9 +355,6 @@ fn parse_asyncapi_channels(
             None
         };
 
-        // Extract observability
-        let observability = extract_observability_opt(op_obj);
-
         // Extract deprecated and sunset
         let deprecated = op_obj
             .get("deprecated")
@@ -399,7 +376,6 @@ fn parse_asyncapi_channels(
             request_body,
             dispatch,
             middlewares,
-            observability,
             deprecated,
             sunset,
             extensions,
@@ -822,56 +798,6 @@ paths:
         assert!(op.extensions.contains_key("x-barbacane-cache"));
     }
 
-    #[test]
-    fn parse_observability_config() {
-        let yaml = r#"
-openapi: "3.1.0"
-info:
-  title: Test API
-  version: "1.0.0"
-x-barbacane-observability:
-  trace_sampling: 0.1
-  detailed_validation_logs: true
-  latency_slo_ms: 50
-paths:
-  /fast:
-    get:
-      x-barbacane-dispatch:
-        name: mock
-      x-barbacane-observability:
-        trace_sampling: 1.0
-        latency_slo_ms: 10
-  /slow:
-    get:
-      x-barbacane-dispatch:
-        name: mock
-"#;
-        let spec = parse_spec(yaml).unwrap();
-
-        // Check global observability config
-        assert_eq!(spec.observability.trace_sampling, Some(0.1));
-        assert_eq!(spec.observability.detailed_validation_logs, Some(true));
-        assert_eq!(spec.observability.latency_slo_ms, Some(50));
-
-        // Check operation-level override
-        let fast_op = spec
-            .operations
-            .iter()
-            .find(|op| op.path == "/fast")
-            .unwrap();
-        let fast_obs = fast_op.observability.as_ref().unwrap();
-        assert_eq!(fast_obs.trace_sampling, Some(1.0));
-        assert_eq!(fast_obs.latency_slo_ms, Some(10));
-
-        // Check operation without override
-        let slow_op = spec
-            .operations
-            .iter()
-            .find(|op| op.path == "/slow")
-            .unwrap();
-        assert!(slow_op.observability.is_none());
-    }
-
     #[test]
     fn parse_request_body() {
         let yaml = r#"
@@ -1233,40 +1159,4 @@ channels: {}
         let result = parse_spec(yaml);
         assert!(matches!(result, Err(ParseError::SchemaError(_))));
     }
-
-    #[test]
-    fn parse_asyncapi_observability() {
-        let yaml = r#"
-asyncapi: "3.0.0"
-info:
-  title: Observable API
-  version: "1.0.0"
-x-barbacane-observability:
-  trace_sampling: 0.5
-channels:
-  events:
-    address: events
-    messages:
-      Event:
-        payload:
-          type: object
-operations:
-  handleEvent:
-    action: receive
-    channel:
-      $ref: '#/channels/events'
-    x-barbacane-observability:
-      trace_sampling: 1.0
-    x-barbacane-dispatch:
-      name: kafka
-"#;
-        let spec = parse_spec(yaml).unwrap();
-
-        // Global observability
-        assert_eq!(spec.observability.trace_sampling, Some(0.5));
-
-        // Operation-level override
-        let op = &spec.operations[0];
-        assert_eq!(op.observability.as_ref().unwrap().trace_sampling, Some(1.0));
-    }
 }

crates/barbacane-telemetry/src/config.rs

@@ -1,7 +1,5 @@
 //! Telemetry configuration.
 
-use std::time::Duration;
-
 /// Log output format.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
 pub enum LogFormat {
@@ -136,28 +134,3 @@ impl TelemetryConfig {
         self
     }
 }
-
-/// Per-operation observability configuration from `x-barbacane-observability`.
-#[derive(Debug, Clone, Default)]
-pub struct ObservabilityConfig {
-    /// Override trace sampling rate for this operation (0.0 to 1.0).
-    pub trace_sampling: Option<f64>,
-
-    /// Enable detailed validation failure logging.
-    pub detailed_validation_logs: Option<bool>,
-
-    /// Latency SLO threshold. Emit metric when exceeded.
-    pub latency_slo: Option<Duration>,
-}
-
-impl ObservabilityConfig {
-    /// Merge with global config, returning effective sampling rate.
-    pub fn effective_trace_sampling(&self, global: f64) -> f64 {
-        self.trace_sampling.unwrap_or(global)
-    }
-
-    /// Check if detailed validation logs are enabled.
-    pub fn should_log_validation_details(&self) -> bool {
-        self.detailed_validation_logs.unwrap_or(false)
-    }
-}

crates/barbacane-telemetry/src/lib.rs

@@ -25,7 +25,7 @@ pub mod metrics;
 pub mod prometheus;
 pub mod tracing;
 
-pub use config::{LogFormat, ObservabilityConfig, OtlpProtocol, TelemetryConfig};
+pub use config::{LogFormat, OtlpProtocol, TelemetryConfig};
 pub use logging::events;
 pub use metrics::MetricsRegistry;
 pub use prometheus::PROMETHEUS_CONTENT_TYPE;