chore: add comments on the Observation module

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

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

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(..)