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.

attr_

Arguments

:: Key

-> Value

-> Di level Path msg

-> Di level Path msg

Like attr, but takes a Value rather than any ToValue.

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

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

debug' :: (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.

info' :: (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.

notice' :: (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.

warning' :: (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.

error' :: (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.

alert' :: (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.

critical' :: (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.

emergency' :: (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

Importance of the logged message.

These levels, listed in increasing order of importance, correspond to the levels used by syslog(3).

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

Order of importance. For example, Emergency is more important than Debug:

Emergency > Debug  ==  True

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

Path represents the hierarchical structure of logged messages.

For example, consider a df1 log line as like the following:

1999-12-20T07:11:39.230553031Z /foo x=a y=b /bar /qux z=c z=d WARNING Something

For that line, the log_path attribute of the Log datatype will contain the following:

[ Push (segment "foo")
, Attr (key "x") (value "a")
, Attr (key "y") (value "b")
, Push (segment "bar")
, Push (segment "qux")
, Attr (key "z") (value "c")
, Attr (key "z") (value "d")
] :: Seq Path

Please notice that [] :: Seq Path is a valid path insofar as df1 is concerned, and that Attr and Push can be juxtapositioned in any order.

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

A path segment.

If you have the OverloadedStrings GHC extension enabled, you can build a Segment using a string literal:

"foo" :: Segment

Otherwise, you can use fromString or segment.

Notice that "" :: Segment is acceptable, and will be correctly rendered and parsed back.

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

Identity.

Defined in Df1.Types

Methods

segment :: Segment -> Segment

class ToSegment a where

Convert an arbitrary type to a Segment.

You are encouraged to create custom ToSegment instances for your types making sure you avoid rendering sensitive details such as passwords, so that they don't accidentally end up in logs.

Any characters that need to be escaped for rendering will be automatically escaped at rendering time. You don't need to escape them here.

Methods

segment :: a -> Segment

Instances

ToSegment Text

x :: Text == unSegment (segment x)

Defined in Df1.Types

Methods

segment :: Text -> Segment

ToSegment Text

x :: Text == toStrict (unSegment (segment x))

Defined in Df1.Types

Methods

segment :: Text -> Segment

ToSegment String

x :: String == unpack (unSegment (segment x))

Defined in Df1.Types

Methods

segment :: String -> Segment

ToSegment Segment

Identity.

Defined in Df1.Types

Methods

segment :: Segment -> Segment

data Key

An attribute key (see Attr).

If you have the OverloadedStrings GHC extension enabled, you can build a Key using a string literal:

"foo" :: Key

Otherwise, you can use fromString or key.

Notice that "" :: Key is acceptable, and will be correctly rendered and parsed back.

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

Identity.

Defined in Df1.Types

Methods

key :: Key -> Key

class ToKey a where

Convert an arbitrary type to a Key.

You are encouraged to create custom ToKey instances for your types making sure you avoid rendering sensitive details such as passwords, so that they don't accidentally end up in logs.

Any characters that need to be escaped for rendering will be automatically escaped at rendering time. You don't need to escape them here.

Methods

key :: a -> Key

Instances

ToKey Text

x :: Text == unKey (key x)

Defined in Df1.Types

Methods

key :: Text -> Key

ToKey Text

x :: Text == toStrict (unKey (key x))

Defined in Df1.Types

Methods

key :: Text -> Key

ToKey String

x :: String == unpack (unKey (key x))

Defined in Df1.Types

Methods

key :: String -> Key

ToKey Key

Identity.

Defined in Df1.Types

Methods

key :: Key -> Key

data Value

An attribute value (see Attr).

If you have the OverloadedStrings GHC extension enabled, you can build a Value using a string literal:

"foo" :: Value

Otherwise, you can use fromString or value.

Notice that "" :: Value is acceptable, and will be correctly rendered and parsed back.

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

Identity.

Defined in Df1.Types

Methods

value :: Value -> Value

class ToValue a where

Convert an arbitrary type to a Value.

You are encouraged to create custom ToValue instances for your types making sure you avoid rendering sensitive details such as passwords, so that they don't accidentally end up in logs.

Any characters that need to be escaped for rendering will be automatically escaped at rendering time. You don't need to escape them here.

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

x :: Text == unValue (value x)

Defined in Df1.Types

Methods

value :: Text -> Value

ToValue Text

x :: Text == toStrict (unValue (value x))

Defined in Df1.Types

Methods

value :: Text -> Value

ToValue String

x :: String == unpack (unValue (value x))

Defined in Df1.Types

Methods

value :: String -> Value

ToValue SomeException

Defined in Df1.Types

Methods

value :: SomeException -> Value

ToValue Value

Identity.

Defined in Df1.Types

Methods

value :: Value -> Value

data Message

A message text.

If you have the OverloadedStrings GHC extension enabled, you can build a Message using a string literal:

"foo" :: Message

Otherwise, you can use fromString or message.

Notice that "" :: Message is acceptable, and will be correctly rendered and parsed back.

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

Identity.

Defined in Df1.Types

Methods

message :: Message -> Message

class ToMessage a where

Convert an arbitrary type to a Message.

You are encouraged to create custom ToMessage instances for your types making sure you avoid rendering sensitive details such as passwords, so that they don't accidentally end up in logs.

Any characters that need to be escaped for rendering will be automatically escaped at rendering time. You don't need to escape them here.

Methods

message :: a -> Message

Instances

ToMessage Text

x :: Text == unMessage (message x)

Defined in Df1.Types

Methods

message :: Text -> Message

ToMessage Text

x :: Text == toStrict (unMessage (message x))

Defined in Df1.Types

Methods

message :: Text -> Message

ToMessage String

x :: String == unpack (unMessage (message x))

Defined in Df1.Types

Methods

message :: String -> Message

ToMessage SomeException

Defined in Df1.Types

Methods

message :: SomeException -> Message

ToMessage Message

Identity.

Defined in Df1.Types

Methods

message :: Message -> Message