katip
A structured logging framework.
https://github.com/Soostone/katip
Version on this page: | 0.8.3.0 |
LTS Haskell 22.39: | 0.8.8.2 |
Stackage Nightly 2024-10-31: | 0.8.8.2 |
Latest on Hackage: | 0.8.8.2 |
katip-0.8.3.0@sha256:8a67c0aec3ba1f0eabcfae443cb909e4cf9405e29bac99ccf1420f1f1bbda9c4,4097
Module documentation for 0.8.3.0
- Katip
- Katip.Core
- Katip.Format
- Katip.Monadic
- Katip.Scribes
Katip
Katip is a structured logging framework for Haskell.
Kâtip (pronounced kah-tip) is the Turkish word for scribe.
Features
-
Structured: Logs are structured, meaning they can be individually tagged with key value data (JSON Objects). This helps you add critical details to log messages before you need them so that when you do, they are available. Katip exposes a typeclass for log payloads so that you can use rich, domain-specific Haskell types to add context that will be automatically merged in with existing log context.
-
Easy to Integration: Katip was designed to be easily integrated into existing monads. By using typeclasses for logging facilities, individual subsystems and even libraries can easily add their own namespacing and context without having any knowledge of their logging environment.
-
Practical Use: Katip comes with a set of convenience facilities built-in, so it can be used without much headache even in small projects.
-
A
Handle
backend for logging to files in simple settings. -
A
AnyLogPayload
key-value type that makes it easy to log structured columns on the fly without having to define new data types. -
A
Monadic
interface where logging namespace can be obtained from the monad context. -
Multiple variants of the fundamental logging functions for optionally including fields and line-number information.
-
-
Extensible: Can be easily extended (even at runtime) to output to multiple backends at once (known as scribes). See
katip-elasticsearch
as an example. Backends for other forms of storage are trivial to write, including both hosted database systems and SaaS logging providers. -
Debug-Friendly: Critical details for monitoring production systems such as host, PID, thread id, module and line location are automatically captured. User-specified attributes such as environment (e.g. Production, Test, Dev) and system name are also captured.
-
Configurable: Can be adjusted on a per-scribe basis both with verbosity and severity.
-
Verbosity dictates how much of the log structure should actually get logged. In code you can capture highly detailed metadata and decide how much of that gets emitted to each backend.
-
Severity AKA “log level” is specified with each message and individual scribes can decide whether or not to record that severity. It is even possible to at runtime swap out and replace loggers, allowing for swapping in verbose debug logging at runtime if you want.
-
-
Battle-Tested: Katip has been integrated into several production systems since 2015 and has logged hundreds of millions of messages to files and ElasticSearch.
Examples
Be sure to look in the examples directory for some examples of how to integrate Katip into your own stack.
Contributors
- Ozgun Ataman
- Michael Xavier
- Doug Beardsley
- Leonid Onokhov
- Alexander Vershilov
- Chris Martin
- Domen Kožar
- Tristan Bull
- Aleksey Khudyakov
Changes
0.8.3.0
- Add
logKatipItem
function and reimplementlogItem
to use it. vlatkoB
0.8.2.0
- Add
MonadFail
instances forbase
>= 4.9.0.0 Koray Al
0.8.1.0
- Export
logLoc
. Credit to Brian McKenna
0.8.0.0
- Breaking change: switch from severity based log level filtering to
user-definable
PermitFunc
. To upgrade, any time you initialize one of the standard scribes, rather than providing a severity likeInfoS
, instead pass in(permitItem InfoS)
. Credit to vlatkoB. - Update some misformatted and outdated docs.
- Set lower bound of base to 4.9.0.0, the version shipped with GHC 8.0.2. Support for GHC versions older than that is removed.
- Update default formatter of Handle scribe to format pid as
[PID 1234]
instead of[1234]
and[ThreadId 1234]
instead of[1234]
. - Add missing
Bounded
instance forVerbosity
. This allows you to easily enumerate all verbosities via[minBound..maxBound]
.
0.7.0.0
- Exclusively use HasCallstack for location reporting in errors. Credit to Domen Kožar
- Drop support for GHC 7.x
0.6.3.0
- Add
ToJSON
/FromJSON
instances for Verbosity. Credit to Aleksey Khudyakov.
0.6.2.1
- Add
mkHandleScribeWithFormatter
. This allows control over the format of log items going to a handle. Credit to Tristan Bull for the implementation. - Documentation fixes. Credit to Domen Kožar for the implementation.
- Add
jsonFormat
handle formatter. - Deprecate
formatItem
which is now replaced bybracketFormat
.
0.6.1.0
- Loosen deps
- Support latest STM
0.6.0.0
- Drop ListT instance due to deprecations.
- Loosen dependencies.
0.5.5.1
- Decrease default timer resolution from 1s to 1ms.
0.5.5.0
- Export
runNoLoggingT
andNoLoggingT
constructor. - Delegate MonadReader instance for
NoLoggingT
.
0.5.4.0
- Loosen bounds on resourcet and template-haskell.
- Add convenience function askLoggerIO.
0.5.3.0
- Add MonadUnliftIO instances.
- Add NoLoggingT
0.5.2.0
- Allow newer versions of either by conditionally adding instances for the removed EitherT interface.
0.5.1.0
- Add mkFileScribe, a specialization of mkHandleScribe for files that manages the handle automatically.
0.5.0.4
- Loosen Win32 upper bound to run with GHC 8.2 on Windows.
0.5.0.3
- Add worked example of Katip/KatipContext to the haddocks.
0.5.0.2
- Export Katip.Compat for Windows users.
0.5.0.1
- Fix numeric formatting in Handle scribe.
- Bump deps for GHC 8.2.1
0.5.0.0
- Improved documentation.
- Add built-in buffering to scribes. Scribes now allocate a bounded queue (with configurable size). Rather than writes being synchronous to all scribes, they simply attempt to write into the bounded queue of each scribe. If any of the scribes is too far behind and the queue is full, the write is dropped. This also means that closing scribes is now an IO operation that happens synchrounsly.
- Added local-like functions to Katip and KatipContext typeclasses. This allows us to generalize
katipNoLogging
,katipAddNamespace
, andkatipAddContext
to be available to anything with aKatip
orKatipContext
instance rather than having to reimplement these functions all the time.
0.4.1.0
- Add Katip instances for Strict StateT, WriterT, RWST.
- Add Katip instances for Lazy RWST.
0.4.0.0
- Drop unsafe _ioLogEnv for safe ioLogEnv
0.3.1.5
- Add Semigroup instance for LogStr.
0.3.1.4
- Loosen deps on aeson to allow 1.1.0.0
0.3.1.3
- Fix build on windows
0.3.1.2
- Add some missing test files
0.3.1.1
- Fix some example code that wasn’t building
- Make FromJSON instance for Severity case insensitive.
0.3.1.0
- Add support for aeson 1.0.x
- Add Katip.Format.Time module and use much more efficient time formatting code in the Handle scribe.
0.3.0.0
- Switch from
regex-tdfa-rc
toregex-tdfa
. - Add
katipNoLogging
combinator. - Add
Semigroup
instances. - Drop
ToJSON
superclass requirement froToObject
. Instead,ToObject
will provide a default instance for types with an instance forToJSON
. This gets us to the same place as before without having to add a broader instance for something that’s only going to show up in logs as an Object. - Add a simple MVar lock for file handle scribes to avoid interleaved log lines from concurrent inputs.
0.2.0.0
- Add GHC implicit callstack support, add logLoc.
- Drop lens in favor of type-compatible, lighter microlens.
- Renamed
logEnvNs
to clearerlogEnvApp
- Added
katipAddNamespace
andkatipAddContext
- Fixed nested objects not rendering in Handle scribe.
- LogContexts Monoid instance is now right-biased rather than left
biased. This better fits the use case. For instance
ctx1 <> ctx2
will prefer keys inctx2
if there are conflicts. This makes the most sense because functions likekatipAddContext
willmappend
on the right side. - LogContext internally uses a
Seq
instead of a list for better complexity on context add. - Improved documentation.
0.1.1.0
- Set upper bounds for a few dependencies.
- Add ExceptT instance for Katip typeclass
0.1.0.0
- Initial release