Katip.Core

This module is not meant to be imported directly and may contain internal mechanisms that will change without notice.

Documentation

readMay :: Read a => String -> Maybe a

newtype Namespace

Represents a heirarchy of namespaces going from general to specific. For instance: ["processname", "subsystem"]. Note that single-segment namespaces can be created using IsString/OverloadedStrings, so "foo" will result in Namespace ["foo"].

Constructors

Namespace

Fields

• unNamespace :: [Text]

Instances

Eq Namespace

Defined in Katip.Core

Methods

(==) :: Namespace -> Namespace -> Bool

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

Ord Namespace

Defined in Katip.Core

Methods

compare :: Namespace -> Namespace -> Ordering

(<) :: Namespace -> Namespace -> Bool

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

(>) :: Namespace -> Namespace -> Bool

(>=) :: Namespace -> Namespace -> Bool

max :: Namespace -> Namespace -> Namespace

min :: Namespace -> Namespace -> Namespace

Read Namespace

Defined in Katip.Core

Methods

readsPrec :: Int -> ReadS Namespace

readList :: ReadS [Namespace]

readPrec :: ReadPrec Namespace

readListPrec :: ReadPrec [Namespace]

Show Namespace

Defined in Katip.Core

Methods

showsPrec :: Int -> Namespace -> ShowS

show :: Namespace -> String

showList :: [Namespace] -> ShowS

IsString Namespace

Defined in Katip.Core

Methods

fromString :: String -> Namespace

Generic Namespace

Defined in Katip.Core

Associated Types

type Rep Namespace :: Type -> Type

Methods

from :: Namespace -> Rep Namespace x

to :: Rep Namespace x -> Namespace

Semigroup Namespace

Defined in Katip.Core

Methods

(<>) :: Namespace -> Namespace -> Namespace

sconcat :: NonEmpty Namespace -> Namespace

stimes :: Integral b => b -> Namespace -> Namespace

Monoid Namespace

Defined in Katip.Core

Methods

mempty :: Namespace

mappend :: Namespace -> Namespace -> Namespace

mconcat :: [Namespace] -> Namespace

Lift Namespace

Defined in Katip.Core

Methods

lift :: Namespace -> Q Exp

ToJSON Namespace

Defined in Katip.Core

Methods

toJSON :: Namespace -> Value

toEncoding :: Namespace -> Encoding

toJSONList :: [Namespace] -> Value

toEncodingList :: [Namespace] -> Encoding

FromJSON Namespace

Defined in Katip.Core

Methods

parseJSON :: Value -> Parser Namespace

parseJSONList :: Value -> Parser [Namespace]

type Rep Namespace

Defined in Katip.Core

type Rep Namespace = D1 (MetaData "Namespace" "Katip.Core" "katip-0.8.4.0-7DneCQDN77aDRNtrdZcl08" True) (C1 (MetaCons "Namespace" PrefixI True) (S1 (MetaSel (Just "unNamespace") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [Text])))

intercalateNs :: Namespace -> [Text]

Ready namespace for emission with dots to join the segments.

newtype Environment

Application environment, like prod, devel, testing.

Constructors

Environment

Fields

• getEnvironment :: Text

Instances

Eq Environment

Defined in Katip.Core

Methods

(==) :: Environment -> Environment -> Bool

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

Ord Environment

Defined in Katip.Core

Methods

compare :: Environment -> Environment -> Ordering

(<) :: Environment -> Environment -> Bool

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

(>) :: Environment -> Environment -> Bool

(>=) :: Environment -> Environment -> Bool

max :: Environment -> Environment -> Environment

min :: Environment -> Environment -> Environment

Read Environment

Defined in Katip.Core

Methods

readsPrec :: Int -> ReadS Environment

readList :: ReadS [Environment]

readPrec :: ReadPrec Environment

readListPrec :: ReadPrec [Environment]

Show Environment

Defined in Katip.Core

Methods

showsPrec :: Int -> Environment -> ShowS

show :: Environment -> String

showList :: [Environment] -> ShowS

IsString Environment

Defined in Katip.Core

Methods

fromString :: String -> Environment

Generic Environment

Defined in Katip.Core

Associated Types

type Rep Environment :: Type -> Type

Methods

from :: Environment -> Rep Environment x

to :: Rep Environment x -> Environment

ToJSON Environment

Defined in Katip.Core

Methods

toJSON :: Environment -> Value

toEncoding :: Environment -> Encoding

toJSONList :: [Environment] -> Value

toEncodingList :: [Environment] -> Encoding

FromJSON Environment

Defined in Katip.Core

Methods

parseJSON :: Value -> Parser Environment

parseJSONList :: Value -> Parser [Environment]

type Rep Environment

Defined in Katip.Core

type Rep Environment = D1 (MetaData "Environment" "Katip.Core" "katip-0.8.4.0-7DneCQDN77aDRNtrdZcl08" True) (C1 (MetaCons "Environment" PrefixI True) (S1 (MetaSel (Just "getEnvironment") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Text)))

data Severity

Constructors

DebugS

Debug messages

InfoS

Information

NoticeS

Normal runtime Conditions

WarningS

General Warnings

ErrorS

General Errors

CriticalS

Severe situations

AlertS

Take immediate action

EmergencyS

System is unusable

Instances

Bounded Severity

Defined in Katip.Core

Methods

minBound :: Severity

maxBound :: Severity

Enum Severity

Defined in Katip.Core

Methods

succ :: Severity -> Severity

pred :: Severity -> Severity

toEnum :: Int -> Severity

fromEnum :: Severity -> Int

enumFrom :: Severity -> [Severity]

enumFromThen :: Severity -> Severity -> [Severity]

enumFromTo :: Severity -> Severity -> [Severity]

enumFromThenTo :: Severity -> Severity -> Severity -> [Severity]

Eq Severity

Defined in Katip.Core

Methods

(==) :: Severity -> Severity -> Bool

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

Ord Severity

Defined in Katip.Core

Methods

compare :: Severity -> Severity -> Ordering

(<) :: Severity -> Severity -> Bool

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

(>) :: Severity -> Severity -> Bool

(>=) :: Severity -> Severity -> Bool

max :: Severity -> Severity -> Severity

min :: Severity -> Severity -> Severity

Read Severity

Defined in Katip.Core

Methods

readsPrec :: Int -> ReadS Severity

readList :: ReadS [Severity]

readPrec :: ReadPrec Severity

readListPrec :: ReadPrec [Severity]

Show Severity

Defined in Katip.Core

Methods

showsPrec :: Int -> Severity -> ShowS

show :: Severity -> String

showList :: [Severity] -> ShowS

Generic Severity

Defined in Katip.Core

Associated Types

type Rep Severity :: Type -> Type

Methods

from :: Severity -> Rep Severity x

to :: Rep Severity x -> Severity

Lift Severity

Defined in Katip.Core

Methods

lift :: Severity -> Q Exp

ToJSON Severity

Defined in Katip.Core

Methods

toJSON :: Severity -> Value

toEncoding :: Severity -> Encoding

toJSONList :: [Severity] -> Value

toEncodingList :: [Severity] -> Encoding

FromJSON Severity

Defined in Katip.Core

Methods

parseJSON :: Value -> Parser Severity

parseJSONList :: Value -> Parser [Severity]

type Rep Severity

Defined in Katip.Core

type Rep Severity = D1 (MetaData "Severity" "Katip.Core" "katip-0.8.4.0-7DneCQDN77aDRNtrdZcl08" False) (((C1 (MetaCons "DebugS" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "InfoS" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "NoticeS" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "WarningS" PrefixI False) (U1 :: Type -> Type))) :+: ((C1 (MetaCons "ErrorS" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "CriticalS" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "AlertS" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "EmergencyS" PrefixI False) (U1 :: Type -> Type))))

data Verbosity

Verbosity controls the amount of information (columns) a Scribe emits during logging.

The convention is: - V0 implies no additional payload information is included in message. - V3 implies the maximum amount of payload information. - Anything in between is left to the discretion of the developer.

Constructors

V0

V1

V2

V3

Instances

Bounded Verbosity

Defined in Katip.Core

Methods

minBound :: Verbosity

maxBound :: Verbosity

Enum Verbosity

Defined in Katip.Core

Methods

succ :: Verbosity -> Verbosity

pred :: Verbosity -> Verbosity

toEnum :: Int -> Verbosity

fromEnum :: Verbosity -> Int

enumFrom :: Verbosity -> [Verbosity]

enumFromThen :: Verbosity -> Verbosity -> [Verbosity]

enumFromTo :: Verbosity -> Verbosity -> [Verbosity]

enumFromThenTo :: Verbosity -> Verbosity -> Verbosity -> [Verbosity]

Eq Verbosity

Defined in Katip.Core

Methods

(==) :: Verbosity -> Verbosity -> Bool

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

Ord Verbosity

Defined in Katip.Core

Methods

compare :: Verbosity -> Verbosity -> Ordering

(<) :: Verbosity -> Verbosity -> Bool

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

(>) :: Verbosity -> Verbosity -> Bool

(>=) :: Verbosity -> Verbosity -> Bool

max :: Verbosity -> Verbosity -> Verbosity

min :: Verbosity -> Verbosity -> Verbosity

Read Verbosity

Defined in Katip.Core

Methods

readsPrec :: Int -> ReadS Verbosity

readList :: ReadS [Verbosity]

readPrec :: ReadPrec Verbosity

readListPrec :: ReadPrec [Verbosity]

Show Verbosity

Defined in Katip.Core

Methods

showsPrec :: Int -> Verbosity -> ShowS

show :: Verbosity -> String

showList :: [Verbosity] -> ShowS

Generic Verbosity

Defined in Katip.Core

Associated Types

type Rep Verbosity :: Type -> Type

Methods

from :: Verbosity -> Rep Verbosity x

to :: Rep Verbosity x -> Verbosity

Lift Verbosity

Defined in Katip.Core

Methods

lift :: Verbosity -> Q Exp

ToJSON Verbosity

Defined in Katip.Core

Methods

toJSON :: Verbosity -> Value

toEncoding :: Verbosity -> Encoding

toJSONList :: [Verbosity] -> Value

toEncodingList :: [Verbosity] -> Encoding

FromJSON Verbosity

Defined in Katip.Core

Methods

parseJSON :: Value -> Parser Verbosity

parseJSONList :: Value -> Parser [Verbosity]

type Rep Verbosity

Defined in Katip.Core

type Rep Verbosity = D1 (MetaData "Verbosity" "Katip.Core" "katip-0.8.4.0-7DneCQDN77aDRNtrdZcl08" False) ((C1 (MetaCons "V0" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "V1" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "V2" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "V3" PrefixI False) (U1 :: Type -> Type)))

renderSeverity :: Severity -> Text

textToSeverity :: Text -> Maybe Severity

newtype LogStr

Log message with Builder underneath; use <> to concat in O(1).

Constructors

LogStr

Fields

• unLogStr :: Builder

Instances

Eq LogStr

Defined in Katip.Core

Methods

(==) :: LogStr -> LogStr -> Bool

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

Show LogStr

Defined in Katip.Core

Methods

showsPrec :: Int -> LogStr -> ShowS

show :: LogStr -> String

showList :: [LogStr] -> ShowS

IsString LogStr

Defined in Katip.Core

Methods

fromString :: String -> LogStr

Generic LogStr

Defined in Katip.Core

Associated Types

type Rep LogStr :: Type -> Type

Methods

from :: LogStr -> Rep LogStr x

to :: Rep LogStr x -> LogStr

Semigroup LogStr

Defined in Katip.Core

Methods

(<>) :: LogStr -> LogStr -> LogStr

sconcat :: NonEmpty LogStr -> LogStr

stimes :: Integral b => b -> LogStr -> LogStr

Monoid LogStr

Defined in Katip.Core

Methods

mempty :: LogStr

mappend :: LogStr -> LogStr -> LogStr

mconcat :: [LogStr] -> LogStr

FromJSON LogStr

Defined in Katip.Core

Methods

parseJSON :: Value -> Parser LogStr

parseJSONList :: Value -> Parser [LogStr]

type Rep LogStr

Defined in Katip.Core

type Rep LogStr = D1 (MetaData "LogStr" "Katip.Core" "katip-0.8.4.0-7DneCQDN77aDRNtrdZcl08" True) (C1 (MetaCons "LogStr" PrefixI True) (S1 (MetaSel (Just "unLogStr") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Builder)))

logStr :: StringConv a Text => a -> LogStr

Pack any string-like thing into a LogStr. This will automatically work on String, ByteString, Text and any of the lazy variants.

ls :: StringConv a Text => a -> LogStr

Shorthand for logStr

showLS :: Show a => a -> LogStr

Convert any showable type into a LogStr.

newtype ThreadIdText

Constructors

ThreadIdText

Fields

• getThreadIdText :: Text

Instances

Eq ThreadIdText

Defined in Katip.Core

Methods

(==) :: ThreadIdText -> ThreadIdText -> Bool

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

Ord ThreadIdText

Defined in Katip.Core

Methods

compare :: ThreadIdText -> ThreadIdText -> Ordering

(<) :: ThreadIdText -> ThreadIdText -> Bool

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

(>) :: ThreadIdText -> ThreadIdText -> Bool

(>=) :: ThreadIdText -> ThreadIdText -> Bool

max :: ThreadIdText -> ThreadIdText -> ThreadIdText

min :: ThreadIdText -> ThreadIdText -> ThreadIdText

Show ThreadIdText

Defined in Katip.Core

Methods

showsPrec :: Int -> ThreadIdText -> ShowS

show :: ThreadIdText -> String

showList :: [ThreadIdText] -> ShowS

ToJSON ThreadIdText

Defined in Katip.Core

Methods

toJSON :: ThreadIdText -> Value

toEncoding :: ThreadIdText -> Encoding

toJSONList :: [ThreadIdText] -> Value

toEncodingList :: [ThreadIdText] -> Encoding

FromJSON ThreadIdText

Defined in Katip.Core

Methods

parseJSON :: Value -> Parser ThreadIdText

parseJSONList :: Value -> Parser [ThreadIdText]

mkThreadIdText :: ThreadId -> ThreadIdText

data Item a

This has everything each log message will contain.

Constructors

Item

Fields

• _itemApp :: Namespace
• _itemEnv :: Environment
• _itemSeverity :: Severity
• _itemThread :: ThreadIdText
• _itemHost :: HostName
• _itemProcess :: ProcessID
• _itemPayload :: a
• _itemMessage :: LogStr
• _itemTime :: UTCTime
• _itemNamespace :: Namespace
• _itemLoc :: Maybe Loc

Instances

Functor Item

Defined in Katip.Core

Methods

fmap :: (a -> b) -> Item a -> Item b

(<$) :: a -> Item b -> Item a

Eq a => Eq (Item a)

Defined in Katip.Core

Methods

(==) :: Item a -> Item a -> Bool

(/=) :: Item a -> Item a -> Bool

Show a => Show (Item a)

Defined in Katip.Core

Methods

showsPrec :: Int -> Item a -> ShowS

show :: Item a -> String

showList :: [Item a] -> ShowS

Generic (Item a)

Defined in Katip.Core

Associated Types

type Rep (Item a) :: Type -> Type

Methods

from :: Item a -> Rep (Item a) x

to :: Rep (Item a) x -> Item a

ToJSON a => ToJSON (Item a)

Defined in Katip.Core

Methods

toJSON :: Item a -> Value

toEncoding :: Item a -> Encoding

toJSONList :: [Item a] -> Value

toEncodingList :: [Item a] -> Encoding

FromJSON a => FromJSON (Item a)

Defined in Katip.Core

Methods

parseJSON :: Value -> Parser (Item a)

parseJSONList :: Value -> Parser [Item a]

type Rep (Item a)

Defined in Katip.Core

type Rep (Item a) = D1 (MetaData "Item" "Katip.Core" "katip-0.8.4.0-7DneCQDN77aDRNtrdZcl08" False) (C1 (MetaCons "Item" PrefixI True) (((S1 (MetaSel (Just "_itemApp") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Namespace) :*: S1 (MetaSel (Just "_itemEnv") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Environment)) :*: (S1 (MetaSel (Just "_itemSeverity") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Severity) :*: (S1 (MetaSel (Just "_itemThread") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ThreadIdText) :*: S1 (MetaSel (Just "_itemHost") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 HostName)))) :*: ((S1 (MetaSel (Just "_itemProcess") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 ProcessID) :*: (S1 (MetaSel (Just "_itemPayload") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a) :*: S1 (MetaSel (Just "_itemMessage") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 LogStr))) :*: (S1 (MetaSel (Just "_itemTime") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 UTCTime) :*: (S1 (MetaSel (Just "_itemNamespace") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Namespace) :*: S1 (MetaSel (Just "_itemLoc") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Maybe Loc)))))))

itemTime :: forall a. Lens' (Item a) UTCTime

itemThread :: forall a. Lens' (Item a) ThreadIdText

itemSeverity :: forall a. Lens' (Item a) Severity

itemProcess :: forall a. Lens' (Item a) ProcessID

itemPayload :: forall a a. Lens (Item a) (Item a) a a

itemNamespace :: forall a. Lens' (Item a) Namespace

itemMessage :: forall a. Lens' (Item a) LogStr

itemLoc :: forall a. Lens' (Item a) (Maybe Loc)

itemHost :: forall a. Lens' (Item a) HostName

itemEnv :: forall a. Lens' (Item a) Environment

itemApp :: forall a. Lens' (Item a) Namespace

newtype LocShow

Constructors

LocShow Loc

Instances

Show LocShow

Defined in Katip.Core

Methods

showsPrec :: Int -> LocShow -> ShowS

show :: LocShow -> String

showList :: [LocShow] -> ShowS

newtype LocJs

Constructors

LocJs

Fields

• getLocJs :: Loc

Instances

ToJSON LocJs

Defined in Katip.Core

Methods

toJSON :: LocJs -> Value

toEncoding :: LocJs -> Encoding

toJSONList :: [LocJs] -> Value

toEncodingList :: [LocJs] -> Encoding

FromJSON LocJs

Defined in Katip.Core

Methods

parseJSON :: Value -> Parser LocJs

parseJSONList :: Value -> Parser [LocJs]

processIDToText :: ProcessID -> Text

textToProcessID :: Text -> Maybe ProcessID

newtype ProcessIDJs

Constructors

ProcessIDJs

Fields

• getProcessIDJs :: ProcessID

Instances

ToJSON ProcessIDJs

Defined in Katip.Core

Methods

toJSON :: ProcessIDJs -> Value

toEncoding :: ProcessIDJs -> Encoding

toJSONList :: [ProcessIDJs] -> Value

toEncodingList :: [ProcessIDJs] -> Encoding

FromJSON ProcessIDJs

Defined in Katip.Core

Methods

parseJSON :: Value -> Parser ProcessIDJs

parseJSONList :: Value -> Parser [ProcessIDJs]

data PayloadSelection

Field selector by verbosity within JSON payload.

Constructors

AllKeys

SomeKeys [Text]

Instances

Eq PayloadSelection

Defined in Katip.Core

Methods

(==) :: PayloadSelection -> PayloadSelection -> Bool

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

Show PayloadSelection

Defined in Katip.Core

Methods

showsPrec :: Int -> PayloadSelection -> ShowS

show :: PayloadSelection -> String

showList :: [PayloadSelection] -> ShowS

Semigroup PayloadSelection

Defined in Katip.Core

Methods

(<>) :: PayloadSelection -> PayloadSelection -> PayloadSelection

sconcat :: NonEmpty PayloadSelection -> PayloadSelection

stimes :: Integral b => b -> PayloadSelection -> PayloadSelection

Monoid PayloadSelection

Defined in Katip.Core

Methods

mempty :: PayloadSelection

mappend :: PayloadSelection -> PayloadSelection -> PayloadSelection

mconcat :: [PayloadSelection] -> PayloadSelection

class ToObject a where

Katip requires JSON objects to be logged as context. This typeclass provides a default instance which uses ToJSON and produces an empty object if toJSON results in any type other than object. If you have a type you want to log that produces an Array or Number for example, you'll want to write an explicit instance here. You can trivially add a ToObject instance for something with a ToJSON instance like:

instance ToObject Foo

Minimal complete definition

Nothing

Methods

toObject :: a -> Object

toObject :: ToJSON a => a -> Object

Instances

ToObject ()

Defined in Katip.Core

Methods

toObject :: () -> Object

ToObject Object

Defined in Katip.Core

Methods

toObject :: Object -> Object

ToObject SimpleLogPayload

Defined in Katip.Core

Methods

toObject :: SimpleLogPayload -> Object

ToObject LogContexts

Defined in Katip.Monadic

Methods

toObject :: LogContexts -> Object

class ToObject a => LogItem a where

Payload objects need instances of this class. LogItem makes it so that you can have very verbose items getting logged with lots of extra fields but under normal circumstances, if your scribe is configured for a lower verbosity level, it will only log a selection of those keys. Furthermore, each Scribe can be configured with a different Verbosity level. You could even use registerScribe, unregisterScribe, and clearScribes to at runtime swap out your existing scribes for more verbose debugging scribes if you wanted to.

When defining payloadKeys, don't redundantly declare the same keys for higher levels of verbosity. Each level of verbosity automatically and recursively contains all keys from the level before it.

Methods

payloadKeys :: Verbosity -> a -> PayloadSelection

List of keys in the JSON object that should be included in message.

Instances

LogItem ()

Defined in Katip.Core

Methods

payloadKeys :: Verbosity -> () -> PayloadSelection

LogItem SimpleLogPayload

Defined in Katip.Core

Methods

payloadKeys :: Verbosity -> SimpleLogPayload -> PayloadSelection

LogItem LogContexts

Defined in Katip.Monadic

Methods

payloadKeys :: Verbosity -> LogContexts -> PayloadSelection

data AnyLogPayload

Constructors

ToJSON a => AnyLogPayload a

newtype SimpleLogPayload

Constructors

SimpleLogPayload

Fields

• unSimpleLogPayload :: [(Text, AnyLogPayload)]

Instances

Semigroup SimpleLogPayload

Defined in Katip.Core

Methods

(<>) :: SimpleLogPayload -> SimpleLogPayload -> SimpleLogPayload

sconcat :: NonEmpty SimpleLogPayload -> SimpleLogPayload

stimes :: Integral b => b -> SimpleLogPayload -> SimpleLogPayload

Monoid SimpleLogPayload

Defined in Katip.Core

Methods

mempty :: SimpleLogPayload

mappend :: SimpleLogPayload -> SimpleLogPayload -> SimpleLogPayload

mconcat :: [SimpleLogPayload] -> SimpleLogPayload

ToJSON SimpleLogPayload

A built-in convenience log payload that won't log anything on V0, but will log everything in any other level of verbosity. Intended for easy in-line usage without having to define new log types.

Construct using sl and combine multiple tuples using <> from Monoid.

Defined in Katip.Core

Methods

toJSON :: SimpleLogPayload -> Value

toEncoding :: SimpleLogPayload -> Encoding

toJSONList :: [SimpleLogPayload] -> Value

toEncodingList :: [SimpleLogPayload] -> Encoding

LogItem SimpleLogPayload

Defined in Katip.Core

Methods

payloadKeys :: Verbosity -> SimpleLogPayload -> PayloadSelection

ToObject SimpleLogPayload

Defined in Katip.Core

Methods

toObject :: SimpleLogPayload -> Object

sl :: ToJSON a => Text -> a -> SimpleLogPayload

Construct a simple log from any JSON item.

payloadObject :: LogItem a => Verbosity -> a -> Object

Constrain payload based on verbosity. Backends should use this to automatically bubble higher verbosity levels to lower ones.

itemJson :: LogItem a => Verbosity -> Item a -> Value

Convert log item to its JSON representation while trimming its payload based on the desired verbosity. Backends that push JSON messages should use this to obtain their payload.

type PermitFunc = forall a. Item a -> IO Bool

Scribes are handlers of incoming items. Each registered scribe knows how to push a log item somewhere.

Guidelines for writing your own Scribe

Scribes should always take a Severity and Verbosity.

Severity is used to exclude log messages that are lower than the provided Severity. For instance, if the user passes InfoS, DebugS items should be ignored. Katip provides the permitItem utility for this. The user or the scribe may use permitAND and permitOR to further customize this filtering, even dynamically if they wish to.

Verbosity is used to select keys from the log item's payload. Each LogItem instance describes what keys should be retained for each Verbosity level. Use the payloadObject utility for extracting the keys that should be written.

Scribes provide a finalizer IO action (scribeFinalizer) that is meant to synchronously flush any remaining writes and clean up any resources acquired when the scribe was created. Internally, katip keeps a buffer for each scribe's writes. When closeScribe or closeScribes is called, that buffer stops accepting new log messages and after the last item in its buffer is sent to liPush, calls the finalizer. Thus, when the finalizer returns, katip can assume that all resources are cleaned up and all log messages are durably written.

While katip internally buffers messages per ScribeSettings, it sends them one at a time to the scribe. Depending on the scribe itself, it may make sense for that scribe to keep its own internal buffer to batch-send logs if writing items one at a time is not efficient. The scribe implementer must be sure that on finalization, all writes are committed synchronously.

Signature of a function passed to Scribe constructor and mkScribe* functions that decides which messages to be logged. Typically filters based on Severity, but can be combined with other, custom logic with permitAND and permitOR

permitAND :: PermitFunc -> PermitFunc -> PermitFunc

AND together 2 permit functions

permitOR :: PermitFunc -> PermitFunc -> PermitFunc

OR together 2 permit functions

data Scribe

Constructors

Scribe

Fields

• liPush :: forall a. LogItem a => Item a -> IO ()

  How do we write an item to the scribe's output?

• scribeFinalizer :: IO ()

  Provide a blocking finalizer to call when your scribe is removed. All pending writes should be flushed synchronously. If this is not relevant to your scribe, return () is fine.

• scribePermitItem :: PermitFunc

  Provide a filtering function to allow the item to be logged, or not. It can check Severity or some string in item's body. The initial value of this is usually created from permitItem. Scribes and users can customize this by ANDing or ORing onto the default with permitAND or permitOR

Instances

Semigroup Scribe

Combine two scribes. Publishes to the left scribe if the left would permit the item and to the right scribe if the right would permit the item. Finalizers are called in sequence from left to right.

Defined in Katip.Core

Methods

(<>) :: Scribe -> Scribe -> Scribe

sconcat :: NonEmpty Scribe -> Scribe

stimes :: Integral b => b -> Scribe -> Scribe

Monoid Scribe

Defined in Katip.Core

Methods

mempty :: Scribe

mappend :: Scribe -> Scribe -> Scribe

mconcat :: [Scribe] -> Scribe

whenM :: Monad m => m Bool -> m () -> m ()

data ScribeHandle

Constructors

ScribeHandle

Fields

• shScribe :: Scribe
• shChan :: TBQueue WorkerMessage

data WorkerMessage where

Constructors

NewItem :: LogItem a => Item a -> WorkerMessage

PoisonPill :: WorkerMessage

permitItem :: Monad m => Severity -> Item a -> m Bool

Should this item be logged given the user's maximum severity? Most new scribes will use this as a base for their PermitFunc

data LogEnv

Constructors

LogEnv

Fields

• _logEnvHost :: HostName
• _logEnvPid :: ProcessID
• _logEnvApp :: Namespace

  Name of application. This will typically never change. This field gets prepended to the namespace of your individual log messages. For example, if your app is MyApp and you write a log using "logItem" and the namespace WebServer, the final namespace will be MyApp.WebServer

• _logEnvEnv :: Environment
• _logEnvTimer :: IO UTCTime

  Action to fetch the timestamp. You can use something like AutoUpdate for high volume logs but note that this may cause some output forms to display logs out of order. Alternatively, you could just use getCurrentTime.

• _logEnvScribes :: Map Text ScribeHandle

logEnvTimer :: Lens' LogEnv (IO UTCTime)

logEnvScribes :: Lens' LogEnv (Map Text ScribeHandle)

logEnvPid :: Lens' LogEnv ProcessID

logEnvHost :: Lens' LogEnv HostName

logEnvEnv :: Lens' LogEnv Environment

logEnvApp :: Lens' LogEnv Namespace

initLogEnv

Arguments

:: Namespace

A base namespace for this application

-> Environment

Current run environment (e.g. prod vs. devel)

-> IO LogEnv

Create a reasonable default InitLogEnv. Uses an AutoUdate which updates the timer every 1ms. If you need even more timestamp precision at the cost of performance, consider setting _logEnvTimer with getCurrentTime.

registerScribe

Arguments

:: Text

Name the scribe

-> Scribe

-> ScribeSettings

-> LogEnv

-> IO LogEnv

Add a scribe to the list. All future log calls will go to this scribe in addition to the others. Writes will be buffered per the ScribeSettings to prevent slow scribes from slowing down logging. Writes will be dropped if the buffer fills.

spawnScribeWorker :: Scribe -> TBQueue WorkerMessage -> IO (Async ())

data ScribeSettings

Constructors

ScribeSettings

Fields

• _scribeBufferSize :: Int

Instances

Eq ScribeSettings

Defined in Katip.Core

Methods

(==) :: ScribeSettings -> ScribeSettings -> Bool

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

Show ScribeSettings

Defined in Katip.Core

Methods

showsPrec :: Int -> ScribeSettings -> ShowS

show :: ScribeSettings -> String

showList :: [ScribeSettings] -> ShowS

scribeBufferSize :: Lens' ScribeSettings Int

defaultScribeSettings :: ScribeSettings

Reasonable defaults for a scribe. Buffer size of 4096.

unregisterScribe

Arguments

:: Text

Name of the scribe

-> LogEnv

-> LogEnv

Remove a scribe from the environment. This does not finalize the scribe. This mainly only makes sense to use with something like MonadReader's local function to temporarily disavow a single logger for a block of code.

clearScribes :: LogEnv -> LogEnv

Unregister all scribes. Note that this is not for closing or finalizing scribes, use closeScribes for that. This mainly only makes sense to use with something like MonadReader's local function to temporarily disavow any loggers for a block of code.

closeScribe

Arguments

:: Text

Name of the scribe

-> LogEnv

-> IO LogEnv

Finalize a scribe. The scribe is removed from the environment, its finalizer is called so that it can never be written to again and all pending writes are flushed. Note that this will throw any exceptions yoru finalizer will throw, and that LogEnv is immutable, so it will not be removed in that case.

closeScribes :: LogEnv -> IO LogEnv

Call this at the end of your program. This is a blocking call that stop writing to a scribe's queue, waits for the queue to empty, finalizes each scribe in the log environment and then removes it. Finalizers are all run even if one of them throws, but the exception will be re-thrown at the end.

class MonadIO m => Katip m where

Monads where katip logging actions can be performed. Katip is the most basic logging monad. You will typically use this directly if you either don't want to use namespaces/contexts heavily or if you want to pass in specific contexts and/or namespaces at each log site.

For something more powerful, look at the docs for KatipContext, which keeps a namespace and merged context. You can write simple functions that add additional namespacing and merges additional context on the fly.

localLogEnv was added to allow for lexically-scoped modifications of the log env that are reverted when the supplied monad completes. katipNoLogging, for example, uses this to temporarily pause log outputs.

Methods

getLogEnv :: m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> m a -> m a

Instances

Katip m => Katip (MaybeT m)

Defined in Katip.Core

Methods

getLogEnv :: MaybeT m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> MaybeT m a -> MaybeT m a

Katip m => Katip (ResourceT m)

Defined in Katip.Core

Methods

getLogEnv :: ResourceT m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> ResourceT m a -> ResourceT m a

MonadIO m => Katip (KatipT m)

Defined in Katip.Core

Methods

getLogEnv :: KatipT m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> KatipT m a -> KatipT m a

MonadIO m => Katip (NoLoggingT m)

Defined in Katip.Monadic

Methods

getLogEnv :: NoLoggingT m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> NoLoggingT m a -> NoLoggingT m a

MonadIO m => Katip (KatipContextT m)

Defined in Katip.Monadic

Methods

getLogEnv :: KatipContextT m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> KatipContextT m a -> KatipContextT m a

Katip m => Katip (ExceptT s m)

Defined in Katip.Core

Methods

getLogEnv :: ExceptT s m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> ExceptT s m a -> ExceptT s m a

(Katip m, Monoid s) => Katip (WriterT s m)

Defined in Katip.Core

Methods

getLogEnv :: WriterT s m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> WriterT s m a -> WriterT s m a

Katip m => Katip (StateT s m)

Defined in Katip.Core

Methods

getLogEnv :: StateT s m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> StateT s m a -> StateT s m a

Katip m => Katip (StateT s m)

Defined in Katip.Core

Methods

getLogEnv :: StateT s m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> StateT s m a -> StateT s m a

(Katip m, Monoid s) => Katip (WriterT s m)

Defined in Katip.Core

Methods

getLogEnv :: WriterT s m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> WriterT s m a -> WriterT s m a

Katip m => Katip (ReaderT s m)

Defined in Katip.Core

Methods

getLogEnv :: ReaderT s m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> ReaderT s m a -> ReaderT s m a

(Katip m, Monoid w) => Katip (RWST r w s m)

Defined in Katip.Core

Methods

getLogEnv :: RWST r w s m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> RWST r w s m a -> RWST r w s m a

(Katip m, Monoid w) => Katip (RWST r w s m)

Defined in Katip.Core

Methods

getLogEnv :: RWST r w s m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> RWST r w s m a -> RWST r w s m a

newtype KatipT m a

A concrete monad you can use to run logging actions. Use this if you prefer an explicit monad transformer stack and adding layers as opposed to implementing Katip for your monad.

Constructors

KatipT

Fields

• unKatipT :: ReaderT LogEnv m a

Instances

MonadTrans KatipT

Defined in Katip.Core

Methods

lift :: Monad m => m a -> KatipT m a

MonadTransControl KatipT

Defined in Katip.Core

Associated Types

type StT KatipT a :: Type

Methods

liftWith :: Monad m => (Run KatipT -> m a) -> KatipT m a

restoreT :: Monad m => m (StT KatipT a) -> KatipT m a

MonadBase b m => MonadBase b (KatipT m)

Defined in Katip.Core

Methods

liftBase :: b α -> KatipT m α

MonadBaseControl b m => MonadBaseControl b (KatipT m)

Defined in Katip.Core

Associated Types

type StM (KatipT m) a :: Type

Methods

liftBaseWith :: (RunInBase (KatipT m) b -> b a) -> KatipT m a

restoreM :: StM (KatipT m) a -> KatipT m a

Monad m => Monad (KatipT m)

Defined in Katip.Core

Methods

(>>=) :: KatipT m a -> (a -> KatipT m b) -> KatipT m b

(>>) :: KatipT m a -> KatipT m b -> KatipT m b

return :: a -> KatipT m a

fail :: String -> KatipT m a

Functor m => Functor (KatipT m)

Defined in Katip.Core

Methods

fmap :: (a -> b) -> KatipT m a -> KatipT m b

(<$) :: a -> KatipT m b -> KatipT m a

MonadFail m => MonadFail (KatipT m)

Defined in Katip.Core

Methods

fail :: String -> KatipT m a

Applicative m => Applicative (KatipT m)

Defined in Katip.Core

Methods

pure :: a -> KatipT m a

(<*>) :: KatipT m (a -> b) -> KatipT m a -> KatipT m b

liftA2 :: (a -> b -> c) -> KatipT m a -> KatipT m b -> KatipT m c

(*>) :: KatipT m a -> KatipT m b -> KatipT m b

(<*) :: KatipT m a -> KatipT m b -> KatipT m a

MonadIO m => MonadIO (KatipT m)

Defined in Katip.Core

Methods

liftIO :: IO a -> KatipT m a

MonadThrow m => MonadThrow (KatipT m)

Defined in Katip.Core

Methods

throwM :: Exception e => e -> KatipT m a

MonadCatch m => MonadCatch (KatipT m)

Defined in Katip.Core

Methods

catch :: Exception e => KatipT m a -> (e -> KatipT m a) -> KatipT m a

MonadMask m => MonadMask (KatipT m)

Defined in Katip.Core

Methods

mask :: ((forall a. KatipT m a -> KatipT m a) -> KatipT m b) -> KatipT m b

uninterruptibleMask :: ((forall a. KatipT m a -> KatipT m a) -> KatipT m b) -> KatipT m b

generalBracket :: KatipT m a -> (a -> ExitCase b -> KatipT m c) -> (a -> KatipT m b) -> KatipT m (b, c)

MonadUnliftIO m => MonadUnliftIO (KatipT m)

Defined in Katip.Core

Methods

withRunInIO :: ((forall a. KatipT m a -> IO a) -> IO b) -> KatipT m b

MonadIO m => Katip (KatipT m)

Defined in Katip.Core

Methods

getLogEnv :: KatipT m LogEnv

localLogEnv :: (LogEnv -> LogEnv) -> KatipT m a -> KatipT m a

(Monad m, KatipContext m) => KatipContext (KatipT m)

Defined in Katip.Monadic

Methods

getKatipContext :: KatipT m LogContexts

localKatipContext :: (LogContexts -> LogContexts) -> KatipT m a -> KatipT m a

getKatipNamespace :: KatipT m Namespace

localKatipNamespace :: (Namespace -> Namespace) -> KatipT m a -> KatipT m a

type StT KatipT a

Defined in Katip.Core

type StT KatipT a = a

type StM (KatipT m) a

Defined in Katip.Core

type StM (KatipT m) a = ComposeSt KatipT m a

runKatipT :: LogEnv -> KatipT m a -> m a

Execute KatipT on a log env.

katipNoLogging :: Katip m => m a -> m a

Disable all scribes for the given monadic action, then restore them afterwards. Works in any Katip monad.

logItem :: (Applicative m, LogItem a, Katip m) => a -> Namespace -> Maybe Loc -> Severity -> LogStr -> m ()

Log with everything, including a source code location. This is very low level and you typically can use logT in its place.

logKatipItem :: (Applicative m, LogItem a, Katip m) => Item a -> m ()

Log already constructed Item. This is the lowest level function that other log* functions use. It can be useful when implementing centralised logging services.

tryWriteTBQueue

Arguments

:: TBQueue a

-> a

-> STM Bool

Did we write?

logF

Arguments

:: (Applicative m, LogItem a, Katip m)

=> a

Contextual payload for the log

-> Namespace

Specific namespace of the message.

-> Severity

Severity of the message

-> LogStr

The log message

-> m ()

Log with full context, but without any code location.

logException

Arguments

:: (Katip m, LogItem a, MonadCatch m, Applicative m)

=> a

Log context

-> Namespace

Namespace

-> Severity

Severity

-> m b

Main action being run

-> m b

Perform an action while logging any exceptions that may occur. Inspired by onException.

>>> > logException () mempty ErrorS (error "foo")

logMsg :: (Applicative m, Katip m) => Namespace -> Severity -> LogStr -> m ()

Log a message without any payload/context or code location.

liftLoc :: Loc -> Q Exp

Lift a location into an Exp.

getLoc :: HasCallStack => Maybe Loc

For use when you want to include location in your logs. This will fill the 'Maybe Loc' gap in logF of this module, and relies on implicit callstacks when available (GHC > 7.8).

getLocTH :: ExpQ

logT :: ExpQ

Loc-tagged logging when using template-haskell.

$(logT) obj mempty InfoS "Hello world"

logLoc :: (Applicative m, LogItem a, Katip m, HasCallStack) => a -> Namespace -> Severity -> LogStr -> m ()

Loc-tagged logging using Stack when available.

This function does not require template-haskell as it automatically uses implicit-callstacks when the code is compiled using GHC > 7.8. Using an older version of the compiler will result in the emission of a log line without any location information, so be aware of it. Users using GHC <= 7.8 may want to use the template-haskell function logT for maximum compatibility.

logLoc obj mempty InfoS "Hello world"

locationToString :: Loc -> String