Merge pull request #5635 from IntersectMBO/jutaro/tracer-docs

trace-dispatcher: documentation

trace-dispatcher/src/Cardano/Logging/Configuration.hs

@@ -42,7 +42,10 @@ import           Cardano.Logging.TraceDispatcherMessage
 import           Cardano.Logging.Types
 
 
--- | Call this function at initialisation, and later for reconfiguration
+-- | Call this function at initialisation, and later for reconfiguration.
+-- Config reflection is used to optimise the tracers and has to collect
+-- information about the tracers. Although it is possible to give more then
+-- one tracer of the same time, it is not a common case to do this.
 configureTracers :: forall a m.
      (MetaTrace a
   ,  MonadIO m)

trace-dispatcher/src/Cardano/Logging/Consistency.hs

@@ -27,7 +27,8 @@ newtype NSLookup = NSLookup (Map.Map T.Text NSLookup)
 --   Warns if namespaces in all namespaces are not unique,
 --   Warns if namespaces in all namespaces are ending in the
 --   middle of another namespace.
---   TODO TRACING: add more checks from documentation
+--   The namespaces in allNamespaces are consistent with the namespaces for the
+--   severityFor, privacyFor, detailsFor, documentFor and metricsDofFor functions.
 checkTraceConfiguration ::
      FilePath
   -> TraceConfig

trace-dispatcher/src/Cardano/Logging/Trace.hs

@@ -315,7 +315,7 @@ contramapM' rFunc =
   Trace $ T.Tracer $ T.emit rFunc
 
 -- | Folds the monadic cata function with acc over a.
--- Uses an IORef to store the state
+-- Uses an MVar to store the state
 foldTraceM :: forall a acc m . (MonadUnliftIO m)
   => (acc -> LoggingContext -> a -> m acc)
   -> acc

trace-dispatcher/src/Cardano/Logging/Tracer/EKG.hs

@@ -21,6 +21,8 @@ import qualified System.Metrics.Label as Label
 import           System.Remote.Monitoring (Server, getCounter, getGauge, getLabel)
 
 
+-- | It is mandatory to construct only one standard tracer in any application!
+-- Throwing away a standard tracer and using a new one will result in an exception
 ekgTracer :: MonadIO m => Either Metrics.Store Server-> m (Trace m FormattedMessage)
 ekgTracer storeOrServer = liftIO $ do
     rgsGauges   <- newMVar Map.empty

trace-dispatcher/src/Cardano/Logging/Tracer/Forward.hs

@@ -18,6 +18,8 @@ import           Cardano.Logging.Types
 
 ---------------------------------------------------------------------------
 
+-- | It is mandatory to construct only one forwardTracer tracer in any application!
+-- Throwing away a forwardTracer tracer and using a new one will result in an exception
 forwardTracer :: forall m. (MonadIO m)
   => ForwardSink TraceObject
   -> Trace m FormattedMessage

trace-dispatcher/src/Cardano/Logging/Types.hs

@@ -393,9 +393,9 @@ data ConfigOption =
     -- | Detail level (default is DNormal)
   | ConfDetail {detail :: DetailLevel}
   -- | To which backend to pass
-  --   Default is [EKGBackend, Forwarder, Stdout HumanFormatColoured]
+  --   Default is [EKGBackend, Forwarder, Stdout MachineFormat]
   | ConfBackend {backends :: [BackendConfig]}
-  -- | Construct a limiter with name (Text) and limiting to the Double,
+  -- | Construct a limiter with limiting to the Double,
   -- which represents frequency in number of messages per second
   | ConfLimiter {maxFrequency :: Double}
   deriving (Eq, Ord, Show, Generic)