katip-0.3.1.4: A structured logging framework.

Safe HaskellNone
LanguageHaskell2010

Katip.Core

Description

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

Synopsis

Documentation

newtype Namespace Source

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]
 

intercalateNs :: Namespace -> [Text] Source

Ready namespace for emission with dots to join the segments.

newtype Environment Source

Application environment, like prod, devel, testing.

Constructors

Environment 

Fields

getEnvironment :: Text
 

data Severity Source

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

data Verbosity Source

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 

newtype LogStr Source

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

Constructors

LogStr 

Fields

unLogStr :: Builder
 

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

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 Source

Shorthand for logStr

showLS :: Show a => a -> LogStr Source

Convert any showable type into a LogStr.

data Item a Source

This has everything each log message will contain.

Instances

Functor Item Source 
Show a => Show (Item a) Source 
Generic (Item a) Source 
ToJSON a => ToJSON (Item a) Source 
FromJSON a => FromJSON (Item a) Source 
type Rep (Item a) Source 

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

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

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

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

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

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

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

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

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

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

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

newtype LocShow Source

Constructors

LocShow Loc 

Instances

newtype LocJs Source

Constructors

LocJs 

Fields

getLocJs :: Loc
 

Instances

ToJSON LocJs Source 
FromJSON LocJs Source 

newtype ProcessIDJs Source

Constructors

ProcessIDJs 

Instances

data PayloadSelection Source

Field selector by verbosity within JSON payload.

Constructors

AllKeys 
SomeKeys [Text] 

class ToObject a where Source

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 Source

class ToObject a => LogItem a where Source

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 Source

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

data AnyLogPayload Source

Constructors

forall a . ToJSON a => AnyLogPayload a 

newtype SimpleLogPayload Source

Constructors

SimpleLogPayload 

Fields

unSimpleLogPayload :: [(Text, AnyLogPayload)]
 

Instances

Monoid SimpleLogPayload Source 
Semigroup SimpleLogPayload Source 
ToJSON SimpleLogPayload Source

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 Source 
ToObject SimpleLogPayload Source 

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

Construct a simple log from any JSON item.

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

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 Source

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 Source

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 a 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

permitItem :: Severity -> Item a -> Bool Source

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

data LogEnv Source

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
 

logEnvHost :: Lens' LogEnv HostName Source

initLogEnv Source

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 Source

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 Source

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 Source

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 Source

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 Source

Instances

Katip m => Katip (MaybeT m) Source 
Katip m => Katip (ResourceT m) Source 
MonadIO m => Katip (KatipT m) Source 
MonadIO m => Katip (KatipContextT m) Source 
Katip m => Katip (ReaderT s m) Source 
Katip m => Katip (StateT s m) Source 
Katip m => Katip (ExceptT s m) Source 
(Katip m, Monoid s) => Katip (WriterT s m) Source 
Katip m => Katip (EitherT s m) Source 

newtype KatipT m a Source

A concrete monad you can use to run logging actions.

Constructors

KatipT 

Fields

unKatipT :: ReaderT LogEnv m a
 

Instances

MonadTrans KatipT Source 
MonadTransControl KatipT Source 
MonadBase b m => MonadBase b (KatipT m) Source 
MonadBaseControl b m => MonadBaseControl b (KatipT m) Source 
Monad m => Monad (KatipT m) Source 
Functor m => Functor (KatipT m) Source 
Applicative m => Applicative (KatipT m) Source 
MonadIO m => MonadIO (KatipT m) Source 
MonadThrow m => MonadThrow (KatipT m) Source 
MonadMask m => MonadMask (KatipT m) Source 
MonadCatch m => MonadCatch (KatipT m) Source 
MonadIO m => Katip (KatipT m) Source 
(Monad m, KatipContext m) => KatipContext (KatipT m) Source 
type StT KatipT a = a Source 
type StM (KatipT m) a = ComposeSt KatipT m a Source 

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

Execute KatipT on a log env.

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

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

logF Source

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 Source

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

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

liftLoc :: Loc -> Q Exp Source

Lift a location into an Exp.

getLoc :: (?loc :: CallStack) => Maybe Loc Source

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

logT :: ExpQ Source

Loc-tagged logging when using template-haskell.

$(logT) obj mempty InfoS "Hello world"

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

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"