The main ideas of this log library are:
- we don't want to see all unnecessary trace messages when there are no errors,
- but we want to have all possible information about error.
This library is based on scopes. Every scope have a name, and logs traces only if there are some errors. Otherwise it logs only message with
Let's start by simple example:
test :: ReaderT Log IO () test = scope "test" $ do log Trace "Trace message" log Info "Starting test" s <- liftIO T.getLine when (T.null s) $ log Error "Oh no!" log Trace $ T.concat ["Your input: ", s]
When you input some valid string, it will produce output:
08/10/12 22:23:34 INFO test> Starting test abc
wihtout any traces
But if you input empty strings, you'll get:
08/10/12 22:24:20 INFO test> Starting test 08/10/12 22:24:20 TRACE test> Trace message 08/10/12 22:24:21 ERROR test> Oh no! 08/10/12 22:24:21 TRACE test> Your input:
There are three scope functions:
scope_ is basic function.
scope catches all exceptions and logs error with it, then rethrows.
scoper is like
scope, but logs (with
Trace level) result of do-block.
Of course, scopes can be nested:
test :: ReaderT Log IO () test = scope "test" $ do log Trace "test trace" foo log Info "some info" bar foo :: ReaderT Log IO () foo = scope "foo" $ do log Trace "foo trace" bar :: ReaderT Log IO () bar = scope "bar" $ do log Trace "bar trace" log Error "bar error"
08/10/12 22:32:53 INFO test> some info 08/10/12 22:32:53 TRACE test/bar> bar trace 08/10/12 22:32:53 ERROR test/bar> bar error
Note, no messages for "foo" and no trace messages for "test", because error was in "bar", not in "foo".
Code to run log:
rules :: Rules rules =  run :: IO () run = do l <- newLog (constant rules) [logger text console] withLog l test
Sometimes we need to trace function, but we don't want to write all traces. We can get this by setting rules. Rules changes politics for specified scope-path (scope-path is list of nested scopes, for example ["test"], ["test", "bar"], ["test", "bar", "baz", "quux"] etc.)
For example, we want to trace function
rules = [ rule root $ use defaultPolitics, rule (relative ["foo"]) $ low Trace]
We may adjust politics for scope
foo, that is nested directly in scope
rules = [ rule root $ use defaultPolitics, relative ["quux", "foo"] $ low Trace]
And, of course, we may specify absolute path:
rules = [ rule root $ use defaultPolitics, absolute ["bar", "baz", "foo"] $ low Trace]
Politics will be changed only for scope "foo", which is nested directly in "baz", which is nested in "bar", which is top scope.
Another way to define rule is using special functions from System.Log.Config module:
rules = [ "/" %= use defaultPolitics, "/bar/baz/foo" %= low Trace, "quux/foo" %= low Debug]
One more way to use special syntax for rules:
rules = parseRules_ $ T.unlines [ "/: use default", "/bar/baz/foo: low trace", "quux/foo: low debug"]
Here "/" is for root, "/path" for absolute path, "path" for relative and "path/" for child of "path" (which may be also prefixed with "/" to be absolute)
This syntax is useful to config log by file. Having file "log.cfg":
/: use default /bar/baz/foo: low trace quux/foo: low debug
We can use it to config log
l <- newLog (fileCfg "log.cfg" 60) [logger text console]
where 60 is period (in seconds) of auto reload or 0 for no reloading.