Add multi-package library.

Author: qnikst

cheops-logger.cabal

@@ -3,22 +3,14 @@ name:                cheops-logger
 version:             0.0.1.0
 synopsis:            Structured logger implementation.
 description:
-   Implementation of a very simple structured logger.
-   This logger is provides following functionality:
 
-   * asynchronous background logging (using co-log-concurrent);
-   * structured logging with katip like interface;
-   * handle pattern approach that is compatible with other approaches
-     for effect stucturing.
+   The library implements of a very simple structured logging. This package provides
+   a library that can be used in [co-log](https://hackage.haskell.org/package/co-log)
+   ecosystem. It provides:
 
-   Entry tutorial can be found on GitHub Readme page.
-   
-   Reference documentation can be found in "Cheops.Logger" module.
-
-   Internal module describe details and design choices.
-
-   This logger asynchronously emits json messages to the stdout, of the form, 
-   pretty-printed for convenience:
+     * "Cheops.Logger.Structured" — API for adding structured context to the log messages
+     * "Cheops.Logger.Internal.Writer" — efficient function for dumping logs in the 
+       following format.
 
    @
    { "namespace":"server.package"
@@ -34,6 +26,26 @@ description:
       } 
    }
    @
+   
+   == cheops-logger:instance
+
+   In addition the package provides an @cheops-logger:instance@ library that
+   can be used in the application as-is. The library is provides following
+   functionality:
+
+   * asynchronous background logging using [co-log-concurrent](https://hackage.haskell.org/package/co-log-concurrent);
+   * configuration
+   * optional metrics support
+
+   == References
+
+   Entry tutorial can be found on GitHub Readme page.
+   
+   Reference documentation can be found in "Cheops.Logger" module.
+
+   Internal module describe details and design choices.
+
+   == Notes
 
    The library allows to keep track and output additional user information ("data")
    with the messages. Implement fast and safe API for message output.
@@ -58,14 +70,13 @@ category:            System
 build-type:          Simple
 extra-source-files:  ChangeLog.md
 
-
 library metrics-prometheus
   default-language: Haskell2010
   visibility: public
   exposed-modules:
      Cheops.Logger.Internal.Metric.Prometheus
   reexported-modules:
-     Cheops.Logger.Internal.Metric.Prometheus as Cheops.Logger.Internal.Metrics
+     Cheops.Logger.Internal.Metric.Prometheus as Cheops.Logger.Metrics
   hs-source-dirs: src
   default-extensions:
     OverloadedStrings
@@ -79,17 +90,36 @@ library metrics-noop
   visibility: public
   exposed-modules:
      Cheops.Logger.Internal.Metric.Noop
-  reexported-modules:
-     Cheops.Logger.Internal.Metric.Noop as Cheops.Logger.Internal.Metrics
   hs-source-dirs: src
   default-language: Haskell2010
   build-depends:
     base >= 4.11 && <5
 
 
-library
+library instance
+  visibility: public
+  default-language: Haskell2010
   exposed-modules:
     Cheops.Logger
+  default-extensions:
+    ImportQualifiedPost
+    RecordWildCards
+    OverloadedStrings
+  hs-source-dirs:
+    logger
+  signatures: Cheops.Logger.Metrics
+  build-depends:
+      base >= 4.11 && <5
+    , aeson ^>= 1.5
+    , co-log-core
+    , cheops-logger
+    , co-log-concurrent ^>=0.5
+    , stm ^>=2.5
+  ghc-options: -Wall -Werror
+
+library
+  exposed-modules:
+    Cheops.Logger.Structured
     Cheops.Logger.Internal.Structured
     Cheops.Logger.Internal.Writer
   default-extensions:
@@ -114,10 +144,7 @@ library
     , text ^>=1.2
     , containers ^>=0.6
     , co-log-core ^>=0.2
-    , co-log-concurrent ^>=0.5
     , string-conv ^>=0.1
-    , stm ^>=2.5
-  signatures: Cheops.Logger.Internal.Metrics
   ghc-options: -Wall -Werror
   hs-source-dirs:      src
   default-language:    Haskell2010
@@ -128,6 +155,6 @@ executable Example
   main-is: Main.hs
   build-depends:
     base >=4.11 && <5,
-    cheops-logger,
+    cheops-logger:instance,
     cheops-logger:metrics-prometheus
   default-language: Haskell2010

src/Cheops/Logger.hs renamed to logger/Cheops/Logger.hs

@@ -24,50 +24,23 @@
 module Cheops.Logger
   ( -- * Initialization
     withLogger
-  , emptyLogger
   , defCapacity
   , LoggerConfig(..)
-  , LoggerEnv
-    -- * High level
-    -- ** Writing logs
-    -- $writing-logs
-  , ls
-  , showLS
-  , LogStr(..)
-    -- $writing-helpers
-  , logDebug
-  , logNotice
-  , logInfo
-  , logErr
-  , logWarn
-  , logAlert
-  , logCrit
-  , logEmergency
-  , Severity(..)
-    -- ** Adding context
-    -- $adding-context
-  , addContext
-  , addNamespace
-  , sl
-    -- * Low level
-  , PushContext
-  , logSay
+  , module Cheops.Logger.Structured
     -- * Metrics support
     -- $metrics-support
   -- $setup
   ) where
 
-import Cheops.Logger.Internal.Metrics (flushLog, submitLog)
+import Cheops.Logger.Metrics (flushLog, submitLog)
 import Cheops.Logger.Internal.Structured
 import Cheops.Logger.Internal.Writer
+import Cheops.Logger.Structured
 import Colog.Concurrent
 import Colog.Concurrent.Internal
 import Colog.Core hiding (Severity, Info)
-import Control.Concurrent
 import Data.Aeson
 import System.IO
-import qualified Data.Sequence as Seq
-import qualified Data.Text as T
 
 -- | Logger configuration
 data LoggerConfig = LoggerConfig
@@ -87,13 +60,6 @@ instance FromJSON LoggerConfig where
     n <- o .:? "disabled"
     pure $ LoggerConfig defCapacity n
 
--- | Logger environment, keeps internal Katip environment,
--- current contexts (metadata), namespaces and minimal interesting
--- severity and verbosity.
-data LoggerEnv = LoggerEnv
-  { action :: LogAction IO Message
-  , context :: Seq.Seq Structured
-  }
 
 -- | Create logger and initialize it with defaults.
 withLogger
@@ -108,90 +74,11 @@ withLogger LoggerConfig{..} f
        (LogAction $ flushLog . feed)
        (hFlush stdout)
        $ \(LogAction log_action) ->
-         f $ LoggerEnv
-              (LogAction $ submitLog . log_action)
-              Seq.Empty
+         f $ mkLogger (LogAction $ submitLog . log_action)
   where
     LogAction feed = feedHandle stdout
 
--- | Internal logger function.
-logSay :: LoggerEnv -- ^ Logger handle.
-       -> Severity -- ^ Message severity.
-       -> LogStr -- ^ Message itself.
-       -> IO ()
-logSay (LoggerEnv action context) lvl msg = do
-  tid <- myThreadId
-  unLogAction action $ Message lvl (mkThreadId tid) context msg
-
--- | Logger that does nothing. Useful for the testing purpose.
-emptyLogger :: LoggerEnv
-emptyLogger = LoggerEnv (LogAction $ \_ -> pure ()) Seq.empty
-
--- $adding-context
---
--- Messages in the library forms a stack, and you can attach 2 kinds of data to it:
---
---   1. @namespace@ - a list of locations, that allows to tell that the component
---        is it.
---   2. @context@ - context is a list of key-value pairs, where key is a text and
---        a value is any JSON value.
---
--- When you attach that information to the 'LoggerContext' it will be added to
--- each message that is written in that context. Allowing to analyze data in the
--- external systems.
---
-
--- | Helper to update context, by appending another item to the log.
--- 
--- @
--- local ('addContext' ('sl' "key" "value")) $ do
---   ...
--- @
-addContext
-  :: PushContext -- ^ New data to store
-  -> LoggerEnv   -- ^ Old context.
-  -> LoggerEnv
-addContext (PushContext f) LoggerEnv{..} = LoggerEnv{context = f context, ..}
-
--- | Helper to extend current namespace by appending sub-namespace.
---
--- @
--- local ('addNamespace' "subcomponent") $ do
---   ...
--- @
-addNamespace :: T.Text -> LoggerEnv -> LoggerEnv
-addNamespace ns LoggerEnv{..} = LoggerEnv{context=context Seq.|> Segment ns, ..}
-
--- $writing-logs
--- Logs can we written using one of the following helpers. The general pattern is
---
--- @
--- 'logDebug' logger "message"
--- @
---
--- Messages has type 'LogStr'. This is an abstraction over a data-type for efficient
--- log concatenation. Currently it uses 'Data.Text.Lazy.Builder' but it's an implementation
--- detail and may change in the future.
---
--- 'LogStr' implements 'Data.String.IsString' class, so you can write constant strings
--- without any boilerplate. For other types you should use 'ls' or 'showLS' names are
--- taken from 'Katip' interface.
-
-
--- $writing-helpers
--- Library provides helper for each 'Severity' level.
 
-logDebug, logNotice, logInfo, logWarn,
-  logErr, logAlert, logCrit, logEmergency
-  :: LoggerEnv -> LogStr -> IO ()
-logDebug  x = logSay x DebugS
-logNotice x = logSay x InfoS
-logInfo x = logSay x InfoS
-logWarn x = logSay x WarningS
-logErr x = logSay x ErrorS
-logCrit x = logSay x CriticalS
-logAlert x = logSay x AlertS
-logEmergency x = logSay x EmergencyS
 
 
 -- $metrics-support

src/Cheops/Logger/Internal/Metrics.hsig renamed to logger/Cheops/Logger/Metrics.hsig

@@ -1,3 +1,3 @@
-signature Cheops.Logger.Internal.Metrics where
+signature Cheops.Logger.Metrics where
   flushLog :: IO () -> IO ()
   submitLog ::  IO () -> IO ()