feat(observability): OpenTelemetry golden-signals middleware

.cargo/config.toml

@@ -0,0 +1,5 @@
+# Required by tokio-metrics for runtime instrumentation. Affects all
+# crates in the workspace; only the saturation::tokio_runtime module
+# consumes the additional APIs that this flag unlocks.
+[build]
+rustflags = ["--cfg", "tokio_unstable"]

.gitignore

@@ -41,6 +41,7 @@ test_logs
 # pre-commit config
 .pre-commit-config.yaml
 .cargo
+!.cargo/config.toml
 
 #gradle files
 .gradle

Cargo.toml

@@ -63,13 +63,20 @@ diesel = { version = "2.2.4", package = "juspay_diesel", features = [
 ] }
 fred = { version = "9.2.1" }
 futures-util = "0.3.28"
+humantime = "2.1"
 inventory = "0.3"
 itertools = { version = "0.10.5" }
 jsonlogic = { version = "0.5.5", package = "juspay_jsonlogic" }
 jsonschema = "~0.17"
 leptos = { version = "0.6.11" }
 log = { version = "0.4.20", features = ["kv_unstable_serde"] }
 once_cell = { version = "1.18.0" }
+opentelemetry = { version = "0.27", default-features = false, features = ["metrics"] }
+opentelemetry_sdk = { version = "0.27", default-features = false, features = ["metrics", "rt-tokio"] }
+opentelemetry-prometheus = { version = "0.27", default-features = false }
+opentelemetry-otlp = { version = "0.27", default-features = false, features = ["metrics", "http-proto", "reqwest-client"] }
+opentelemetry-semantic-conventions = { version = "0.27" }
+prometheus = { version = "0.13", default-features = false }
 regex = "1.9.1"
 reqwest = { version = "0.11.18", features = ["json"] }
 rs-snowflake = "0.6.0"
@@ -79,7 +86,9 @@ serde_json = { version = "1.0.140" }
 secrecy = "0.10"
 strum = "0.25"
 strum_macros = "0.25"
+thiserror = "1"
 tokio = { version = "1.29.1", features = ["full"] }
+tokio-metrics = { version = "0.3", default-features = false, features = ["rt"] }
 toml = { version = "0.8.8", features = ["preserve_order"] }
 tracing = "0.1.44"
 tracing-subscriber = { version = "0.3.22", features = [
@@ -100,6 +109,9 @@ superposition_provider = { path = "crates/superposition_provider", version = "0.
 superposition_sdk = { path = "crates/superposition_sdk", version = "0.106.2" }
 service_utils = { path = "crates/service_utils", version = "0.106.2" }
 
+[workspace.lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(tokio_unstable)'] }
+
 [workspace.lints.clippy]
 mod_module_files = "warn"
 manual_range_contains = "allow"

README.md

@@ -150,6 +150,22 @@ Want a broader systems view? Open the [DeepWiki architecture guide](https://deep
 - [Context7 LLM-friendly docs](https://context7.com/juspay/superposition)
 - [DeepWiki repository guide](https://deepwiki.com/juspay/superposition)
 
+## Metrics & observability
+
+The HTTP API exposes Prometheus metrics on `SUPERPOSITION_METRICS_PORT` (default `9091`):
+
+```
+curl http://localhost:9091/metrics
+```
+
+Health endpoints live on the main port: `GET /healthz`, `/livez`, `/readyz`.
+
+**Note on `tokio_unstable`.** The workspace's `.cargo/config.toml` enables
+`--cfg tokio_unstable` so `tokio-metrics` can collect runtime saturation. This
+flag only adds APIs; no behavioural change for existing code. Contributors who
+build outside `cargo` (e.g., custom IDE invocations) should pass the same flag,
+or accept that the `runtime.tokio.*` metrics will be absent.
+
 ## Contributing
 
 We welcome contributions across the platform, clients, docs, and examples.

crates/service_utils/Cargo.toml

@@ -21,12 +21,20 @@ diesel = { workspace = true }
 diesel-adapter = { version = "1.2.0" }
 fred = { workspace = true, features = ["metrics"] }
 futures-util = { workspace = true }
+humantime = { workspace = true }
 inventory = { workspace = true }
 log = { workspace = true }
 once_cell = { workspace = true }
 openidconnect = "3.5.0"
+opentelemetry = { workspace = true }
+opentelemetry_sdk = { workspace = true }
+opentelemetry-otlp = { workspace = true }
+opentelemetry-prometheus = { workspace = true }
+opentelemetry-semantic-conventions = { workspace = true }
+prometheus = { workspace = true }
 rand = "0.8"
 tokio = { workspace = true }
+tokio-metrics = { workspace = true }
 tracing = { workspace = true }
 regex = { workspace = true }
 reqwest = { workspace = true }
@@ -42,6 +50,7 @@ superposition_types = { workspace = true, features = [
     "api",
     "diesel_derives",
 ] }
+thiserror = { workspace = true }
 url = { workspace = true }
 urlencoding = "~2.1.2"
 uuid = {workspace = true}

crates/service_utils/src/lib.rs

@@ -1,10 +1,21 @@
 #![deny(unused_crate_dependencies)]
+// Re-exported so T4+ modules can use them without triggering
+// the `unused_crate_dependencies` lint while no source yet imports them.
+use humantime as _;
+use opentelemetry as _;
+use opentelemetry_otlp as _;
+use opentelemetry_prometheus as _;
+use opentelemetry_sdk as _;
+use opentelemetry_semantic_conventions as _;
+use prometheus as _;
+use tokio_metrics as _;
 pub mod aws;
 pub mod db;
 pub mod encryption;
 pub mod extensions;
 pub mod helpers;
 pub mod middlewares;
+pub mod observability;
 pub mod redis;
 pub mod registry;
 pub mod service;