polysemy-log-0.1.0.0: Polysemy effects for logging
Safe HaskellNone
LanguageHaskell2010

Polysemy.Log

Description

 
Synopsis

Introduction

There are at least two libraries that wrap a logging backend with polysemy interpreters. An author of a library who wants to provide log messages faces the problem that committing to a backend requires the user to translate those messages if their chosen backend differs.

polysemy-log provides an abstraction for this task with interpreter adapters for co-log and di.

If you're looking for instructions on how to use polysemy-log with a backend, please visit the haddocks of the adapter libraries:

A program using this library might look like this:

prog :: Member Log r => Sem r ()
prog = do
  Log.debug "starting"
  Log.error "nothing happened"

Arbitrary Data Messages

Logging backends usually don't put any restrictions on the data type that represents a log message, so the adapter effect that faces towards the backend is simply polymorphic in that type.

For complex logging purposes, it would be perfectly valid to use DataLog directly, even though this library focuses on simpler messages:

data ComplexMessage = ComplexMessage { points :: Int, user :: Text }

prog :: Member (DataLog ComplexMessage) r => Sem r ()
prog = do
  dataLog (ComplexMessage 500 "googleson78")

data DataLog a :: Effect where Source #

Adapter for a logging backend.

Usually this is reinterpreted into an effect like those from co-log or di, but it can be used purely for testing. This effect is basically identical to Output and serves only as a nominal component.

Constructors

DataLog :: a -> DataLog a m ()

Schedule an arbitrary value for logging.

Instances

Instances details
type DefiningModule DataLog Source # 
Instance details

Defined in Polysemy.Log.Data.DataLog

type DefiningModule DataLog = "Polysemy.Log.Data.DataLog"

Interpreters

interpretDataLogAtomic' :: forall a r. Member (AtomicState [a]) r => InterpreterFor (DataLog a) r Source #

Interpret DataLog by prepending each message to a list in an AtomicState.

interpretDataLogAtomic :: forall a r. Member (Embed IO) r => InterpretersFor [DataLog a, AtomicState [a]] r Source #

Interpret DataLog by prepending each message to a list in an AtomicState, then interpret the AtomicState in a TVar.

Text Messages with Severity and Metadata

While it would be quite reasonable to handle any kind of complexly structured logging data ergonomically with polysemy, most authors probably prefer not to burden their users with this task while still appreciating the possibility to easily relay debug information in a standardized way.

The default logging effect uses a simple data structure that annotates the given severity and text message with the source location and timestamp:

data LogMessage Source #

User-specified part of the default logging data, consisting of a severity level like warning, error, debug, and a plain text message.

Constructors

LogMessage !Severity !Text 

Instances

Instances details
Eq LogMessage Source # 
Instance details

Defined in Polysemy.Log.Data.LogMessage

Show LogMessage Source # 
Instance details

Defined in Polysemy.Log.Data.LogMessage

data LogEntry a Source #

Metadata wrapper for a log message.

Constructors

LogEntry !a !UTCTime !CallStack 

Instances

Instances details
Show a => Show (LogEntry a) Source # 
Instance details

Defined in Polysemy.Log.Data.LogEntry

Methods

showsPrec :: Int -> LogEntry a -> ShowS #

show :: LogEntry a -> String #

showList :: [LogEntry a] -> ShowS #

data Log :: Effect where Source #

The default high-level effect for simple text messages. To be used with the severity constructors:

import qualified Polysemy.Log as Log

prog = do
  Log.debug "debugging…"
  Log.warn "warning!"

Interpreters should preprocess and relay the message to DataLog.

Constructors

Log :: HasCallStack => LogMessage -> Log m ()

Schedule a message to be logged.

log :: HasCallStack => Member Log r => Severity -> Text -> Sem r () Source #

Log a message with the given severity. Basic Sem constructor.

trace :: HasCallStack => Member Log r => Text -> Sem r () Source #

Log a message with the Trace severity.

debug :: HasCallStack => Member Log r => Text -> Sem r () Source #

Log a message with the Debug severity.

info :: HasCallStack => Member Log r => Text -> Sem r () Source #

Log a message with the Info severity.

warn :: HasCallStack => Member Log r => Text -> Sem r () Source #

Log a message with the Warn severity.

error :: HasCallStack => Member Log r => Text -> Sem r () Source #

Log a message with the Error severity.

crit :: HasCallStack => Member Log r => Text -> Sem r () Source #

Log a message with the Crit severity.

formatLogEntry :: LogEntry LogMessage -> Text Source #

Default formatter for the default message type.

data Severity Source #

A log message's severity, or log level.

Constructors

Trace 
Debug 
Info 
Warn 
Error 
Crit 

Interpreters

interpretLogDataLog :: Members [DataLog (LogEntry LogMessage), GhcTime] r => InterpreterFor Log r Source #

Interpret Log into DataLog, adding metadata information and wrapping with LogEntry.

Since this adds a timestamp, it has a dependency on GhcTime. Use interpretLogDataLog' for a variant that interprets GhcTime in-place.

interpretLogDataLog' :: Member (Embed IO) r => Member (DataLog (LogEntry LogMessage)) r => InterpretersFor [Log, LogMetadata LogMessage, GhcTime] r Source #

Interpret Log into DataLog, adding metadata information and wrapping with LogEntry.

interpretLogNull :: InterpreterFor Log r Source #

Interpret Log by discarding all messages.

interpretLogAtomic :: Member (Embed IO) r => InterpretersFor [Log, AtomicState [LogMessage]] r Source #

Interpret Log by prepending each message to a list in an AtomicState, then interpret the AtomicState in a TVar.

interpretLogAtomic' :: Member (AtomicState [LogMessage]) r => InterpreterFor Log r Source #

Interpret Log by prepending each message to a list in an AtomicState.