Di.Df1

This module extends extends the di logging ecosystem with support for the df1 hierarchical structured logging format.

Particularly, it exports df1 for rendering df1-formatted logs, an extension to the Di.Core API with vocabulary specific to df1, and functions like fromDiLog or fromDf1Log to convert back and forth between di and df1 types.

The Di.Df1.Monad module belonging to this same package exports an extension to the Di.Monad API, rather than to Di.Core.

Consider this a preview release: The API is likely to stay stable, but extensive testing, formalization and tooling is due.

Documentation

type Df1 = Di Level Path Message

Convenience type-synonym for a Di restricted to all the df1 monomorphic types.

Df1 == Di Level Path Message
   :: *

This type-synonym is not used within the di-df1 library itself because all functions exposed in the library have more general types. However, users are encouraged to use Df1 if they find it useful to reduce boilerplate and improve type inference.

Hierarchy

push

Arguments

:: Segment

-> Di level Path msg

-> Di level Path msg

Push a new Segment to the Di

Metadata

attr

Arguments

:: ToValue value

=> Key

-> value

-> Di level Path msg

-> Di level Path msg

Push a new attribute Key and Value to the Di.

Logging from IO

debug :: (MonadIO m, ToMessage msg) => Di Level path Message -> msg -> m ()

Log a message intended to be useful only when deliberately debugging a program.

info :: (MonadIO m, ToMessage msg) => Di Level path Message -> msg -> m ()

Log an informational message.

notice :: (MonadIO m, ToMessage msg) => Di Level path Message -> msg -> m ()

Log a condition that is not an error, but should possibly be handled specially.

warning :: (MonadIO m, ToMessage msg) => Di Level path Message -> msg -> m ()

Log a warning condition, such as an exception being gracefully handled or some missing configuration setting being assigned a default value.

error :: (MonadIO m, ToMessage msg) => Di Level path Message -> msg -> m ()

Log an error condition, such as an unhandled exception.

alert :: (MonadIO m, ToMessage msg) => Di Level path Message -> msg -> m ()

Log a condition that should be corrected immediately, such as a corrupted database.

critical :: (MonadIO m, ToMessage msg) => Di Level path Message -> msg -> m ()

Log a critical condition that could result in system failure, such as a disk running out of space.

emergency :: (MonadIO m, ToMessage msg) => Di Level path Message -> msg -> m ()

Log a message stating that the system is unusable.

Type-inference helpers

debug' :: MonadIO m => Di Level path Message -> Message -> m ()

Like debug, but takes a Message rather than any ToMessage.

This helps with type inference in case you are trying to log a literal string and have the OverloadedStrings GHC extension enabled.

info' :: MonadIO m => Di Level path Message -> Message -> m ()

Like info, but takes a Message rather than any ToMessage.

This helps with type inference in case you are trying to log a literal string and have the OverloadedStrings GHC extension enabled.

notice' :: MonadIO m => Di Level path Message -> Message -> m ()

Like notice, but takes a Message rather than any ToMessage.

This helps with type inference in case you are trying to log a literal string and have the OverloadedStrings GHC extension enabled.

warning' :: MonadIO m => Di Level path Message -> Message -> m ()

Like warning, but takes a Message rather than any ToMessage.

This helps with type inference in case you are trying to log a literal string and have the OverloadedStrings GHC extension enabled.

error' :: MonadIO m => Di Level path Message -> Message -> m ()

Like error, but takes a Message rather than any ToMessage.

This helps with type inference in case you are trying to log a literal string and have the OverloadedStrings GHC extension enabled.

alert' :: MonadIO m => Di Level path Message -> Message -> m ()

Like alert, but takes a Message rather than any ToMessage.

This helps with type inference in case you are trying to log a literal string and have the OverloadedStrings GHC extension enabled.

critical' :: MonadIO m => Di Level path Message -> Message -> m ()

Like critical, but takes a Message rather than any ToMessage.

This helps with type inference in case you are trying to log a literal string and have the OverloadedStrings GHC extension enabled.

emergency' :: MonadIO m => Di Level path Message -> Message -> m ()

Like emergency, but takes a Message rather than any ToMessage.

This helps with type inference in case you are trying to log a literal string and have the OverloadedStrings GHC extension enabled.

Logging from STM

debugSTM :: (Monad m, ToMessage msg) => (forall x. STM x -> m x) -> Di Level path Message -> msg -> m ()

Like debug, but can be used from any Monad supporting STM.

infoSTM :: (Monad m, ToMessage msg) => (forall x. STM x -> m x) -> Di Level path Message -> msg -> m ()

Like info, but can be used from any Monad supporting STM.

noticeSTM :: (Monad m, ToMessage msg) => (forall x. STM x -> m x) -> Di Level path Message -> msg -> m ()

Like notice, but can be used from any Monad supporting STM.

warningSTM :: (Monad m, ToMessage msg) => (forall x. STM x -> m x) -> Di Level path Message -> msg -> m ()

Like warning, but can be used from any Monad supporting STM.

errorSTM :: (Monad m, ToMessage msg) => (forall x. STM x -> m x) -> Di Level path Message -> msg -> m ()

Like error, but can be used from any Monad supporting STM.

alertSTM :: (Monad m, ToMessage msg) => (forall x. STM x -> m x) -> Di Level path Message -> msg -> m ()

Like alert, but can be used from any Monad supporting STM.

criticalSTM :: (Monad m, ToMessage msg) => (forall x. STM x -> m x) -> Di Level path Message -> msg -> m ()

Like critical, but can be used from any Monad supporting STM.

emergencySTM :: (Monad m, ToMessage msg) => (forall x. STM x -> m x) -> Di Level path Message -> msg -> m ()

Like emergency, but can be used from any Monad supporting STM.

Support for Di.Handle

df1 :: LineRenderer Level Path Message

A LineRenderer to be used with tools like handle or stderr from the Di.Handle module.

Conversion

fromDiLog :: Log Level Path Message -> Log

Convert a Log from Df1 to a Log from Di.Core.

fromDiLog . fromDf1Log  ==  id

fromDf1Log . fromDiLog  ==  id

fromDf1Log :: Log -> Log Level Path Message

Convert a Log from Di.Core to a Log from Df1.

fromDiLog . fromDf1Log  ==  id

fromDf1Log . fromDiLog  ==  id

Types from Df1

data Level

Instances

Bounded Level

Defined in Df1.Types

Methods

minBound :: Level

maxBound :: Level

Enum Level

Defined in Df1.Types

Methods

succ :: Level -> Level

pred :: Level -> Level

toEnum :: Int -> Level

fromEnum :: Level -> Int

enumFrom :: Level -> [Level]

enumFromThen :: Level -> Level -> [Level]

enumFromTo :: Level -> Level -> [Level]

enumFromThenTo :: Level -> Level -> Level -> [Level]

Eq Level

Defined in Df1.Types

Methods

(==) :: Level -> Level -> Bool

(/=) :: Level -> Level -> Bool

Ord Level

Defined in Df1.Types

Methods

compare :: Level -> Level -> Ordering

(<) :: Level -> Level -> Bool

(<=) :: Level -> Level -> Bool

(>) :: Level -> Level -> Bool

(>=) :: Level -> Level -> Bool

max :: Level -> Level -> Level

min :: Level -> Level -> Level

Show Level

Defined in Df1.Types

Methods

showsPrec :: Int -> Level -> ShowS

show :: Level -> String

showList :: [Level] -> ShowS

data Path

Instances

Eq Path

Defined in Df1.Types

Methods

(==) :: Path -> Path -> Bool

(/=) :: Path -> Path -> Bool

Show Path

Defined in Df1.Types

Methods

showsPrec :: Int -> Path -> ShowS

show :: Path -> String

showList :: [Path] -> ShowS

data Segment

Instances

Eq Segment

Defined in Df1.Types

Methods

(==) :: Segment -> Segment -> Bool

(/=) :: Segment -> Segment -> Bool

Show Segment

Defined in Df1.Types

Methods

showsPrec :: Int -> Segment -> ShowS

show :: Segment -> String

showList :: [Segment] -> ShowS

IsString Segment

Defined in Df1.Types

Methods

fromString :: String -> Segment

Semigroup Segment

Defined in Df1.Types

Methods

(<>) :: Segment -> Segment -> Segment

sconcat :: NonEmpty Segment -> Segment

stimes :: Integral b => b -> Segment -> Segment

Monoid Segment

Defined in Df1.Types

Methods

mempty :: Segment

mappend :: Segment -> Segment -> Segment

mconcat :: [Segment] -> Segment

ToSegment Segment

Defined in Df1.Types

Methods

segment :: Segment -> Segment

class ToSegment a where

Methods

segment :: a -> Segment

Instances

ToSegment Text

Defined in Df1.Types

Methods

segment :: Text -> Segment

ToSegment Text

Defined in Df1.Types

Methods

segment :: Text -> Segment

ToSegment String

Defined in Df1.Types

Methods

segment :: String -> Segment

ToSegment Segment

Defined in Df1.Types

Methods

segment :: Segment -> Segment

data Key

Instances

Eq Key

Defined in Df1.Types

Methods

(==) :: Key -> Key -> Bool

(/=) :: Key -> Key -> Bool

Show Key

Defined in Df1.Types

Methods

showsPrec :: Int -> Key -> ShowS

show :: Key -> String

showList :: [Key] -> ShowS

IsString Key

Defined in Df1.Types

Methods

fromString :: String -> Key

Semigroup Key

Defined in Df1.Types

Methods

(<>) :: Key -> Key -> Key

sconcat :: NonEmpty Key -> Key

stimes :: Integral b => b -> Key -> Key

Monoid Key

Defined in Df1.Types

Methods

mempty :: Key

mappend :: Key -> Key -> Key

mconcat :: [Key] -> Key

ToKey Key

Defined in Df1.Types

Methods

key :: Key -> Key

class ToKey a where

Methods

key :: a -> Key

Instances

ToKey Text

Defined in Df1.Types

Methods

key :: Text -> Key

ToKey Text

Defined in Df1.Types

Methods

key :: Text -> Key

ToKey String

Defined in Df1.Types

Methods

key :: String -> Key

ToKey Key

Defined in Df1.Types

Methods

key :: Key -> Key

data Value

Instances

Eq Value

Defined in Df1.Types

Methods

(==) :: Value -> Value -> Bool

(/=) :: Value -> Value -> Bool

Show Value

Defined in Df1.Types

Methods

showsPrec :: Int -> Value -> ShowS

show :: Value -> String

showList :: [Value] -> ShowS

IsString Value

Defined in Df1.Types

Methods

fromString :: String -> Value

Semigroup Value

Defined in Df1.Types

Methods

(<>) :: Value -> Value -> Value

sconcat :: NonEmpty Value -> Value

stimes :: Integral b => b -> Value -> Value

Monoid Value

Defined in Df1.Types

Methods

mempty :: Value

mappend :: Value -> Value -> Value

mconcat :: [Value] -> Value

ToValue Value

Defined in Df1.Types

Methods

value :: Value -> Value

class ToValue a where

Methods

value :: a -> Value

Instances

ToValue Bool

Defined in Df1.Types

Methods

value :: Bool -> Value

ToValue Double

Defined in Df1.Types

Methods

value :: Double -> Value

ToValue Float

Defined in Df1.Types

Methods

value :: Float -> Value

ToValue Int

Defined in Df1.Types

Methods

value :: Int -> Value

ToValue Int8

Defined in Df1.Types

Methods

value :: Int8 -> Value

ToValue Int16

Defined in Df1.Types

Methods

value :: Int16 -> Value

ToValue Int32

Defined in Df1.Types

Methods

value :: Int32 -> Value

ToValue Int64

Defined in Df1.Types

Methods

value :: Int64 -> Value

ToValue Integer

Defined in Df1.Types

Methods

value :: Integer -> Value

ToValue Natural

Defined in Df1.Types

Methods

value :: Natural -> Value

ToValue Word

Defined in Df1.Types

Methods

value :: Word -> Value

ToValue Word8

Defined in Df1.Types

Methods

value :: Word8 -> Value

ToValue Word16

Defined in Df1.Types

Methods

value :: Word16 -> Value

ToValue Word32

Defined in Df1.Types

Methods

value :: Word32 -> Value

ToValue Word64

Defined in Df1.Types

Methods

value :: Word64 -> Value

ToValue Text

Defined in Df1.Types

Methods

value :: Text -> Value

ToValue Text

Defined in Df1.Types

Methods

value :: Text -> Value

ToValue String

Defined in Df1.Types

Methods

value :: String -> Value

ToValue SomeException

Defined in Df1.Types

Methods

value :: SomeException -> Value

ToValue Value

Defined in Df1.Types

Methods

value :: Value -> Value

data Message

Instances

Eq Message

Defined in Df1.Types

Methods

(==) :: Message -> Message -> Bool

(/=) :: Message -> Message -> Bool

Show Message

Defined in Df1.Types

Methods

showsPrec :: Int -> Message -> ShowS

show :: Message -> String

showList :: [Message] -> ShowS

IsString Message

Defined in Df1.Types

Methods

fromString :: String -> Message

Semigroup Message

Defined in Df1.Types

Methods

(<>) :: Message -> Message -> Message

sconcat :: NonEmpty Message -> Message

stimes :: Integral b => b -> Message -> Message

Monoid Message

Defined in Df1.Types

Methods

mempty :: Message

mappend :: Message -> Message -> Message

mconcat :: [Message] -> Message

ToMessage Message

Defined in Df1.Types

Methods

message :: Message -> Message

class ToMessage a where

Methods

message :: a -> Message

Instances

ToMessage Text

Defined in Df1.Types

Methods

message :: Text -> Message

ToMessage Text

Defined in Df1.Types

Methods

message :: Text -> Message

ToMessage String

Defined in Df1.Types

Methods

message :: String -> Message

ToMessage SomeException

Defined in Df1.Types

Methods

message :: SomeException -> Message

ToMessage Message

Defined in Df1.Types

Methods

message :: Message -> Message