From 80a4edbd2dc5b7788f1d7b220cc9b084ba0fab5e Mon Sep 17 00:00:00 2001
From: steve-chavez <stevechavezast@gmail.com>
Date: Fri, 15 Nov 2024 14:58:46 -0500
Subject: [PATCH] chore: add comments on the Observation module

---
 src/PostgREST/Logger.hs      | 1 +
 src/PostgREST/Metrics.hs     | 5 +++++
 src/PostgREST/Observation.hs | 5 ++++-
 3 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/PostgREST/Logger.hs b/src/PostgREST/Logger.hs
index 5e46594bbd..c224f74c79 100644
--- a/src/PostgREST/Logger.hs
+++ b/src/PostgREST/Logger.hs
@@ -75,6 +75,7 @@ middleware logLevel getAuthRole = case logLevel of
       , Wai.destination = Wai.Handle stdout
       }
 
+-- All observations are logged except some that depend on the log-level
 observationLogger :: LoggerState -> LogLevel -> ObservationHandler
 observationLogger loggerState logLevel obs = case obs of
   o@(PoolAcqTimeoutObs _) -> do
diff --git a/src/PostgREST/Metrics.hs b/src/PostgREST/Metrics.hs
index a8a3324e7d..3999e43d83 100644
--- a/src/PostgREST/Metrics.hs
+++ b/src/PostgREST/Metrics.hs
@@ -1,3 +1,7 @@
+{-|
+Module      : PostgREST.Logger
+Description : Metrics based on the Observation module. See Observation.hs.
+-}
 module PostgREST.Metrics
   ( init
   , MetricsState (..)
@@ -28,6 +32,7 @@ init configDbPoolSize = do
   setGauge poolMaxSize (fromIntegral configDbPoolSize)
   pure $ MetricsState poolTimeouts poolAvailable poolWaiting poolMaxSize schemaCacheLoads schemaCacheQueryTime
 
+-- Only some observations are used as metrics
 observationMetrics :: MetricsState -> ObservationHandler
 observationMetrics (MetricsState poolTimeouts poolAvailable poolWaiting _ schemaCacheLoads schemaCacheQueryTime) obs = case obs of
   (PoolAcqTimeoutObs _) -> do
diff --git a/src/PostgREST/Observation.hs b/src/PostgREST/Observation.hs
index 9e9866180b..18fbf558d7 100644
--- a/src/PostgREST/Observation.hs
+++ b/src/PostgREST/Observation.hs
@@ -1,7 +1,10 @@
 {-# LANGUAGE LambdaCase #-}
 {-|
 Module      : PostgREST.Observation
-Description : Observations that can be used for Logging and Metrics
+Description : This module holds an Observation type which is the core of Observability for PostgREST.
+              The Observation and ObservationHandler (the observer) are abstractions that allow centralizing logging and metrics concerns,
+              only observer calls with an Observation constructor are applied at different parts in the codebase.
+              The Logger and Metrics modules then decide which observations to expose. Not all observations need to be logged nor all correspond to a metric.
 -}
 module PostgREST.Observation
   ( Observation(..)