caster: Multicast, thread-safe, and fast logger.

[ bsd3, library, system ] [ Propose Tags ]

Please see the README on GitHub at https://github.com/kirisaki/caster#readme


[Skip to Readme]
Versions [faq] 0.0.1.0, 0.0.2.0, 0.0.2.1, 0.0.3.0
Change log CHANGELOG.md
Dependencies base (>=4.10), bytestring (>=0.10.8.2), fast-builder (>=0.1.0.0), stm (>=2.5.0.0), text (>=1.2.3.1), unix-time (>=0.4.5) [details]
License BSD-3-Clause
Copyright Akihito KIRISAKI
Author Akihito KIRISAKI
Maintainer kirisaki@klaraworks.net
Category System
Home page https://github.com/kirisaki/caster#readme
Bug tracker https://github.com/kirisaki/caster/issues
Source repo head: git clone https://github.com/kirisaki/caster
Uploaded by A_kirisaki at Mon May 6 08:06:53 UTC 2019
Distributions NixOS:0.0.3.0, Stackage:0.0.3.0
Downloads 289 total (35 in the last 30 days)
Rating (no votes yet) [estimated by rule of succession]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2019-05-06 [all 1 reports]

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for caster-0.0.3.0

[back to package description]

caster

caster is a multicast, thread-safe and fast logger. It's convenient when log towards multiple outputs, for example, when you want to log to stdout and files same time. It's possible to change format and log level each outputs. Also, it converts text-like values and Show instances into log messages automatically.

Usage

First, the logger requires concurrency.

import Control.Concurrent

Then, prepare to use the logger. In following code, make LogQueue, LogChan and Listener, start threads which relay messages from LogChan to the outputs and one which broadcasts messages to LogChan. Be careful not to change the order of relayLog and broadcastLog. It causes that messages at the first are not logged correctly.

import System.IO
import System.Log.Caster

main = do
  chan <- newLogChan
  lq <- newLogQueue

  -- log to a file..
  handle <- openFile "./foo.log" "caster_test_0.log"
  let FileListener = handleListener defaultFormatter handle
  _ <- forkIO $ relayLog chan LogDebug fileListener

  -- log to stdout.
  _ <- forkIO $ relayLog chan LogInfo stdoutListener

  -- start to broadcast.
  _ <- forkIO $ broadcastLog lq chan
  
  -- give the LogQueue to the function which you want to log in.
  someFunc lq

Last, push a message into the LogQueue with given functions in order to log.


someFunc :: LogQueue -> IO ()
someFunc lq = do

  -- log levels are matched to syslog.
  -- if you use OverloadedStrings, need to add type annotation.
  debug lq ("debug message" :: String)
  
  -- or you can use helper operator or helper function.
  info lq $: "info messages"
  info lq $ fix  "info messages"
  
  -- if the type is obviously, need not to annotate.
  let msg = Data.Text.pack "notice message"
  notice lq msg
  
  -- it's possible to give incetanse of Show.
  warn lq True
  
  -- there is the useful operator which concatrates text-like values.
  -- the values are converted into byte string as utf-8.
  let text = "foo" :: Data.Text.Text
  let bs = "bar" :: Data.ByteString.Lazy.ByteString
  err lq $ text <:> bs <:> fix "baz"
  

The logger requires to be given LogQueue, so functions which log need to take LogQueue as a parameter. You can inject LogQueue with Reader Monad and so on. System.Log.Caster.Monad provides MonadCaster for ReaderT patteren. Another way, you can use Data.Reflection.

{-# LANGUAGE FlexibleContexts          #-}
{-# LANGUAGE RankNTypes                #-}

import Control.Concurrent
import Control.Monad
import Data.Reflection
import System.Log.Caster

type UseLogger = Given LogQueue

useLogger :: UseLogger => LogQueue
useLogger = given

someIO :: UseLogger => IO ()
someIO = do
  critical useLogger "critical message"
  alert useLogger "alert message"
  emergency useLogger "..."
  
inject :: (UseLogger => a) -> IO a
inject io = do
  lq <- newLogQueue
  give io lq
  
main :: IO ()
main = do
  chan <- newLogChan
  _ <- forkIO $ relayLog chan LogDebug stdoutListener
  join $ inject someIO