monad-logger-aeson
JSON logging using monad-logger interface
https://sr.ht/~jship/monad-logger-aeson/
LTS Haskell 22.36: | 0.4.1.3 |
Stackage Nightly 2024-10-05: | 0.4.1.3 |
Latest on Hackage: | 0.4.1.3 |
monad-logger-aeson-0.4.1.3@sha256:0a4c29be94a1a3b18659b6c3958f700a1a33359d8b75748367aef9294ca0b76b,6121
Module documentation for 0.4.1.3
- Control
- Control.Monad
- Control.Monad.Logger
- Control.Monad
monad-logger-aeson
Synopsis
monad-logger-aeson
provides structured JSON logging using monad-logger
’s
interface. Specifically, it is intended to be a (largely) drop-in replacement
for monad-logger
’s Control.Monad.Logger.CallStack
module.
For additional detail on the library, please see the Haddocks, the announcement blog post, and the remainder of this README.
Crash course
Assuming we have the following monad-logger
-based code:
{-# LANGUAGE BlockArguments #-}
{-# LANGUAGE OverloadedStrings #-}
module Main
( main
) where
import Control.Monad.Logger.CallStack
import Data.Text (pack)
doStuff :: (MonadLogger m) => Int -> m ()
doStuff x = do
logDebug $ "Doing stuff: x=" <> pack (show x)
main :: IO ()
main = do
runStdoutLoggingT do
doStuff 42
logInfo "Done"
We would get something like this log output:
[Debug] Doing stuff: x=42 @(main:Main app/readme-example.hs:12:3)
[Info] Done @(main:Main app/readme-example.hs:18:5)
We can change our import from this:
import Control.Monad.Logger.CallStack
To this:
import Control.Monad.Logger.Aeson
In changing the import, we’ll have one compiler error to address:
monad-logger-aeson/app/readme-example.hs:12:35: error:
• Couldn't match expected type ‘Message’
with actual type ‘Data.Text.Internal.Text’
• In the second argument of ‘(<>)’, namely ‘pack (show x)’
In the second argument of ‘($)’, namely
‘"Doing stuff: x=" <> pack (show x)’
In a stmt of a 'do' block:
logDebug $ "Doing stuff: x=" <> pack (show x)
|
12 | logDebug $ "Doing stuff: x=" <> pack (show x)
|
This indicates that we need to provide the logDebug
call a Message
rather
than a Text
value. This compiler error gives us a choice depending upon our
current time constraints: we can either go ahead and convert this Text
value
to a “proper” Message
by moving the metadata it encodes into structured data
(i.e. a [Series]
value, where Series
is an aeson
key and encoded value),
or we can defer doing that for now by tacking on an empty [Series]
value.
We’ll opt for the former here:
logDebug $ "Doing stuff" :# ["x" .= x]
Note that the logInfo
call did not give us a compiler error, as Message
has
an IsString
instance.
Our log output now looks like this (formatted for readability here with jq
):
{
"time": "2022-05-15T20:52:15.5559417Z",
"level": "debug",
"location": {
"package": "main",
"module": "Main",
"file": "app/readme-example.hs",
"line": 11,
"char": 3
},
"message": {
"text": "Doing stuff",
"meta": {
"x": 42
}
}
}
{
"time": "2022-05-15T20:52:15.5560448Z",
"level": "info",
"location": {
"package": "main",
"module": "Main",
"file": "app/readme-example.hs",
"line": 17,
"char": 5
},
"message": {
"text": "Done"
}
}
Voilà! Now our Haskell code is using structured logging. Our logs are fit for parsing, ingestion into our log aggregation/analysis service of choice, etc.
Goals
The following goals have underpinned the development of monad-logger-aeson
:
- Structured logging must be easy to add to existing Haskell codebases
- Structured logging should be performant
We believe we have achieved goal 1 by targeting monad-logger
‘s
MonadLogger
/LoggingT
interface. There are many interesting logging libraries
to choose from in Haskell: monad-logger
, di
, logging-effect
, katip
, and
so on. Both by comparing the reverse dependency list for monad-logger
with
the other logging libraries’ reverse dependency lists, and also consulting our
personal experiences working on Haskell codebases, monad-logger
would seem to
be the most prevalent logging library in the wild. In developing our library as
a (largely) drop-in replacement for monad-logger
, we hope to empower
Haskellers using this popular logging interface to add structured logging to
their programs with minimal fuss.
We believe we have achieved goal 2 by directly representing in-flight Message
values using a fixed aeson
object Encoding
, by never (internally) converting
anything to intermediate Value
s, and by never parsing these in-flight log
messages when assembling the final logged message. Regarding the latter point,
we need to know the origin of an input LogStr
(i.e. is it from
monad-logger-aeson
or not?). If we know an input LogStr
came from
monad-logger-aeson
, then we know the LogStr
is an aeson
object Encoding
of a Message
, and so we can pass this encoding along untouched as a piece of
the final log message’s encoding. If we know an input LogStr
did not come from
monad-logger-aeson
, then we can scoop this LogStr
up into a text-only
Message
, encode that, and pass the encoding along as a piece of the final log
message’s encoding. A straightforward and relatively expensive implementation of
determining a LogStr
‘s origin would involve parsing of in-flight log messages
back into Message
values. Rather than resort to parsing every in-flight
message, we simply check the first 9 characters of the LogStr
for a match with
{"text":"
. Yes, there is the possibility that a monad-logger
user logs out a
LogStr
with this same prefix and that LogStr
makes its way into a
monad-logger-aeson
user’s LoggingT
runner function. This would cause
monad-logger-aeson
to erroneously assume the message’s origin is
monad-logger-aeson
. We feel this possibility is overall unlikely, and have
accepted this as a tradeoff in the design space of the library. While we believe
the principles described previously should provide good performance, please note
that benchmarks do not yet exist for this library. Caveat emptor!
Changes
Change log
0.4.1.3
- Relax upper bound on
time
: 1.14 -> 1.15
0.4.1.2
- Support GHC 9.8 by relaxing upper bound on
text
: 2.1 -> 2.2 (@rickowens)
0.4.1.1
- Relax upper bound on
bytestring
: 0.12.0.0 -> 0.13.0.0
0.4.1.0
- Support
aeson-2.2
0.4.0.4
- Relax upper bound on
fast-logger
: 2.11 -> 2.12
0.4.0.3
- Relax upper bound on
fast-logger
: 3.2.0 -> 3.3.0
0.4.0.2
- Relax upper bound on
time
: 1.13 -> 1.14
0.4.0.1
- Relax upper bound on
hspec
: 2.10 -> 2.11 - Relax upper bound on
time
: 1.12 -> 1.13
0.4.0.0
- Replace
log*N
variants reexported frommonad-logger
with custom variants that acceptMessage
instead ofText
0.3.1.0
- Add
Semigroup
instance forSeriesElem
0.3.0.2
- Backwards compatibility down to GHC 8.4 (@pbrisbin)
0.3.0.1
- Minor Haddock updates
0.3.0.0
- Remove deprecated
(.@)
operator - Message metadata is now of type
[SeriesElem]
instead of[Series]
- Should be backwards-compatible based on library’s recommended usage
0.2.0.2
- Support
text-2.0
0.2.0.1
- Relax dependency lower bounds to support GHC 8.8 (@pbrisbin)
0.2.0.0
- Deprecate
(.@)
in favor of(.=)
fromaeson
- Re-export
(.=)
fromaeson
0.1.0.1
- Relax lower bound on
base
: 4.14.3.0 -> 4.14.0.0
0.1.0.0
- Initial release
0.0.0.0
- Unreleased dev version