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

Ord Namespace

Read Namespace

Show Namespace

IsString Namespace

Generic Namespace

Monoid Namespace

Lift Namespace

Semigroup Namespace

ToJSON Namespace

FromJSON Namespace

type Rep Namespace

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

Ord Environment

Read Environment

Show Environment

IsString Environment

Generic Environment

ToJSON Environment

FromJSON Environment

type Rep Environment

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

Enum Severity

Eq Severity

Ord Severity

Read Severity

Show Severity

Generic Severity

Lift Severity

ToJSON Severity

FromJSON Severity

type Rep Severity

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

Enum Verbosity

Eq Verbosity

Ord Verbosity

Read Verbosity

Show Verbosity

Generic Verbosity

Lift Verbosity

type Rep Verbosity

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

Show LogStr

IsString LogStr

Generic LogStr

Monoid LogStr

Semigroup LogStr

FromJSON LogStr

type Rep LogStr

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

Ord ThreadIdText

Show ThreadIdText

ToJSON ThreadIdText

FromJSON 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

Show a => Show (Item a)

Generic (Item a)

ToJSON a => ToJSON (Item a)

FromJSON a => FromJSON (Item a)

type Rep (Item a)

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

newtype LocJs

Constructors

LocJs

Fields

getLocJs :: Loc

Instances

ToJSON LocJs

FromJSON LocJs

processIDToText :: ProcessID -> Text

textToProcessID :: Text -> Maybe ProcessID

newtype ProcessIDJs

Constructors

ProcessIDJs

Fields

getProcessIDJs :: ProcessID

Instances

ToJSON ProcessIDJs

FromJSON ProcessIDJs

data PayloadSelection

Field selector by verbosity within JSON payload.

Constructors

AllKeys

SomeKeys [Text]

Instances

Eq PayloadSelection

Show PayloadSelection

Monoid PayloadSelection

Semigroup 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

Instances

ToObject ()

ToObject Object

ToObject SimpleLogPayload

ToObject LogContexts

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 ()

LogItem SimpleLogPayload

LogItem LogContexts

data AnyLogPayload

Constructors

forall a . ToJSON a => AnyLogPayload a

newtype SimpleLogPayload

Constructors

SimpleLogPayload

Fields

unSimpleLogPayload :: [(Text, AnyLogPayload)]

Instances

Monoid SimpleLogPayload

Semigroup 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.

LogItem SimpleLogPayload

ToObject SimpleLogPayload

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.

data Scribe

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 < the provided Severity. For instance, if the user passes InfoS, DebugS items should be ignored. Katip provides the permitItem utility for this.

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 permitted.

There is no built-in mechanism in katip for telling a scribe that its time to shut down. unregisterScribe merely drops it from the LogEnv. This means there are 2 ways to handle resources as a scribe:

1. Pass in the resource when the scribe is created. Handle allocation and release of the resource elsewhere. This is what the Handle scribe does.
2. Return a finalizing function that tells the scribe to shut down. katip-elasticsearch's mkEsScribe returns an IO (Scribe, IO ()). The finalizer will flush any queued log messages and shut down gracefully before returning. This can be hooked into your application's shutdown routine to ensure you never miss any log messages on shutdown.

Constructors

Scribe

Fields

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

Instances

Monoid Scribe

Semigroup Scribe

permitItem :: Severity -> Item a -> Bool

Should this item be logged given the user's maximum severity?

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 Scribe

logEnvTimer :: Lens' LogEnv (IO UTCTime)

logEnvScribes :: Lens' LogEnv (Map Text Scribe)

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 with the default settings as the timer. If you are concerned about timestamp precision or event ordering in log outputs like ElasticSearch, you should replace the timer with getCurrentTime

registerScribe

Arguments

:: Text

Name the scribe

-> Scribe

-> LogEnv

-> LogEnv

Add a scribe to the list. All future log calls will go to this scribe in addition to the others.

unregisterScribe

Arguments

:: Text

Name of the scribe

-> LogEnv

-> LogEnv

Remove a scribe from the list. All future log calls will no longer use this scribe. If the given scribe doesn't exist, its a no-op.

clearScribes :: LogEnv -> LogEnv

Unregister *all* scribes. Logs will go off into space from this point onward until new scribes are added. Note that you could use this with local if you're using a Reader based stack to temporarily disable log output. See katipNoLogging for an example.

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.

Methods

getLogEnv :: m LogEnv

Instances

Katip m => Katip (MaybeT m)

Katip m => Katip (ResourceT m)

MonadIO m => Katip (KatipT m)

MonadIO m => Katip (KatipContextT m)

Katip m => Katip (ReaderT s m)

Katip m => Katip (StateT s m)

Katip m => Katip (StateT s m)

Katip m => Katip (ExceptT s m)

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

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

Katip m => Katip (EitherT s m)

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

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

newtype KatipT m a

A concrete monad you can use to run logging actions.

Constructors

KatipT

Fields

unKatipT :: ReaderT LogEnv m a

Instances

MonadTrans KatipT

MonadTransControl KatipT

MonadBase b m => MonadBase b (KatipT m)

MonadBaseControl b m => MonadBaseControl b (KatipT m)

Monad m => Monad (KatipT m)

Functor m => Functor (KatipT m)

Applicative m => Applicative (KatipT m)

MonadIO m => MonadIO (KatipT m)

MonadThrow m => MonadThrow (KatipT m)

MonadMask m => MonadMask (KatipT m)

MonadCatch m => MonadCatch (KatipT m)

MonadIO m => Katip (KatipT m)

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

type StT KatipT a = a

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

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

Execute KatipT on a log env.

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.

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 :: (?loc :: CallStack) => 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, ?loc :: CallStack) => a -> Namespace -> Severity -> LogStr -> m ()

Loc-tagged logging using implicit-callstacks 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