From 30ca64d8494852064384ac1a49b9bad4088c2630 Mon Sep 17 00:00:00 2001
From: steve-chavez <stevechavezast@gmail.com>
Date: Fri, 24 May 2024 17:13:02 -0500
Subject: [PATCH] docs: improve observability

---
 docs/references/observability.rst | 2 ++
 src/PostgREST/Logger.hs           | 4 +++-
 src/PostgREST/Observation.hs      | 2 +-
 3 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/references/observability.rst b/docs/references/observability.rst
index 687e6ac78..de75c5d79 100644
--- a/docs/references/observability.rst
+++ b/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:
diff --git a/src/PostgREST/Logger.hs b/src/PostgREST/Logger.hs
index 812618926..08ad5b166 100644
--- a/src/PostgREST/Logger.hs
+++ b/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)
diff --git a/src/PostgREST/Observation.hs b/src/PostgREST/Observation.hs
index 2dfd94b22..28cdbf3ef 100644
--- a/src/PostgREST/Observation.hs
+++ b/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(..)