From 0f95a8bb97ff7334c888f2ab6283dea84ca474b4 Mon Sep 17 00:00:00 2001
From: Mayuresh Nirhali <mayureshnirhali@gmail.com>
Date: Wed, 21 Jan 2026 14:09:06 +0530
Subject: [PATCH] #598 - Fix service observability doc

---
 README.md | 25 ++-----------------------
 SETUP.md  | 34 +++++++++++++++++++++++++++++++---
 2 files changed, 33 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 21f05a6..c727164 100644
--- a/README.md
+++ b/README.md
@@ -64,29 +64,8 @@ The **Beckn Protocol** is an open protocol that enables location-aware, local co
 ### 📊 **Observability**
 - **Structured Logging**: JSON-formatted logs with contextual information
 - **Transaction Tracking**: End-to-end request tracing with unique IDs
-- **OpenTelemetry Metrics**: Pull-based metrics exposed via `/metrics`
-  - RED metrics for every module and action (rate, errors, duration)
-  - Per-step histograms with error attribution
-  - Cache, routing, plugin, and business KPIs (signature/schema validations, Beckn messages)
-  - Native Prometheus exporter with Grafana dashboards & alert rules (`monitoring/`)
-  - Opt-in: add a `plugins.otelsetup` block in your config to wire the `otelsetup` plugin; omit it to run without metrics. Example:
-
-    ```yaml
-    plugins:
-      otelsetup:
-        id: otelsetup
-        config:
-          serviceName: "beckn-onix"
-          serviceVersion: "1.0.0"
-          enableMetrics: "true"
-          environment: "development"
-    ```
-  - **Modular Metrics Architecture**: Metrics are organized by module for better maintainability:
-    - OTel SDK wiring via `otelsetup` plugin
-    - Step execution metrics in `telemetry` package
-    - Handler metrics (signature, schema, routing) in `handler` module
-    - Cache metrics in `cache` plugin
-- **Runtime Instrumentation**: Go runtime + Redis client metrics baked in
+- **OpenTelemetry Metrics**: Performance and business metrics collection
+- **Runtime Instrumentation**: Go runtime + Redis client metrics included
 - **Health Checks**: Liveness and readiness probes for Kubernetes
 
 #### Monitoring Quick Start
diff --git a/SETUP.md b/SETUP.md
index 98e06e0..1f8ff85 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -12,9 +12,10 @@ This comprehensive guide walks you through setting up Beckn-ONIX from developmen
 6. [GUI Component Setup](#gui-component-setup)
 7. [Docker Deployment](#docker-deployment)
 8. [Kubernetes Deployment](#kubernetes-deployment)
-9. [Testing Your Setup](#testing-your-setup)
-10. [Troubleshooting](#troubleshooting)
-11. [Sample Payloads](#sample-payloads)
+9. [Service Observability](#service-ob)
+10. [Testing Your Setup](#testing-your-setup)
+11. [Troubleshooting](#troubleshooting)
+12. [Sample Payloads](#sample-payloads)
 
 ---
 
@@ -1344,6 +1345,33 @@ autoscaling:
 
 ---
 
+## Service Observability
+  - Pull-based metrics exposed via `/metrics`
+  - RED metrics for every module and action (rate, errors, duration)
+  - Per-step histograms with error attribution
+  - Cache, routing, plugin, and business KPIs (signature/schema validations, Beckn messages)
+  - Native Prometheus exporter with Grafana dashboards & alert rules (`monitoring/`)
+  - Opt-in: add a `plugins.otelsetup` block in your config to wire the `otelsetup` plugin; omit it to run without metrics. Example:
+
+    ```yaml
+    plugins:
+      otelsetup:
+        id: otelsetup
+        config:
+          serviceName: "beckn-onix"
+          serviceVersion: "1.0.0"
+          enableMetrics: "true"
+          environment: "development"
+    ```
+### Modular Metrics Architecture**: 
+Metrics are organized by module for better maintainability:
+    - OTel SDK wiring via `otelsetup` plugin
+    - Step execution metrics in `telemetry` package
+    - Handler metrics (signature, schema, routing) in `handler` module
+    - Cache metrics in `cache` plugin
+    
+---
+
 ## Testing Your Setup
 
 ### Health Check