Control.Monad.Trace

This module is useful mostly for tracing backend implementors. If you are only interested in adding tracing to an application, start at Monitor.Tracing.

Tracers

data Tracer

A tracer is a producer of spans.

More specifically, a tracer:

• runs MonadTrace actions via runTraceT,
• transparently collects their generated spans,
• and outputs them to a channel (available via spanSamples).

These samples can then be consumed independently, decoupling downstream span processing from their production.

newTracer :: MonadIO m => m Tracer

Creates a new Tracer.

runTraceT :: TraceT m a -> Tracer -> m a

Trace an action, sampling its generated spans. This method is thread-safe and can be used to trace multiple actions concurrently.

Unless you are implementing a custom span publication backend, you should not need to call this method explicitly. Instead, prefer to use the backend's functionality directly (e.g. run for Zipkin). To ease debugging in certain cases, collectSpanSamples is also available.

See runTraceT' for a variant which allows discarding spans.

runTraceT' :: TraceT m a -> Maybe Tracer -> m a

Maybe trace an action. If the tracer is Nothing, no spans will be published.

newtype TraceT m a

A span generation monad.

Constructors

TraceT

Fields

• traceTReader :: ReaderT (Maybe Scope) m a

Instances

MonadTrans TraceT

Defined in Control.Monad.Trace

Methods

lift :: Monad m => m a -> TraceT m a

MonadBase b m => MonadBase b (TraceT m)

Defined in Control.Monad.Trace

Methods

liftBase :: b α -> TraceT m α

MonadBaseControl b m => MonadBaseControl b (TraceT m)

Defined in Control.Monad.Trace

Associated Types

type StM (TraceT m) a

Methods

liftBaseWith :: (RunInBase (TraceT m) b -> b a) -> TraceT m a

restoreM :: StM (TraceT m) a -> TraceT m a

MonadWriter w m => MonadWriter w (TraceT m)

Defined in Control.Monad.Trace

Methods

writer :: (a, w) -> TraceT m a

tell :: w -> TraceT m ()

listen :: TraceT m a -> TraceT m (a, w)

pass :: TraceT m (a, w -> w) -> TraceT m a

MonadState s m => MonadState s (TraceT m)

Defined in Control.Monad.Trace

Methods

get :: TraceT m s

put :: s -> TraceT m ()

state :: (s -> (a, s)) -> TraceT m a

MonadReader r m => MonadReader r (TraceT m)

Defined in Control.Monad.Trace

Methods

ask :: TraceT m r

local :: (r -> r) -> TraceT m a -> TraceT m a

reader :: (r -> a) -> TraceT m a

MonadError e m => MonadError e (TraceT m)

Defined in Control.Monad.Trace

Methods

throwError :: e -> TraceT m a

catchError :: TraceT m a -> (e -> TraceT m a) -> TraceT m a

Monad m => Monad (TraceT m)

Defined in Control.Monad.Trace

Methods

(>>=) :: TraceT m a -> (a -> TraceT m b) -> TraceT m b

(>>) :: TraceT m a -> TraceT m b -> TraceT m b

return :: a -> TraceT m a

Functor m => Functor (TraceT m)

Defined in Control.Monad.Trace

Methods

fmap :: (a -> b) -> TraceT m a -> TraceT m b

(<$) :: a -> TraceT m b -> TraceT m a

Applicative m => Applicative (TraceT m)

Defined in Control.Monad.Trace

Methods

pure :: a -> TraceT m a

(<*>) :: TraceT m (a -> b) -> TraceT m a -> TraceT m b

liftA2 :: (a -> b -> c) -> TraceT m a -> TraceT m b -> TraceT m c

(*>) :: TraceT m a -> TraceT m b -> TraceT m b

(<*) :: TraceT m a -> TraceT m b -> TraceT m a

MonadIO m => MonadIO (TraceT m)

Defined in Control.Monad.Trace

Methods

liftIO :: IO a -> TraceT m a

(MonadIO m, MonadBaseControl IO 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 ()

type StM (TraceT m) a

Defined in Control.Monad.Trace

type StM (TraceT m) a

Collected data

Tracers currently expose two pieces of data: completed spans and pending span count. Note that only sampled spans are eligible: spans which are neverSampled appear in neither.

Completed spans

spanSamples :: Tracer -> TChan Sample

Returns all newly completed spans' samples. The samples become available in the same order they are completed.

data Sample

A sampled span and its associated metadata.

Constructors

Sample

Fields

• sampleSpan :: !Span

  The sampled span.

• sampleTags :: !Tags

  Tags collected during this span.

• sampleLogs :: !Logs

  Logs collected during this span, sorted in chronological order.

• sampleStart :: !POSIXTime

  The time the span started at.

• sampleDuration :: !NominalDiffTime

  The span's duration.

type Tags = Map Key Value

A collection of span tags.

type Logs = [(POSIXTime, Key, Value)]

A collection of span logs.

Pending spans

pendingSpanCount :: Tracer -> TVar Int

Returns the number of spans currently in flight (started but not yet completed).