A polymorphic, type-safe, json-structured tracing library.
This library provides a way of structured tracing, which are useful for logging call graphs.
json-tracer
Type-safe polymorphic json-structured tracing library
This library provides two modules
Data.PolyDict: type-safe, polymorphic, and json-structured dictionaryControl.Monad.CTrace: a monad that enables contextual tracing
PolyDict
PolyDict is a hash dict like JSON, but it is typed. Dict n is a dictinary whose fields are typed accoding to Assoc n. That is, each field has type Key k (which is a proxy of type-level symbol k) and Assoc n k is the type of values associated with the key.
Basically, users define a data that represents the namespace of the Dict. For example:
data Main
Then, one can define the type of Dict n by adding rules for type family Assoc n k like this:
type instance Assoc Main "elapsed_time" = NominalDiffTime
type instance Assoc Main "tag" = String
The RHS type of the Assoc n k must satisfy the DictValue v constraint.
type family DictValue v :: Constraint where
DictValue v = (Eq v, Show v, ToJSON v)
As far as the author knows, any ToJSON v value satisfy this constraint.
Note: Dict n is allowed as the RHS type as Dict n satisfies the DictValue constraint. Hence recursive structures can be handled.
Since the definition of type family is open, users don't have to define all rules at the same module. It's totally free to add other fields on demand, as long as there are no conflicting keys. When such confliction occurs, the compiler reports it as an error.
type instance Assoc Main "tag" = Int
-- this would be compile error because the key "tag" is conflicting to the previous definition.
Values in Dict are obtained and updated by lookup and insert function.
lookup :: (KnownSymbol k, DictValue v, Assoc n k ~ v) => Key k -> Dict n -> Maybe v
insert :: (KnownSymbol k, DictValue v, Assoc n k ~ v) => Key k -> v -> Dict n -> Dict n
With the OverloadedLabels extention, user can write #foo as the key for the field "foo".
Examples
ghci> let v = insert #tag "sample" empty
ghci> v
{"tag": "sample"}
ghci> lookup #tag v
Just "sample"
ghci> lookup #elapsed_time v
Nothing
Instead, lenses can be used to access thouse fields with access function.
access :: forall n k v. (KnownSymbol k, DictValue v, Assoc n k ~ v) => Key k -> Lens' (Dict n) (Maybe v)
access' :: forall n k v. (KnownSymbol k, DictValue v, Assoc n k ~ v) => Key k -> v -> Lens' (Dict n) v
Examples
ghci> let v = empty & access #tag ?~ "sample"
ghci> v
{"tag": "sample"}
ghci> v ^. access #tag
Just "sample"
Tracer Monad
TracerT c m a is the type of a monad transformer that enables contextual tracing. update and zoom operations can be performed in this monad transformer.
update is the action to modifies the value of context.
update :: Monad m => (c -> c) -> TracerT c m ()
For example, you can count the number of calls of function f by inserting update succ :: TracerT Int m () for each call of f.
Note: although you can modify the value, you cannot get the current value in this monad. This is intentional, to make it easy to disable tracing.
zoom is the action to change the context of tracing.
zoom :: ASetter' c c' -> TracerT c' m a -> TracerT c m a
Complete Example
{-# LANGUAGE TypeFamilies, DataKinds, OverloadedLabels #-}
import Data.PolyDict
import Control.Monad.CTrace
import Lens.Micro
import Control.Monad
data Main
data Sub
type instance Assoc Main "sub" = Dict Sub
type instance Assoc Sub "count" = Int
subFunc :: Monad m => Int -> TracerT (Dict Sub) m ()
subFunc n = replicateM_ n (update (access' #count 0 %~ succ))
mainFunc :: Monad m => TracerT (Dict Main) m ()
mainFunc = zoom (access' #sub empty) (subFunc 42)
main :: IO ()
main = do
(_,d) <- ioTracerT empty mainFunc
print d
-- > {"sub": {"count": 42}}