co-log-core

Composable Contravariant Comonadic Logging Library

https://github.com/kowainik/co-log

Version on this page:0.2.1.1@rev:1
LTS Haskell 22.43:0.3.2.2
Stackage Nightly 2024-12-05:0.3.2.2
Latest on Hackage:0.3.2.2

See all snapshots co-log-core appears in

MPL-2.0 licensed by Dmitrii Kovanikov
Maintained by Kowainik
This version can be pinned in stack with:co-log-core-0.2.1.1@sha256:1209cb589cf431c640f79d63b38b6cc8912a9f8397502b8c13e0959b13212bd6,3574

Module documentation for 0.2.1.1

co-log

GitHub CI Build status Windows build MPL-2.0 license

co-log-core Hackage Stackage LTS Stackage Nightly
co-log Hackage Stackage LTS Stackage Nightly
co-log-polysemy Hackage Stackage LTS Stackage Nightly

co-log is a composable and configurable logging framework. It combines all the benefits of Haskell idioms to provide a reasonable and convenient interface. Though it uses some advanced concepts in its core, we are striving to provide beginner-friendly API. The library also contains complete documentation with a lot of beginner-friendly examples, explanations and tutorials to guide users. The combination of a pragmatic approach to logging and fundamental Haskell abstractions allows us to create a highly composable and configurable logging framework.

If you’re interested in how different Haskell typeclasses are used to implement core functions of co-log, you can read the following blog post which goes into detail about internal implementation specifics:

co-log is also modular on the level of packages. We care a lot about a low dependency footprint so you can build your logging only on top of the minimal required interface for your use-case. This repository contains the following packages:

  • co-log-core: lightweight package with basic data types and general idea which depends only on base.
  • co-log: taggless final implementation of logging library based on co-log-core.
  • co-log-polysemy: implementation of logging library based on co-log-core and the polysemy extensible effects library.
  • co-log-benchmark: benchmarks of the co-log library.

To provide a more user-friendly introduction to the library, we’ve created the tutorial series which introduces the main concepts behind co-log smoothly:

co-log also cares about concurrent logging. For this purpose we have the concurrent-playground executable where we experiment with different multithreading scenarios to test the library’s behavior. You can find it here:

Benchmarks

co-log is compared with basic functions like putStrLn. Since IO overhead is big enough, every benchmark dumps 10K messages to output. If a benchmark’s name doesn’t contain Message then this benchmark simply dumps the string "message" to output, otherwise it works with the Message data type from the co-log library.

To run benchmarks, use the following command:

cabal v2-run co-log-bench
Benchmarks Time for 10K messages
Prelude.putStrLn 5.117ms
Text.putStrLn 9.220ms
ByteString.putStrLn 2.971ms
mempty 1.181ms
logStringStdout 5.107ms
logPrint 5.248ms
logTextStdout 5.351ms
logByteStringStdout 2.933ms
logByteStringStderr 17.482ms
ByteString > (stdout <> stderr) 17.715ms
Message > format > stdout 9.188ms
Message > format > ByteString > stdout 3.524ms
Message{callstack} > format > stdout 9.139ms
Message{callstack:5} > format > stdout 9.464ms
Message{callstack:50} > format > stdout 9.439ms
Message{Time,ThreadId} > format > stdout 54.160ms
Message{Time,ThreadId} > format > ByteString > stdout 54.137ms

Changes

Change log

co-log-core uses PVP Versioning. The change log is available on GitHub.

0.2.1.1 — Apr 18, 2020

  • #186: Support GHC-8.10.1.

0.2.1.0 — Jan 19, 2020

  • #139: Add (unrepresentable) Functor instance for LogAction with the custom type-error. (by @vrom911)
  • #148: Support GHC-8.8.2. (by @chshersh)
  • #122: Add the separate combinator. (by @vrom911)
  • #125: Add monadic versions of contravariant functions. (by @piq9117)
  • #138: Add hoistLogAction — higher-order transformation function. (by @jiribenes)
  • #123: Write default implementation to getLogAction via logActionL. (by @SanchayanMaity)

0.2.0.0 — May 5, 2019

  • #85: Move overLogAction to HasLog typeclass
  • #101: Add logActionL lens with default implementation to HasLog type class.
  • #99: Add comonadic combinators: duplicate and multiplicate.
  • #78: Improve documentation significantly.

0.1.1 — Nov 15, 2018

  • #63: Add logPrint, logPrintStderr, logPrintHandle and withLogPrintFile to Colog.Core.IO.
  • #46: Moves logStringStdout, logStringStderr, logStringHandle, withLogStringFile from Colog.Actions to Colog.Core.IO.
  • #48: Adds liftLogIO function.
  • #49: Add <& and &>operators for unLogAction.
  • #47: Add doctest tests.
  • #13: Add .cabal file description and improve documentation.
  • #39: Support GHC-8.2.2 and GHC-8.6.2.

0.1.0

  • #38: Rename cbind to cmapM.

  • #37: Add base bounds.

0.0.0

  • Initially created.