b6e415e · typeable/katip

git.iko.soy/typeable/katip

More fine touches for release

commitb6e415ed4743cc36a630c4ab2acd4b74a201ad1b authorMichael Xavier <michael@michaelxavier.net> dateFri 4 Mar 2016, 10:14 (11 years ago) parentd429ec8

7 files changed+83−8

compare with master

unifiedsplit

katip/examples/example.hs+17−1 katip/examples/example_lens.hs+17−1 katip/katip.cabal+3−1 katip/src/Katip.hs+20 katip/src/Katip/Core.hs+17−2 katip/src/Katip/Monadic.hs+8−3 katip/src/Katip/Scribes/Handle.hs+1

katip/examples/example.hs+17−1

@@ -12,6 +12,7 @@ module Main

1212import Control.Monad.Reader

1313import Data.Aeson

1414import Data.Monoid as M

15+import System.IO (stdout)

1516-------------------------------------------------------------------------------

1617import Katip

1718-------------------------------------------------------------------------------

@@ -21,9 +22,24 @@ import Katip

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

2223main :: IO ()

2324main = do

24− s <- MyState M.mempty mempty <$> initLogEnv mempty (Environment "production")

25+ le <- initLogEnv "main" "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

29+ -- 'unregisterScribe' and 'registerScribe' to make it possible to

30+ -- hot-swap scribes at runtime if you need to.

31+ handleScribe <- mkHandleScribe ColorIfTerminal stdout InfoS V2

32+ let le' = registerScribe "stdout" handleScribe le

33+ let s = MyState M.mempty mempty le'

2534 runStack s $ do

2635 $(logTM) InfoS "Started"

36+ -- this will add "confrabulation" to the current namespace, making

37+ -- logs made under this block have the namespace of

38+ -- "main.confrabulation". Further, ConfrabLogCTX's key/value

39+ -- context will also get merged with the context above it. You can

40+ -- use this to stack up various contextual details throughout your

41+ -- code and they will be flattened out and combined in the log

42+ -- output.

2743 addNamespace "confrabulation" $ addContext (ConfrabLogCTX 42) $ do

2844 $(logTM) DebugS "Confrabulating widgets, with extra namespace and context"

2945 confrabulateWidgets

katip/examples/example_lens.hs+17−1

@@ -13,6 +13,7 @@ import Control.Lens hiding ((.=))

1313import Control.Monad.Reader

1414import Data.Aeson

1515import Data.Monoid as M

16+import System.IO (stdout)

1617-------------------------------------------------------------------------------

1718import Katip

1819-------------------------------------------------------------------------------

@@ -37,9 +38,24 @@ makeClassy ''MyState

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

3839main :: IO ()

3940main = do

40− s <- MyState M.mempty mempty <$> initLogEnv mempty (Environment "production")

41+ le <- initLogEnv "main" "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

45+ -- 'unregisterScribe' and 'registerScribe' to make it possible to

46+ -- hot-swap scribes at runtime if you need to.

47+ handleScribe <- mkHandleScribe ColorIfTerminal stdout InfoS V2

48+ let le' = registerScribe "stdout" handleScribe le

49+ let s = MyState M.mempty mempty le'

4150 runStack s $ do

4251 $(logTM) InfoS "Started"

52+ -- this will add "confrabulation" to the current namespace, making

53+ -- logs made under this block have the namespace of

54+ -- "main.confrabulation". Further, ConfrabLogCTX's key/value

55+ -- context will also get merged with the context above it. You can

56+ -- use this to stack up various contextual details throughout your

57+ -- code and they will be flattened out and combined in the log

58+ -- output.

4359 addNamespace "confrabulation" $ addContext (ConfrabLogCTX 42) $ do

4460 $(logTM) DebugS "Confrabulating widgets, with extra namespace and context"

4561 confrabulateWidgets

katip/katip.cabal+3−1

@@ -21,7 +21,9 @@ description:

2121 * Designed to be highly configurable. Can be adjusted both with

2222 verbosity, which dictates how much of the log structure should

2323 actually get logged, and severity. Each individual scribe can be

24− configured to a different log severity.

24+ configured to a different log severity. It is even possible to at

25+ runtime swap out and replace loggers, allowing for swapping in

26+ verbose debug logging at runtime if you want.

2527

2628 A note on the name: Katip is Turkish for scribe.

2729

katip/src/Katip.hs+20

@@ -1,3 +1,23 @@

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

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

3+-- usage.

4+--

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

6+--

7+-- * Set up a 'LogEnv' using 'initLogEnv'.

8+--

9+-- * Add 'Scribe's using 'registerScribe'.

10+--

11+-- * Either use 'KatipT' or 'KatipContextT' for a pre-built

12+-- transformer stack or add 'Katip' and 'KatipContext' instances to

13+-- your own transformer stack. If you do the latter, you may want to

14+-- look in the @examples@ dir for some tips on composing contexts and

15+-- namespaces.

16+--

17+-- * Define some structured log data throughout your application and

18+-- implement 'ToObject' and 'LogItem' for them.

19+--

20+-- * Begin logging with 'logT', 'logTM', etc.

121module Katip

222 (

323

katip/src/Katip/Core.hs+17−2

@@ -53,6 +53,11 @@ import System.Posix

5353

5454

5555-------------------------------------------------------------------------------

56+-- | Represents a heirarchy of namespaces going from general to

57+-- specific. For instance: ["processname", "subsystem"]. Note that

58+-- single-segment namespaces can be created using

59+-- IsString/OverloadedStrings, so "foo" will result in Namespace

60+-- ["foo"].

5661newtype Namespace = Namespace { unNamespace :: [Text] }

5762 deriving (Eq,Show,Read,Ord,Generic,ToJSON,FromJSON,Monoid)

5863

@@ -168,6 +173,7 @@ ls = logStr

168173

169174

170175-------------------------------------------------------------------------------

176+-- | Convert any showable type into a LogStr.

171177showLS :: Show a => a -> LogStr

172178showLS = ls . show

173179

@@ -181,6 +187,7 @@ newtype ThreadIdText = ThreadIdText {

181187mkThreadIdText :: ThreadId -> ThreadIdText

182188mkThreadIdText = ThreadIdText . T.pack . show

183189

190+

184191-------------------------------------------------------------------------------

185192-- | This has everything each log message will contain.

186193data Item a = Item {

@@ -341,7 +348,15 @@ instance ToObject ()

341348instance ToObject A.Object

342349

343350-------------------------------------------------------------------------------

344−-- | Payload objects need instances of this class.

351+-- | Payload objects need instances of this class. LogItem makes it so

352+-- that you can have very verbose items getting logged with lots of

353+-- extra fields but under normal circumstances, if your scribe is

354+-- configured for a lower verbosity level, it will only log a

355+-- selection of those keys. Furthermore, each 'Scribe' can be

356+-- configured with a different 'Verbosity' level. You could even use

357+-- 'registerScribe', 'unregisterScribe', and 'clearScribes' to at

358+-- runtime swap out your existing scribes for more verbose debugging

359+-- scribes if you wanted to.

345360--

346361-- When defining 'payloadKeys', don't redundantly declare the same

347362-- keys for higher levels of verbosity. Each level of verbosity

@@ -666,7 +681,7 @@ getLoc = [| $(location >>= liftLoc) |]

666681

667682

668683-------------------------------------------------------------------------------

669−-- | 'Loc'-tagged logging when using template-haskell is OK.

684+-- | 'Loc'-tagged logging when using template-haskell.

670685--

671686-- @$(logT) obj mempty InfoS "Hello world"@

672687logT :: ExpQ

katip/src/Katip/Monadic.hs+8−3

@@ -69,7 +69,10 @@ data AnyLogContext where

6969

7070-------------------------------------------------------------------------------

7171-- | Heterogeneous list of log contexts that provides a smart

72−-- 'LogContext' instance for combining multiple payload policies.

72+-- 'LogContext' instance for combining multiple payload policies. This

73+-- is critical for log contexts deep down in a stack to be able to

74+-- inject their own context without worrying about other context that

75+-- has already been set.

7376newtype LogContexts = LogContexts [AnyLogContext] deriving (Monoid)

7477

7578instance ToJSON LogContexts where

@@ -90,7 +93,8 @@ instance LogItem LogContexts where

9093

9194

9295-------------------------------------------------------------------------------

93−-- | Lift a log context into the generic wrapper

96+-- | Lift a log context into the generic wrapper so that it can

97+-- combine with the existing log context.

9498liftPayload :: (LogItem a) => a -> LogContexts

9599liftPayload = LogContexts . (:[]) . AnyLogContext

96100

@@ -164,7 +168,8 @@ logFM sev msg = do

164168

165169

166170-------------------------------------------------------------------------------

167−-- | 'Loc'-tagged logging when using template-haskell is OK. Automatically supplies payload and namespace.

171+-- | 'Loc'-tagged logging when using template-haskell. Automatically

172+-- supplies payload and namespace.

168173--

169174-- @$(logt) InfoS "Hello world"@

170175logTM :: ExpQ

katip/src/Katip/Scribes/Handle.hs+1

@@ -49,6 +49,7 @@ data ColorStrategy

4949

5050

5151-------------------------------------------------------------------------------

52+-- | Logs to a file handle such as stdout, stderr, or a file.

5253mkHandleScribe :: ColorStrategy -> Handle -> Severity -> Verbosity -> IO Scribe

5354mkHandleScribe cs h sev verb = do

5455 hSetBuffering h LineBuffering