@@ -532,57 +532,82 @@ itemJson verb a = toJSON $ a & itemPayload %~ payloadObject verb
532532--
533533-- Scribes should always take a 'Severity' and 'Verbosity'.
534534--
535−-- Severity is used to *exclude log messages* that are < the provided
536−-- Severity. For instance, if the user passes InfoS, DebugS items
537−-- should be ignored. Katip provides the 'permitItem' utility for this.
535+-- Severity is used to __exclude log messages__ that are lower than
536+-- the provided Severity. For instance, if the user passes InfoS,
537+-- DebugS items should be ignored. Katip provides the 'permitItem'
538+-- utility for this. The user or the scribe may use 'permitAND' and
539+-- 'permitOR' to further customize this filtering, even dynamically if
540+-- they wish to.
538541--
539542-- Verbosity is used to select keys from the log item's payload. Each
540543-- 'LogItem' instance describes what keys should be retained for each
541544-- Verbosity level. Use the 'payloadObject' utility for extracting the keys
542−-- that should be permitted.
545+-- that should be written.
543546--
544−-- There is no built-in mechanism in katip for telling a scribe that
545−-- its time to shut down. 'unregisterScribe' merely drops it from the
546−-- 'LogEnv'. This means there are 2 ways to handle resources as a scribe:
547+-- Scribes provide a finalizer IO action ('scribeFinalizer') that is
548+-- meant to synchronously flush any remaining writes and clean up any
549+-- resources acquired when the scribe was created. Internally, katip
550+-- keeps a buffer for each scribe's writes. When 'closeScribe' or
551+-- 'closeScribes' is called, that buffer stops accepting new log
552+-- messages and after the last item in its buffer is sent to 'liPush',
553+-- calls the finalizer. Thus, when the finalizer returns, katip can
554+-- assume that all resources are cleaned up and all log messages are
555+-- durably written.
547556--
548−-- 1. Pass in the resource when the scribe is created. Handle
549−-- allocation and release of the resource elsewhere. This is what the
550−-- Handle scribe does.
551−--
552−-- 2. Return a finalizing function that tells the scribe to shut
553−-- down. @katip-elasticsearch@'s @mkEsScribe@ returns an @IO (Scribe,
554−-- IO ())@. The finalizer will flush any queued log messages and shut
555−-- down gracefully before returning. This can be hooked into your
556−-- application's shutdown routine to ensure you never miss any log
557−-- messages on shutdown.
557+-- While katip internally buffers messages per 'ScribeSettings', it
558+-- sends them one at a time to the scribe. Depending on the scribe
559+-- itself, it may make sense for that scribe to keep its own internal
560+-- buffer to batch-send logs if writing items one at a time is not
561+-- efficient. The scribe implementer must be sure that on
562+-- finalization, all writes are committed synchronously.
563+
564+-- | Signature of a function passed to `Scribe` constructor and
565+-- mkScribe* functions that decides which messages to be
566+-- logged. Typically filters based on 'Severity', but can be
567+-- combined with other, custom logic with 'permitAND' and 'permitOR'
568+type PermitFunc = forall a. Item a -> IO Bool
558569
559570
560−-- | Signature of a function passed to `Scribe` constructor and mkScribe* functions
561−-- that decides which messages to be logged
562−type PermitFunc = forall a. Item a -> IO Bool
571+-- | AND together 2 permit functions
572+permitAND :: PermitFunc -> PermitFunc -> PermitFunc
573+permitAND f1 f2 = \a -> liftA2 (&&) (f1 a) (f2 a)
574+
575+-- | OR together 2 permit functions
576+permitOR :: PermitFunc -> PermitFunc -> PermitFunc
577+permitOR f1 f2 = \a -> liftA2 (||) (f1 a) (f2 a)
563578
564579
565580data Scribe = Scribe {
566581 liPush :: forall a. LogItem a => Item a -> IO ()
582+ -- ^ How do we write an item to the scribe's output?
567583 , scribeFinalizer :: IO ()
568− -- ^ Provide a *blocking* finalizer to call when your scribe is
569− -- removed. If this is not relevant to your scribe, return () is
570− -- fine.
584+ -- ^ Provide a __blocking__ finalizer to call when your scribe is
585+ -- removed. All pending writes should be flushed synchronously. If
586+ -- this is not relevant to your scribe, return () is fine.
571587 , scribePermitItem :: PermitFunc
572− -- ^ Provide a filtering function to allow the item to be logged, or not.
573− -- It can check Severity or some string in item's body.
588+ -- ^ Provide a filtering function to allow the item to be logged,
589+ -- or not. It can check Severity or some string in item's
590+ -- body. The initial value of this is usually created from
591+ -- 'permitItem'. Scribes and users can customize this by ANDing
592+ -- or ORing onto the default with 'permitAND' or 'permitOR'
574593 }
575594
595+
576596whenM :: Monad m => m Bool -> m () -> m ()
577597whenM mbool = (>>=) mbool . flip when
578598
599+
600+-- | Combine two scribes. Publishes to the left scribe if the left
601+-- would permit the item and to the right scribe if the right would
602+-- permit the item. Finalizers are called in sequence from left to
603+-- right.
579604instance Semigroup Scribe where
580605 (Scribe pushA finA permitA) <> (Scribe pushB finB permitB) =
581606 Scribe (\item -> whenM (permitA item) (pushA item)
582607 >> whenM (permitB item) (pushB item)
583608 )
584609 (finA `finally` finB)
585− (\item -> (||) <$> permitA item <*> permitB item)
610+ (permitOR permitA permitB)
586611
587612
588613instance Monoid Scribe where
@@ -605,8 +630,9 @@ data WorkerMessage where
605630
606631-------------------------------------------------------------------------------
607632-- | Should this item be logged given the user's maximum severity?
633+-- Most new scribes will use this as a base for their 'PermitFunc'
608634permitItem :: Monad m => Severity -> Item a -> m Bool
609−permitItem sev Item{..} = return $ _itemSeverity >= sev
635+permitItem sev item = return (_itemSeverity item >= sev)
610636
611637
612638-------------------------------------------------------------------------------
@@ -652,7 +678,9 @@ initLogEnv an env = LogEnv
652678
653679-------------------------------------------------------------------------------
654680-- | Add a scribe to the list. All future log calls will go to this
655−-- scribe in addition to the others.
681+-- scribe in addition to the others. Writes will be buffered per the
682+-- ScribeSettings to prevent slow scribes from slowing down
683+-- logging. Writes will be dropped if the buffer fills.
656684registerScribe
657685 :: Text
658686 -- ^ Name the scribe
@@ -705,7 +733,7 @@ defaultScribeSettings = ScribeSettings 4096
705733
706734
707735-------------------------------------------------------------------------------
708−-- | Remove a scribe from the environment. This does *not* finalize
736+-- | Remove a scribe from the environment. This does __not__ finalize
709737-- the scribe. This mainly only makes sense to use with something like
710738-- MonadReader's @local@ function to temporarily disavow a single
711739-- logger for a block of code.
@@ -718,7 +746,7 @@ unregisterScribe nm = logEnvScribes %~ M.delete nm
718746
719747
720748-------------------------------------------------------------------------------
721−-- | Unregister *all* scribes. Note that this is *not* for closing or
749+-- | Unregister __all__ scribes. Note that this is __not__ for closing or
722750-- finalizing scribes, use 'closeScribes' for that. This mainly only
723751-- makes sense to use with something like MonadReader's @local@
724752-- function to temporarily disavow any loggers for a block of code.
@@ -730,9 +758,10 @@ clearScribes = logEnvScribes .~ mempty
730758
731759-------------------------------------------------------------------------------
732760-- | Finalize a scribe. The scribe is removed from the environment,
733−-- its finalizer is called and it can never be written to again. Note
734−-- that this will throw any exceptions yoru finalizer will throw, and
735−-- that LogEnv is immutable, so it will not be removed in that case.
761+-- its finalizer is called so that it can never be written to again
762+-- and all pending writes are flushed. Note that this will throw any
763+-- exceptions yoru finalizer will throw, and that LogEnv is immutable,
764+-- so it will not be removed in that case.
736765closeScribe
737766 :: Text
738767 -- ^ Name of the scribe
@@ -927,6 +956,7 @@ tryWriteTBQueue q a = do
927956 unless full (writeTBQueue q a)
928957 return (not full)
929958
959+
930960-------------------------------------------------------------------------------
931961-- | Log with full context, but without any code location.
932962logF