@@ -425,8 +425,36 @@ itemJson verb a = toJSON $ a & itemPayload %~ payloadObject verb
425425-------------------------------------------------------------------------------
426426-- | Scribes are handlers of incoming items. Each registered scribe
427427-- 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.
428456data Scribe = Scribe {
429− lhPush :: forall a. LogItem a => Item a -> IO ()
457+ liPush :: forall a. LogItem a => Item a -> IO ()
430458 }
431459
432460
@@ -436,6 +464,13 @@ instance Monoid Scribe where
436464 a item
437465 b item
438466
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+
439474-------------------------------------------------------------------------------
440475data LogEnv = LogEnv {
441476 _logEnvHost :: HostName