docs: improve observability

docs/references/observability.rst

@@ -3,6 +3,8 @@
 Observability
 #############
 
+Observability allows measuring a system's current state based on the data it generates, such as logs, metrics, and traces.
+
 .. contents::
    :depth: 1
    :local:

src/PostgREST/Logger.hs

@@ -1,7 +1,8 @@
 {-|
 Module      : PostgREST.Logger
-Description : Wai Middleware to log requests to stdout.
+Description : Logging based on the Observation.hs module. Access logs get sent to stdout and server diagnostic get sent to stderr.
 -}
+-- TODO log with buffering enabled to not lose throughput on logging levels higher than LogError
 module PostgREST.Logger
   ( middleware
   , observationLogger
@@ -54,6 +55,7 @@ logWithDebounce loggerState action = do
       putMVar (stateLogDebouncePoolTimeout loggerState) newDebouncer
       newDebouncer
 
+-- TODO stop using this middleware to reuse the same "observer" pattern for all our logs
 middleware :: LogLevel -> (Wai.Request -> Maybe BS.ByteString) -> Wai.Middleware
 middleware logLevel getAuthRole = case logLevel of
   LogCrit  -> requestLogger (const False)

src/PostgREST/Observation.hs

@@ -1,7 +1,7 @@
 {-# LANGUAGE LambdaCase #-}
 {-|
 Module      : PostgREST.Observation
-Description : Module for observability types
+Description : Observations that can be used for Logging and Metrics
 -}
 module PostgREST.Observation
   ( Observation(..)