SimpleLog- Simple, configurable logging

Safe HaskellTrustworthy




SimpleLog is a library for convenient and configurable logging. It uses the usual monad transformer + associated class design: SLogT and MonadSLog.

Example usage:

import System.Log.SLog

main = simpleLog "Example.log" $ do
    logD "Some debugging information"
    logI "This is some other information"
    logW "Something bad is about to happen"
    logE "Something bad happened"

The above sample code when run will produce output similar to this:

2013-10-02 14:17:40 | INFO    | [ThreadId 58] This is some other information
2013-10-02 14:17:40 | WARNING | [ThreadId 58] Something bad is about to happen
2013-10-02 14:17:40 | ERROR   | [ThreadId 58] Something bad happened

Note how the debug line is not displayed. This is because the default configuration (defaultLogConfig) only logs to stdout when the severity is >= INFO. The above code will also append the log lines to the file "Example.log", including the debug line.

The following example shows how one can fine tune SimpleLog as well as how to fork other logging threads.

-- Our log configuration specifies that no ANSI colouring should be used, all log lines
-- should be written to the TChan, and >= INFO severity lines should be written to the
-- stdout synchronously.
logConfig :: TChan LogLine -> LogConfig
logConfig tchan
    = LogConfig { ansiColours = False
                , loggers = [ (anySev, TChanLogger tchan)
                            , ((>= INFO), StdoutLogger Sync)
                            ] }

-- Our custom logging format
logFormat :: Format
logFormat = $(format "%d(%T) (%s) %t: %m")

-- The main thread will fork a child thread, then wait until everything is flushed, then
-- count how many messages have been written in total to the TChan (which will be all
-- messages as our filter passes through everything)
main :: IO ()
main = do
  tchan <- newTChanIO
  (_, fkey) <- runSLogT (logConfig tchan) logFormat "main" $ do
    logS "Main thread started successfully"
    logD "This will not appear on stdout"
    _ <- forkSLog "child" $ do
      logS "I am the child"
      liftIO $ threadDelay 5000000
    logI "Exiting main thread"
  waitFlush fkey
  c <- countTChan tchan
  putStrLn $ show c ++ " messages have been logged in total"

-- Counts the number of elements in the TChan (and pops them all)
countTChan :: TChan a -> IO Int
countTChan tchan = do
  let count = do
        em <- isEmptyTChan tchan
        if em then return 0
        else readTChan tchan >> (1 +) <$> count
  atomically count

The above code when run will produce something like this:

17:35:15 (SUCCESS) main: Main thread started successfully
17:35:15 (SUCCESS) child: I am the child, waiting for 5 seconds...
17:35:15 (INFO   ) main: Exiting main thread
5 messages have been logged in total



data SLogT m a Source

The SLogT monad transformer is simply a ResourceT with an environment


MonadTransControl SLogT 
MonadTrans SLogT 
MonadBase IO m => MonadBase IO (SLogT m) 
MonadBaseControl IO m => MonadBaseControl IO (SLogT m) 
Monad m => Monad (SLogT m) 
Functor m => Functor (SLogT m) 
Applicative m => Applicative (SLogT m) 
(Applicative m, MonadThrow m, MonadUnsafeIO m, MonadIO m) => MonadResource (SLogT m) 
MonadThrow m => MonadThrow (SLogT m) 
MonadIO m => MonadIO (SLogT m) 
MonadIO m => MonadSLog (SLogT m) 
(MonadBaseControl IO m, MonadIO m) => Forkable (SLogT m) (SLogT m) 

type SLog = SLogT IOSource

This is a simple monad for the bottom of one's monad stack.

Running SLogT

runSLogT :: (MonadIO m, MonadThrow m, MonadUnsafeIO m, Applicative m, MonadBaseControl IO m) => LogConfig -> Format -> String -> SLogT m a -> m (a, FlushKey)Source

runSLogT runs an SLogT given a LogConfig, Format and the current thread's name. It returns a FlushKey besides the usual return value.

simpleLog :: (MonadIO m, MonadUnsafeIO m, MonadThrow m, Applicative m, MonadBaseControl IO m) => FilePath -> SLogT m a -> m aSource

simpleLog uses the default configuration with the specified log file name. It also waits using waitFlush until all resources have been released.


data FlushKey Source

A FlushKey is returned when an SLogT is run. You may wait on it with waitFlush.

waitFlush :: FlushKey -> IO ()Source

waitFlush will only return when all resources have been released and all streams have been flushed. Note that this includes resources allocated by the user using the exposed MonadResource instance.

All threads internally accounted for are signaled to exit (they will first finish processing of all remaining jobs) when the SLogT is run, however it is the user's responsibility to shut down threads forked with forkSLog or fork before waitFlush can return.


class MonadIO m => MonadSLog m whereSource

The class of monads that can perform logging


log :: Severity -> Text -> m ()Source

log logs the specified Text with the specified Severity


MonadSLog m => MonadSLog (ResourceT m) 
MonadIO m => MonadSLog (SLogT m) 
MonadSLog m => MonadSLog (ReaderT s m) 
MonadSLog m => MonadSLog (StateT s m) 
(MonadSLog m, Error e) => MonadSLog (ErrorT e m) 
MonadSLog m => MonadSLog (ContT r m) 

Convenience log functions

logD :: MonadSLog m => String -> m ()Source

Log a DEBUG message

logI :: MonadSLog m => String -> m ()Source

Log an INFO message

logS :: MonadSLog m => String -> m ()Source

Log a SUCCESS message

logW :: MonadSLog m => String -> m ()Source

Log a WARNING message

logE :: MonadSLog m => String -> m ()Source

Log an ERROR message


data Logger Source

The Logger type specifies the types of sinks we can log to.


FileLogger Sync FilePath

FileLogger specifies a file to be logged in. Note that symbolic links will be resolved using canonicalizePath when deciding whether two FileLoggers point to the same file.

StdoutLogger Sync

StdoutLogger logs to the stdout

StderrLogger Sync

StderrLogger logs to the stderr

TChanLogger (TChan LogLine)

TChanLogger logs to a specified TChan. Note that LogLines are written instead of the final formatted text. If you wish to use the final text use formatLine.


data Sync Source

Sync is a type to specify whether a logger should log synchronously or asynchronously. Syncronous logging means that the logging thread will block until the message has been written and flushed to the sink. Asynchronous logging means that the logging thread will write to a work queue and move on. The work queue will be read by a dedicated thread that is forked for each sink.




data LogLine Source

LogLine is a log message together with the severity, time of logging and the logging thread's name.




data Severity Source

The type of severities with increasing importance



type Filter = Severity -> BoolSource

Filter is the type of logging filters. Filters may only depend on the Severity.

anySev :: FilterSource

anySev allows all lines to be logged.


data LogConfig Source

LogConfig is the configuration of SLogT




ansiColours :: Bool

Specifies whether ANSI colouring should be used when logging to stdout/stderr

loggers :: [(Filter, Logger)]

The list of loggers together with the associated filters

defaultLogConfig :: FilePath -> LogConfigSource

defaultLogConfig is the default log configuration. It writes all non-DEBUG messages to the stdout synchronously and all messages to a specified file asynchronously.


defaultLogFormat :: FormatSource

The default log format, which currently is $(format "%d(%F %T) | %s | [%t] %m"). See System.Log.SLog.Format for more details on format strings.

Utility functions

forkSLog :: (MonadBaseControl IO m, MonadIO m) => String -> SLogT m () -> SLogT m ThreadIdSource

forkSLog forks an SLogT thread with the specified thread name.

formatLine :: Bool -> Format -> LogLine -> TextSource

formatLine formats the given LogLine using the specified Format. The Boolean determines whether formatLine should insert ANSI colour codes or not.