3d7422c · typeable/katip

git.iko.soy/typeable/katip

Merge branch 'docs'

commit3d7422c5bbc1f33e6e24924967fe3ff9568d7d76 authorMichael Xavier <michael@michaelxavier.net> dateTue 18 Jul 2017, 08:50 (9 years ago) parent9e7b795 25abaa0

9 files changed+153−55

compare with master

unifiedsplit

.travis.yml+1 katip-elasticsearch/examples/example.hs+33 katip-elasticsearch/katip-elasticsearch.cabal+1 katip-elasticsearch/src/Katip/Scribes/ElasticSearch.hs+32−1 katip/examples/example.hs+23−21 katip/examples/example_lens.hs+22−21 katip/src/Katip.hs+33−7 katip/src/Katip/Core.hs+3−1 katip/src/Katip/Monadic.hs+5−4

.travis.yml+1

@@ -52,6 +52,7 @@ script:

5252 - stack $ARGS bench

5353 - stack $ARGS build

5454 - for f in katip/examples/*.hs; do stack $ARGS ghc -- -Wall -Werror $f -o /dev/null; done

55+ - for f in katip-elasticsearch/examples/*.hs; do stack $ARGS ghc -- -Wall -Werror $f -o /dev/null; done

5556 - stack $ARGS sdist

5657

5758# Caching so the next build will be fast too.

katip-elasticsearch/examples/example.hsnew file+33

@@ -0,0 +1,33 @@

1+{-# LANGUAGE OverloadedStrings #-}

2+module Main

3+ ( main

4+ ) where

7+-------------------------------------------------------------------------------

8+import Control.Exception

9+import Database.V5.Bloodhound

10+import Network.HTTP.Client

11+-------------------------------------------------------------------------------

12+import Katip

13+import Katip.Scribes.ElasticSearch

14+-------------------------------------------------------------------------------

15+

16+

17+main :: IO ()

18+main = do

19+ mgr <- newManager defaultManagerSettings

20+ let bhe = mkBHEnv (Server "localhost") mgr

21+ esScribe <- mkEsScribe

22+ -- Reasonable for production

23+ defaultEsScribeCfgV5

24+ -- Reasonable for single-node in development

25+ -- defaultEsScribeCfgV5 { essIndexSettings = IndexSettings (ShardCound 1) (ReplicaCount 0)}

26+ bhe

27+ (IndexName "all-indices-prefixed-with")

28+ (MappingName "application-logs")

29+ DebugS

30+ V3

31+ let mkLogEnv = registerScribe "es" esScribe defaultScribeSettings =<< initLogEnv "MyApp" "production"

32+ bracket mkLogEnv closeScribes $ \le -> runKatipT le $ do

33+ logMsg "ns" InfoS "This goes to elasticsearch"

katip-elasticsearch/katip-elasticsearch.cabal+1

@@ -14,6 +14,7 @@ extra-source-files:

1414 README.md

1515 changelog.md

1616 bench/Main.hs

17+ examples/example.hs

1718 test/Main.hs

1819tested-with: GHC == 7.8.4, GHC== 7.10.3

1920

katip-elasticsearch/src/Katip/Scribes/ElasticSearch.hs+32−1

@@ -4,7 +4,38 @@

44-- choice. Supports ElasticSearch servers with version 1.x or 5.x by

55-- way of different configs.

66--

7−-- == __Important Note on Index Settings__

7+-- Example of configuring for ES5:

8+--

9+-- @

10+--

11+-- import Control.Exception

12+-- import Database.V5.Bloodhound

13+-- import Network.HTTP.Client

14+-- import Katip

15+-- import Katip.Scribes.ElasticSearch

16+--

17+--

18+-- main :: IO ()

19+-- main = do

20+-- mgr <- newManager defaultManagerSettings

21+-- let bhe = mkBHEnv (Server "localhost") mgr

22+-- esScribe <- mkEsScribe

23+-- -- Reasonable for production

24+-- defaultEsScribeCfgV5

25+-- -- Reasonable for single-node in development

26+-- -- defaultEsScribeCfgV5 { essIndexSettings = IndexSettings (ShardCound 1) (ReplicaCount 0)}

27+-- bhe

28+-- (IndexName "all-indices-prefixed-with")

29+-- (MappingName "application-logs")

30+-- DebugS

31+-- V3

32+-- let mkLogEnv = registerScribe "es" esScribe defaultScribeSettings =<< initLogEnv "MyApp" "production"

33+-- bracket mkLogEnv closeScribes $ \le -> runKatipT le $ do

34+-- logMsg "ns" InfoS "This goes to elasticsearch"

35+--

36+-- @

37+--

38+-- __Important Note on Index Settings__

839--

940-- 'defaultEsScribeCfg' inherits a set of default index settings from

1041-- the @bloodhound@ package. These settings at this time of writing

katip/examples/example.hs+23−21

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

1313

1414-------------------------------------------------------------------------------

1515import qualified Control.Applicative as A

16+import Control.Exception

1617import Control.Monad.Base

1718import Control.Monad.Reader

1819import Control.Monad.Trans.Control

@@ -32,28 +33,29 @@ main = do

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

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

3435 -- 'unregisterScribe' and 'registerScribe' to make it possible to

35− -- hot-swap scribes at runtime if you need to.

36+ -- hot-swap scribes at runtime if you need to. 'closeScribes' is

37+ -- blocking and flushes all messages out of a scribe and cleans up

38+ -- resources that were allocated at creation.

3639 handleScribe <- mkHandleScribe ColorIfTerminal stdout InfoS V2

37− le <- registerScribe "stdout" handleScribe defaultScribeSettings =<< initLogEnv "MyApp" "production"

38− let s = MyState M.mempty mempty le

39− runStack s $ do

40− $(logTM) InfoS "Started"

41− -- this will add "confrabulation" to the current namespace, making

42− -- logs made under this block have the namespace of

43− -- "main.confrabulation". Further, ConfrabLogCTX's key/value

44− -- context will also get merged with the context above it. You can

45− -- use this to stack up various contextual details throughout your

46− -- code and they will be flattened out and combined in the log

47− -- output.

48− katipAddNamespace "confrabulation" $ katipAddContext (ConfrabLogCTX 42) $ do

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

50− confrabulateWidgets

51− $(logTM) InfoS "Namespace and context are back to normal"

52− katipNoLogging $

53− $(logTM) DebugS "You'll never see this log message!"

54− -- This blocking call flushes all in-flight messages through

55− -- handlers and then finalizes each scribe.

56− void (closeScribes le)

40+ let mkLogEnv = registerScribe "stdout" handleScribe defaultScribeSettings =<< initLogEnv "MyApp" "production"

41+ bracket mkLogEnv closeScribes $ \le -> do

42+ let s = MyState M.mempty mempty le

43+ runStack s $ do

44+ $(logTM) InfoS "Started"

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

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

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

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

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

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

51+ -- output.

52+ katipAddNamespace "confrabulation" $ katipAddContext (ConfrabLogCTX 42) $ do

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

54+ confrabulateWidgets

55+ $(logTM) InfoS "Namespace and context are back to normal"

56+ katipNoLogging $

57+ $(logTM) DebugS "You'll never see this log message!"

58+

5759

5860-------------------------------------------------------------------------------

5961newtype ConfrabLogCTX = ConfrabLogCTX Int

katip/examples/example_lens.hs+22−21

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

1313

1414-------------------------------------------------------------------------------

1515import Control.Applicative as A

16+import Control.Exception

1617import Control.Lens hiding ((.=))

1718import Control.Monad.Base

1819import Control.Monad.Reader

@@ -47,28 +48,28 @@ main = do

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

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

4950 -- 'unregisterScribe' and 'registerScribe' to make it possible to

50− -- hot-swap scribes at runtime if you need to.

51+ -- hot-swap scribes at runtime if you need to. 'closeScribes' is

52+ -- blocking and flushes all messages out of a scribe and cleans up

53+ -- resources that were allocated at creation.

5154 handleScribe <- mkHandleScribe ColorIfTerminal stdout InfoS V2

52− le <- registerScribe "stdout" handleScribe defaultScribeSettings =<< initLogEnv "MyApp" "production"

53− let s = MyState M.mempty mempty le

54− runStack s $ do

55− $(logTM) InfoS "Started"

56− -- this will add "confrabulation" to the current namespace, making

57− -- logs made under this block have the namespace of

58− -- "main.confrabulation". Further, ConfrabLogCTX's key/value

59− -- context will also get merged with the context above it. You can

60− -- use this to stack up various contextual details throughout your

61− -- code and they will be flattened out and combined in the log

62− -- output.

63− katipAddNamespace "confrabulation" $ katipAddContext (ConfrabLogCTX 42) $ do

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

65− confrabulateWidgets

66− $(logTM) InfoS "Namespace and context are back to normal"

67− katipNoLogging $

68− $(logTM) DebugS "You'll never see this log message!"

69− -- This blocking call flushes all in-flight messages through

70− -- handlers and then finalizes each scribe.

71− void (closeScribes le)

55+ let mkLogEnv = registerScribe "stdout" handleScribe defaultScribeSettings =<< initLogEnv "MyApp" "production"

56+ bracket mkLogEnv closeScribes $ \le -> do

57+ let s = MyState M.mempty mempty le

58+ runStack s $ do

59+ $(logTM) InfoS "Started"

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

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

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

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

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

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

66+ -- output.

67+ katipAddNamespace "confrabulation" $ katipAddContext (ConfrabLogCTX 42) $ do

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

69+ confrabulateWidgets

70+ $(logTM) InfoS "Namespace and context are back to normal"

71+ katipNoLogging $

72+ $(logTM) DebugS "You'll never see this log message!"

7273

7374

7475-------------------------------------------------------------------------------

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