Monitor.Tracing

Non-intrusive distributed tracing

Let's assume for example we are interested in tracing the two following functions and publishing their traces to Zipkin:

listTaskIDs :: MonadIO m => m [Int] -- Returns a list of all task IDs.
fetchTasks :: MonadIO m => [Int] -> m [Task] -- Resolves IDs into tasks.

We can do so simply by wrapping them inside a localSpan call and adding a MonadTrace constraint:

listTaskIDs' :: (MonadIO m, MonadTrace m) => m [Int]
listTaskIDs' = localSpan "list-task-ids" listTaskIDs

fetchTasks' :: (MonadIO m, MonadTrace m) => [Int] -> m [Task]
fetchTasks' = localSpan "fetch-tasks" . fetchTasks

Spans will now automatically get generated and published each time these actions are run! Each publication will include various useful pieces of metadata, including lineage. For example, if we wrap the two above functions in a root span, the spans will correctly be nested:

main :: IO ()
main = do
  zipkin <- new defaultSettings
  tasks <- run zipkin $ rootSpan "list-tasks" (listTaskIDs' >>= fetchTasks')
  publish zipkin
  print tasks

For clarity the above example imported all functions unqualified. In general, the recommended pattern when using this library is to import this module unqualified and the backend-specific module qualified. For example:

import Monitor.Tracing
import qualified Monitor.Tracing.Zipkin as ZPK

Overview

class Monad m => MonadTrace m

A monad capable of generating traces.

There are currently two instances of this monad:

• TraceT, which emits spans for each trace in IO and is meant to be used in production.
• Identity, where tracing is a no-op and allows testing traced functions without any overhead or complex setup.

Minimal complete definition

trace

Instances

MonadTrace Identity

Defined in Control.Monad.Trace.Class

Methods

trace :: Builder -> Identity a -> Identity a

activeSpan :: Identity (Maybe Span)

addSpanEntry :: Key -> Value -> Identity ()

MonadUnliftIO m => MonadTrace (TraceT m)

Defined in Control.Monad.Trace

Methods

trace :: Builder -> TraceT m a -> TraceT m a

activeSpan :: TraceT m (Maybe Span)

addSpanEntry :: Key -> Value -> TraceT m ()

(Monad m, MonadTrace m) => MonadTrace (ExceptT e m)

Defined in Control.Monad.Trace.Class

Methods

trace :: Builder -> ExceptT e m a -> ExceptT e m a

activeSpan :: ExceptT e m (Maybe Span)

addSpanEntry :: Key -> Value -> ExceptT e m ()

(Monad m, MonadTrace m) => MonadTrace (StateT s m)

Defined in Control.Monad.Trace.Class

Methods

trace :: Builder -> StateT s m a -> StateT s m a

activeSpan :: StateT s m (Maybe Span)

addSpanEntry :: Key -> Value -> StateT s m ()

(Monad m, MonadTrace m) => MonadTrace (StateT s m)

Defined in Control.Monad.Trace.Class

Methods

trace :: Builder -> StateT s m a -> StateT s m a

activeSpan :: StateT s m (Maybe Span)

addSpanEntry :: Key -> Value -> StateT s m ()

(Monad m, MonadTrace m, Monoid w) => MonadTrace (WriterT w m)

Defined in Control.Monad.Trace.Class

Methods

trace :: Builder -> WriterT w m a -> WriterT w m a

activeSpan :: WriterT w m (Maybe Span)

addSpanEntry :: Key -> Value -> WriterT w m ()

(Monad m, MonadTrace m, Monoid w) => MonadTrace (WriterT w m)

Defined in Control.Monad.Trace.Class

Methods

trace :: Builder -> WriterT w m a -> WriterT w m a

activeSpan :: WriterT w m (Maybe Span)

addSpanEntry :: Key -> Value -> WriterT w m ()

(Monad m, MonadTrace m) => MonadTrace (ReaderT r m)

Defined in Control.Monad.Trace.Class

Methods

trace :: Builder -> ReaderT r m a -> ReaderT r m a

activeSpan :: ReaderT r m (Maybe Span)

addSpanEntry :: Key -> Value -> ReaderT r m ()

(Monad m, MonadTrace m, Monoid w) => MonadTrace (RWST r w s m)

Defined in Control.Monad.Trace.Class

Methods

trace :: Builder -> RWST r w s m a -> RWST r w s m a

activeSpan :: RWST r w s m (Maybe Span)

addSpanEntry :: Key -> Value -> RWST r w s m ()

(Monad m, MonadTrace m, Monoid w) => MonadTrace (RWST r w s m)

Defined in Control.Monad.Trace.Class

Methods

trace :: Builder -> RWST r w s m a -> RWST r w s m a

activeSpan :: RWST r w s m (Maybe Span)

addSpanEntry :: Key -> Value -> RWST r w s m ()