f7c5ca4 · typeable/katip

git.iko.soy/typeable/katip

Rework docs a bit

Felt that katip was really missing a big codeblock in the beginning as that is the first thing a lot of devs look for.

commitf7c5ca464d8b8f3347ed9c2590cff20a72b4c720 authorMichael Xavier <michael@michaelxavier.net> dateMon 17 Jul 2017, 16:06 (9 years ago) parent5b57227

3 files changed+41−12

compare with master

unifiedsplit

katip/src/Katip.hs+33−7 katip/src/Katip/Core.hs+3−1 katip/src/Katip/Monadic.hs+5−4

katip/src/Katip.hs+33−7

@@ -1,7 +1,32 @@

1−-- | Includes all of the API's youll need to use Katip. Be sure to

1+-- | Includes all of the APIs youll need to use Katip. Be sure to

22-- check out the included @examples@ directory for an example of

33-- usage.

44--

5+-- Here's a basic example:

6+--

7+-- @

8+--

9+-- import Control.Exception

10+-- import Katip

11+--

12+-- main :: IO ()

13+-- main = do

14+-- handleScribe <- mkHandleScribe ColorIfTerminal stdout InfoS V2

15+-- let makeLogEnv = registerScribe "stdout" handleScribe defaultScribeSettings =<< initLogEnv "MyApp" "production"

16+-- -- closeScribes will stop accepting new logs, flush existing ones and clean up resources

17+-- bracket makeLogEnv closeScribes $ \le -> do

18+-- let initialContext = () -- this context will be attached to every log in your app and merged w/ subsequent contexts

19+-- let initialNamespace = "main"

20+-- runKatipContextT le initialContext initialNamespace $ do

21+-- $(logTM) InfoS "Hello Katip"

22+-- -- This adds a namespace to the current namespace and merges a piece of contextual data into your context

23+-- katipAddNamespace "additional_namespace" $ katipAddContext (sl "some_context" True) $ do

24+-- $(logTM) WarningS "Now we're getting fancy"

25+-- katipNoLogging $ do

26+-- $(logTM) DebugS "You will never see this!"

27+--

28+-- @

29+--

530-- To get up and running, the workflow is generally:

631--

732-- * Set up a 'LogEnv' using 'initLogEnv'.

@@ -40,7 +65,7 @@ module Katip

4065 , Scribe (..)

4166 , LogEnv (..)

4267 , SimpleLogPayload, sl

43− , defaultScribeSettings --TODO: lenses and whatnot to avoid breakage

68+ , defaultScribeSettings

4469 , ScribeSettings

4570 , scribeBufferSize

4671 , _scribeBufferSize

@@ -64,7 +89,7 @@ module Katip

6489 , logEnvTimer

6590 , logEnvScribes

6691

67− -- * A Built-in Monad For Logging

92+ -- * A Built-in Monad For Simple Logging

6893 , KatipT (..)

6994 , runKatipT

7095

@@ -90,7 +115,7 @@ module Katip

90115 , logT

91116 , logItem

92117 , logException

93− -- ** 'KatipContext' Logging Functions

118+ -- ** 'KatipContext': Logging With Context

94119 -- $katipcontextlogging

95120 , KatipContext (..)

96121 , logFM

@@ -99,6 +124,10 @@ module Katip

99124 , logExceptionM

100125 , AnyLogContext

101126 , LogContexts, liftPayload

127+ -- *** Temporarily Changing Logging Behavior

128+ , katipAddNamespace

129+ , katipAddContext

130+ , katipNoLogging

102131

103132 -- * Included Scribes

104133 , mkHandleScribe

@@ -112,9 +141,6 @@ module Katip

112141 -- * KatipContextT - Utility transformer that provides Katip and KatipContext instances

113142 , KatipContextT

114143 , runKatipContextT

115− , katipAddNamespace

116− , katipAddContext

117− , katipNoLogging

118144 ) where

119145

120146-------------------------------------------------------------------------------

katip/src/Katip/Core.hs+3−1

@@ -771,7 +771,9 @@ instance (Katip m) => Katip (ResourceT m) where

771771

772772

773773-------------------------------------------------------------------------------

774−-- | A concrete monad you can use to run logging actions.

774+-- | A concrete monad you can use to run logging actions. Use this if

775+-- you prefer an explicit monad transformer stack and adding layers as

776+-- opposed to implementing 'Katip' for your monad.

775777newtype KatipT m a = KatipT { unKatipT :: ReaderT LogEnv m a }

776778 deriving ( Functor, Applicative, Monad, MonadIO

777779 , MonadMask, MonadCatch, MonadThrow, MonadTrans, MonadBase b)

katip/src/Katip/Monadic.hs+5−4

@@ -311,10 +311,11 @@ logExceptionM action sev = action `catchAny` \e -> f e >> throwM e

311311

312312-------------------------------------------------------------------------------

313313-- | Provides a simple transformer that defines a 'KatipContext'

314−-- instance for a fixed namespace and context. You will typically only

315−-- use this if you are forced to run in IO but still want to have your

316−-- log context. This is the slightly more powerful version of KatipT

317−-- in that it provides KatipContext instead of just Katip. For instance:

314+-- instance for a fixed namespace and context. Just like 'KatipT', you

315+-- should use this if you prefer an explicit transformer stack and

316+-- don't want to (or cannot) define 'KatipContext' for your monad

317+-- . This is the slightly more powerful version of KatipT in that it

318+-- provides KatipContext instead of just Katip. For instance:

318319--

319320-- @

320321-- threadWithLogging = do