e108a3d · typeable/katip

git.iko.soy/typeable/katip

on master help sign in

Merge pull request #17 from Soostone/14-clarify-context

e108a3dMichael Xavier11 years ago

katip/examples/example.hs+1−1

compare with master

unifiedsplit

@@ -22,7 +22,7 @@ import Katip

22-- lens_example for a slightly cleaner and more general pattern.

23main :: IO ()

24main = do

25− le <- initLogEnv "main" "production"

25+ le <- initLogEnv "MyApp" "production"

26 -- We'll set up a scribe that logs to stdout and will only log item

27 -- fields permitted for Verbosity 2 and will throw out Debug

28 -- messages entirely. Note that katip provides facilities like

katip/examples/example_lens.hs+1−1

@@ -38,7 +38,7 @@ makeClassy ''MyState

38-- lens_example for a slightly cleaner and more general pattern.

39main :: IO ()

40main = do

41− le <- initLogEnv "main" "production"

41+ le <- initLogEnv "MyApp" "production"

42 -- We'll set up a scribe that logs to stdout and will only log item

43 -- fields permitted for Verbosity 2 and will throw out Debug

44 -- messages entirely. Note that katip provides facilities like

katip/src/Katip.hs+100−7

@@ -26,9 +26,7 @@ module Katip

26 (

28 -- * Framework Types

29−

30− Katip (..)

31− , Namespace (..)

29+ Namespace (..)

32 , Environment (..)

30 , Environment (..)

33 , Severity (..)

31 , Severity (..)

34 , renderSeverity

32 , renderSeverity

@@ -41,9 +39,6 @@ module Katip

41 , PayloadSelection (..)

39 , PayloadSelection (..)

42 , Scribe (..)

40 , Scribe (..)

43 , LogEnv (..)

41 , LogEnv (..)

44− , KatipContext(..)

45− , AnyLogContext

46− , LogContexts, liftPayload

47 , SimpleLogPayload, sl

42 , SimpleLogPayload, sl

49 -- ** @lens@-compatible Lenses

44 -- ** @lens@-compatible Lenses

@@ -60,7 +55,7 @@ module Katip

60 , itemLoc

55 , itemLoc

61 , logEnvHost

56 , logEnvHost

62 , logEnvPid

57 , logEnvPid

63− , logEnvNs

58+ , logEnvApp

64 , logEnvEnv

59 , logEnvEnv

65 , logEnvTimer

60 , logEnvTimer

66 , logEnvScribes

61 , logEnvScribes

@@ -79,15 +74,23 @@ module Katip

79 , LogStr (..)

74 , LogStr (..)

80 , logStr, ls, showLS

75 , logStr, ls, showLS

77+ -- ** 'Katip' LoggingFunctions

78+ -- $katiplogging

79+ , Katip (..)

82 , logF

80 , logF

83 , logMsg

81 , logMsg

84 , logT

82 , logT

85 , logItem

83 , logItem

86 , logException

84 , logException

85+ -- ** 'KatipContext' Logging Functions

86+ -- $katipcontextlogging

87+ , KatipContext (..)

87 , logFM

88 , logFM

88 , logTM

89 , logTM

89 , logItemM

90 , logItemM

90 , logExceptionM

91 , logExceptionM

92+ , AnyLogContext

93+ , LogContexts, liftPayload

92 -- * Included Scribes

95 -- * Included Scribes

93 , mkHandleScribe

96 , mkHandleScribe

@@ -101,6 +104,8 @@ module Katip

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

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

102 , KatipContextT

105 , KatipContextT

103 , runKatipContextT

106 , runKatipContextT

107+ , katipAddNamespace

108+ , katipAddContext

104 ) where

109 ) where

105

110

106-------------------------------------------------------------------------------

111-------------------------------------------------------------------------------

@@ -108,3 +113,91 @@ import Katip.Core

108import Katip.Monadic

113import Katip.Monadic

109import Katip.Scribes.Handle

114import Katip.Scribes.Handle

110-------------------------------------------------------------------------------

115-------------------------------------------------------------------------------

116+

117+

118+{- $katiplogging

119+

120+ These logging functions use the basic 'Katip' constraint and thus

121+will require varying degrees of explicit detail such as 'Namespace'

122+and individual log items to be passed in. These can be described as

123+the primitives of Katip logging. If you find yourself making multiple

124+log statements within a logical logging context for your app, you may

125+want to look into the 'KatipContext' family of logging functions like

126+'logFM' and 'logTM'. 'KatipContext' in most applications should be

127+considered the default. Here's an example of the pain point:

128+

129+@

130+doDatabaseThings = do

131+ connId <- getConnectionId

132+ logF (ConnectionIDContext connId) "database" InfoS "Doing database stuff"

133+ \-\- ...

134+ logF (ConnectionIDContext connId) "database" InfoS "Wow, passing in the same context is getting tedious"

135+@

136+

137+Another pain point to look out for is nesting actions that log in

138+eachother. Let's say you were writing a web app. You want to capture

139+some detail such as the user's ID in the logs, but you also want that

140+info to show up in doDatabaseThings' logs so you can associate those

141+two pieces of information:

142+

143+

144+@

145+webRequestHandler = do

146+ uid <- getUserId

147+ logF (UserIDContext uid) "web" InfoS "Starting web request"

148+ doDatabaseThings

149+@

150+

151+In the above example, doDatabaseThings would overwrite that

152+UderIDContext with its own context and namespace. Sometimes this is

153+what you want and that's why 'logF' and other functions which only

154+require 'Katip' exist. If you are interested in combining log

155+contexts and namespaces, see 'KatipContext'.

156+-}

157+

158+

159+{- $katipcontextlogging

160+

161+ These logging functions use the 'KatipContext' constraint which is a

162+superclass of 'Katip' that also has a mechanism for keeping track of

163+the current context and namespace. This means a few things:

164+

165+1. Functions that use 'KatipContext' like 'logFM' and 'logTM' do not

166+require you to pass in 'LogItem's or 'Namespaces', they pull them from

167+the monadic environment.

168+

169+2. It becomes easy to add functions which add namespaces and/or

170+contexts to the current stack of them. You can (and should) make that

171+action scoped to a monadic action so that when it finishes, the

172+previous context and namespace will be automatically restored.

173+

174+

175+'KatipContextT' provides a simple, 'ReaderT'-based implementation of

176+the 'KatipContext' typeclass, and provides 'katipAddContext' and

177+'katipAddNamespace' functions to append to the context for the

178+duration of a block:

179+

180+

181+@

182+main = do

183+ le <- initLogEnv "MyApp" "production"

184+ \-\- set up scribes here

185+ runKatipContext le () "main" $ do

186+ katipAddNamespace "nextlevel" $ do

187+ $(logTM) InfoS "Logs here will have namespace MyApp.main.nextlevel"

188+

189+ katipAddContext TrivialContext $ do

190+ $(logTM) InfoS "Logs here will have context from TrivialContext"

191+

192+ katipAddContext AnotherContext $ do

193+ $(logTM) InfoS "Logs here will have context from TrivialContext *merged with* context from AnotherContext!"

194+

195+ $(logTM) InfoS "Log context restored to () and namespace to MyApp.main"

196+@

197+

198+'katipAddNamespace' and 'katipAddContext' are one-liners, implemented

199+in terms of 'local' from 'MonadReader'. If you have a custom monad

200+transformer stack and want to add your own version of these, check out

201+<https://github.com/Soostone/katip/tree/master/katip/examples these

202+examples>.

203+-}

katip/src/Katip/Core.hs+20−6

@@ -483,12 +483,18 @@ permitItem sev i = _itemSeverity i >= sev

483data LogEnv = LogEnv {

484 _logEnvHost :: HostName

485 , _logEnvPid :: ProcessID

486− , _logEnvNs :: Namespace

486+ , _logEnvApp :: Namespace

487+ -- ^ Name of application. This will typically never change. This

488+ -- field gets prepended to the namespace of your individual log

489+ -- messages. For example, if your app is MyApp and you write a log

490+ -- using "logItem" and the namespace "WebServer", the final

491+ -- namespace will be "MyApp.WebServer"

487 , _logEnvEnv :: Environment

492 , _logEnvEnv :: Environment

488 , _logEnvTimer :: IO UTCTime

493 , _logEnvTimer :: IO UTCTime

489 -- ^ Action to fetch the timestamp. You can use something like

494 -- ^ Action to fetch the timestamp. You can use something like

490 -- 'AutoUpdate' for high volume logs but note that this may cause

495 -- 'AutoUpdate' for high volume logs but note that this may cause

491− -- some output forms to display logs out of order.

496+ -- some output forms to display logs out of order. Alternatively,

497+ -- you could just use 'getCurrentTime'.

492 , _logEnvScribes :: M.Map Text Scribe

498 , _logEnvScribes :: M.Map Text Scribe

493 }

499 }

494makeLenses ''LogEnv

500makeLenses ''LogEnv

@@ -547,8 +553,16 @@ clearScribes = logEnvScribes .~ mempty

547

553

548

554

549-------------------------------------------------------------------------------

555-------------------------------------------------------------------------------

550−-- | Monads where katip logging actions can be performed

556+-- | Monads where katip logging actions can be performed. Katip is the

557+-- most basic logging monad. You will typically use this directly if

558+-- you either don't want to use namespaces/contexts heavily or if you

559+-- want to pass in specific contexts and/or namespaces at each log site.

560+--

561+-- For something more powerful, look at the docs for 'KatipContext',

562+-- which keeps a namespace and merged context. You can write simple

563+-- functions that add additional namespacing and merges additional

564+-- context on the fly.

551−class MonadIO m => Katip m where

565+class MonadIO m => Katip m where

552 getLogEnv :: m LogEnv

566 getLogEnv :: m LogEnv

553

567

554

568

@@ -623,7 +637,7 @@ logItem a ns loc sev msg = do

623 LogEnv{..} <- getLogEnv

637 LogEnv{..} <- getLogEnv

624 liftIO $ do

638 liftIO $ do

625 item <- Item

639 item <- Item

626− <$> pure _logEnvNs

640+ <$> pure _logEnvApp

627 <*> pure _logEnvEnv

641 <*> pure _logEnvEnv

628 <*> pure sev

642 <*> pure sev

629 <*> (mkThreadIdText <$> myThreadId)

643 <*> (mkThreadIdText <$> myThreadId)

@@ -632,7 +646,7 @@ logItem a ns loc sev msg = do

632 <*> pure a

646 <*> pure a

633 <*> pure msg

647 <*> pure msg

634 <*> _logEnvTimer

648 <*> _logEnvTimer

635− <*> pure (_logEnvNs <> ns)

649+ <*> pure (_logEnvApp <> ns)

636 <*> pure loc

650 <*> pure loc

637 FT.forM_ (M.elems _logEnvScribes) $ \ (Scribe h) -> h item

651 FT.forM_ (M.elems _logEnvScribes) $ \ (Scribe h) -> h item

638

652

katip/src/Katip/Monadic.hs+24

@@ -28,6 +28,8 @@ module Katip.Monadic

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

29 , KatipContextT(..)

30 , runKatipContextT

31+ , katipAddNamespace

32+ , katipAddContext

31 , KatipContextTState(..)

33 , KatipContextTState(..)

32 ) where

34 ) where

@@ -284,3 +286,25 @@ runKatipContextT :: (LogItem c) => LogEnv -> c -> Namespace -> KatipContextT m a

284runKatipContextT le ctx ns = flip runReaderT lts . unKatipContextT

286runKatipContextT le ctx ns = flip runReaderT lts . unKatipContextT

285 where

287 where

286 lts = KatipContextTState le (liftPayload ctx) ns

288 lts = KatipContextTState le (liftPayload ctx) ns

289+

290+

291+-------------------------------------------------------------------------------

292+katipAddNamespace

293+ :: (Monad m)

294+ => Namespace

295+ -> KatipContextT m a

296+ -> KatipContextT m a

297+katipAddNamespace ns (KatipContextT f) =

298+ KatipContextT (local (\r -> r { ltsNamespace = (ltsNamespace r) <> ns}) f)

299+

300+

301+-------------------------------------------------------------------------------

302+katipAddContext

303+ :: ( LogItem i

304+ , Monad m

305+ )

306+ => i

307+ -> KatipContextT m a

308+ -> KatipContextT m a

309+katipAddContext i (KatipContextT f) =

310+ KatipContextT (local (\r -> r { ltsContext = (ltsContext r) <> liftPayload i}) f)