git.iko.soy/typeable/katip
on master help sign in
Document writing your own scribe
6793fa4Michael Xavier
katip/src/Katip.hs+9
compare with master
unifiedsplit
@@ -18,6 +18,10 @@
18-- implement 'ToObject' and 'LogItem' for them.
18-- implement 'ToObject' and 'LogItem' for them.
19--
19--
20-- * Begin logging with 'logT', 'logTM', etc.
20-- * Begin logging with 'logT', 'logTM', etc.
21+--
22+-- * Define your own 'Scribe' if you need to output to some as-yet
23+-- unsupported format or service. If you think it would be useful to
24+-- others, consider releasing your own package.
21module Katip
25module Katip
22 (
26 (
23
27
@@ -87,6 +91,11 @@ module Katip
87 , mkHandleScribe
91 , mkHandleScribe
88 , ColorStrategy (..)
92 , ColorStrategy (..)
89
93
94+ -- * Tools for implementing Scribes
95+ , permitItem
96+ , payloadObject
97+ , itemJson
98+
90 -- * KatipContextT - Utility transformer that provides Katip and KatipContext instances
99 -- * KatipContextT - Utility transformer that provides Katip and KatipContext instances
91 , KatipContextT
100 , KatipContextT
92 , runKatipContextT
101 , runKatipContextT
katip/src/Katip/Core.hs+36−1
@@ -425,8 +425,36 @@ itemJson verb a = toJSON $ a & itemPayload %~ payloadObject verb
425-------------------------------------------------------------------------------
425-------------------------------------------------------------------------------
426-- | Scribes are handlers of incoming items. Each registered scribe
426-- | Scribes are handlers of incoming items. Each registered scribe
427-- knows how to push a log item somewhere.
427-- knows how to push a log item somewhere.
428+--
429+-- = Guidelines for writing your own 'Scribe'
430+--
431+-- Scribes should always take a 'Severity' and 'Verbosity'.
432+--
433+-- Severity is used to *exclude log messages* that are < the provided
434+-- Severity. For instance, if the user passes InfoS, DebugS items
435+-- should be ignored. Katip provides the 'permitItem' utility for this.
436+--
437+-- Verbosity is used to select keys from the log item's payload. Each
438+-- 'LogItem' instance describes what keys should be retained for each
439+-- Verbosity level. Use the 'payloadObject' utility for extracting the keys
440+-- that should be permitted.
441+--
442+-- There is no built-in mechanism in katip for telling a scribe that
443+-- its time to shut down. 'unregisterScribe' merely drops it from the
444+-- 'LogEnv'. This means there are 2 ways to handle resources as a scribe:
445+--
446+-- 1. Pass in the resource when the scribe is created. Handle
447+-- allocation and release of the resource elsewhere. This is what the
448+-- Handle scribe does.
449+--
450+-- 2. Return a finalizing function that tells the scribe to shut
451+-- down. @katip-elasticsearch@'s @mkEsScribe@ returns a @IO (Scribe,
452+-- IO ())@. The finalizer will flush any queued log messages and shut
453+-- down gracefully before returning. This can be hooked into your
454+-- application's shutdown routine to ensure you never miss any log
455+-- messages on shutdown.
428data Scribe = Scribe {
456data Scribe = Scribe {
429− lhPush :: forall a. LogItem a => Item a -> IO ()
457+ liPush :: forall a. LogItem a => Item a -> IO ()
430 }
458 }
431
459
432
460
@@ -436,6 +464,13 @@ instance Monoid Scribe where
436 a item
464 a item
437 b item
465 b item
438
466
467+
468+-------------------------------------------------------------------------------
469+-- | Should this item be logged given the user's maximum severity?
470+permitItem :: Severity -> Item a -> Bool
471+permitItem sev i = _itemSeverity i >= sev
472+
473+
439-------------------------------------------------------------------------------
474-------------------------------------------------------------------------------
440data LogEnv = LogEnv {
475data LogEnv = LogEnv {
441 _logEnvHost :: HostName
476 _logEnvHost :: HostName
katip/src/Katip/Scribes/Handle.hs+1−1
@@ -57,7 +57,7 @@ mkHandleScribe cs h sev verb = do
57 ColorIfTerminal -> hIsTerminalDevice h
57 ColorIfTerminal -> hIsTerminalDevice h
58 ColorLog b -> return b
58 ColorLog b -> return b
59 return $ Scribe $ \ i@Item{..} -> do
59 return $ Scribe $ \ i@Item{..} -> do
60− when (_itemSeverity >= sev) $
60+ when (permitItem sev i) $
61 T.hPutStrLn h $ toLazyText $ formatItem colorize verb i
61 T.hPutStrLn h $ toLazyText $ formatItem colorize verb i
62
62
63
63