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 Zipkin

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 ()

tracedForkIO :: (MonadTrace m, MonadUnliftIO m) => m () -> m ThreadId

Starts a new span inside a new thread, returning the newly created thread's ID.

This convenience method around forkIO and withRunInIO is provided since getting insights into concurrent calls is one of the main benefits of tracing.

Convenience exports

class Monad m => MonadIO (m :: Type -> Type)

Monads in which IO computations may be embedded. Any monad built by applying a sequence of monad transformers to the IO monad will be an instance of this class.

Instances should satisfy the following laws, which state that liftIO is a transformer of monads:

• liftIO . return = return

• liftIO (m >>= f) = liftIO m >>= (liftIO . f)

Minimal complete definition

liftIO

Instances

MonadIO IO

Since: base-4.9.0.0

Defined in Control.Monad.IO.Class

Methods

liftIO :: IO a -> IO a

MonadIO Q

Defined in Language.Haskell.TH.Syntax

Methods

liftIO :: IO a -> Q a

MonadIO m => MonadIO (MaybeT m)

Defined in Control.Monad.Trans.Maybe

Methods

liftIO :: IO a -> MaybeT m a

MonadIO m => MonadIO (ListT m)

Defined in Control.Monad.Trans.List

Methods

liftIO :: IO a -> ListT m a

MonadIO m => MonadIO (TraceT m)

Defined in Control.Monad.Trace

Methods

liftIO :: IO a -> TraceT m a

MonadIO m => MonadIO (ExceptT e m)

Defined in Control.Monad.Trans.Except

Methods

liftIO :: IO a -> ExceptT e m a

MonadIO m => MonadIO (IdentityT m)

Defined in Control.Monad.Trans.Identity

Methods

liftIO :: IO a -> IdentityT m a

(Error e, MonadIO m) => MonadIO (ErrorT e m)

Defined in Control.Monad.Trans.Error

Methods

liftIO :: IO a -> ErrorT e m a

MonadIO m => MonadIO (StateT s m)

Defined in Control.Monad.Trans.State.Lazy

Methods

liftIO :: IO a -> StateT s m a

MonadIO m => MonadIO (StateT s m)

Defined in Control.Monad.Trans.State.Strict

Methods

liftIO :: IO a -> StateT s m a

(Monoid w, MonadIO m) => MonadIO (WriterT w m)

Defined in Control.Monad.Trans.Writer.Lazy

Methods

liftIO :: IO a -> WriterT w m a

(Monoid w, MonadIO m) => MonadIO (WriterT w m)

Defined in Control.Monad.Trans.Writer.Strict

Methods

liftIO :: IO a -> WriterT w m a

MonadIO m => MonadIO (ContT r m)

Defined in Control.Monad.Trans.Cont

Methods

liftIO :: IO a -> ContT r m a

MonadIO m => MonadIO (ReaderT r m)

Defined in Control.Monad.Trans.Reader

Methods

liftIO :: IO a -> ReaderT r m a

(Monoid w, MonadIO m) => MonadIO (RWST r w s m)

Defined in Control.Monad.Trans.RWS.Lazy

Methods

liftIO :: IO a -> RWST r w s m a

(Monoid w, MonadIO m) => MonadIO (RWST r w s m)

Defined in Control.Monad.Trans.RWS.Strict

Methods

liftIO :: IO a -> RWST r w s m a

liftIO :: MonadIO m => IO a -> m a

Lift a computation from the IO monad.

class MonadIO m => MonadUnliftIO (m :: Type -> Type)

Monads which allow their actions to be run in IO.

While MonadIO allows an IO action to be lifted into another monad, this class captures the opposite concept: allowing you to capture the monadic context. Note that, in order to meet the laws given below, the intuition is that a monad must have no monadic state, but may have monadic context. This essentially limits MonadUnliftIO to ReaderT and IdentityT transformers on top of IO.

Laws. For any value u returned by askUnliftIO, it must meet the monad transformer laws as reformulated for MonadUnliftIO:

• unliftIO u . return = return

• unliftIO u (m >>= f) = unliftIO u m >>= unliftIO u . f

The third is a currently nameless law which ensures that the current context is preserved.

• askUnliftIO >>= (u -> liftIO (unliftIO u m)) = m

If you have a name for this, please submit it in a pull request for great glory.

Since: unliftio-core-0.1.0.0

Minimal complete definition

askUnliftIO | withRunInIO

Instances

MonadUnliftIO IO

Defined in Control.Monad.IO.Unlift

Methods

askUnliftIO :: IO (UnliftIO IO)

withRunInIO :: ((forall a. IO a -> IO a) -> IO b) -> IO b

MonadUnliftIO m => MonadUnliftIO (TraceT m)

Defined in Control.Monad.Trace

Methods

askUnliftIO :: TraceT m (UnliftIO (TraceT m))

withRunInIO :: ((forall a. TraceT m a -> IO a) -> IO b) -> TraceT m b

MonadUnliftIO m => MonadUnliftIO (IdentityT m)

Defined in Control.Monad.IO.Unlift

Methods

askUnliftIO :: IdentityT m (UnliftIO (IdentityT m))

withRunInIO :: ((forall a. IdentityT m a -> IO a) -> IO b) -> IdentityT m b

MonadUnliftIO m => MonadUnliftIO (ReaderT r m)

Defined in Control.Monad.IO.Unlift

Methods

askUnliftIO :: ReaderT r m (UnliftIO (ReaderT r m))

withRunInIO :: ((forall a. ReaderT r m a -> IO a) -> IO b) -> ReaderT r m b

withRunInIO :: MonadUnliftIO m => ((forall a. m a -> IO a) -> IO b) -> m b

Convenience function for capturing the monadic context and running an IO action with a runner function. The runner function is used to run a monadic action m in IO.

Since: unliftio-core-0.1.0.0