Safe Haskell	None
Language	Haskell2010

Control.Monad.Trace

Contents

Tracers
Collected data
- Completed spans
- Pending spans

Description

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

Synopsis

data Tracer
newTracer :: MonadIO m => m Tracer
runTraceT :: TraceT m a -> Tracer -> m a
runTraceT' :: TraceT m a -> Maybe Tracer -> m a
newtype TraceT m a = TraceT {
- traceTReader :: ReaderT (Maybe Scope) m a
}
spanSamples :: Tracer -> TChan Sample
data Sample = Sample {
- sampleSpan :: !Span
- sampleTags :: !Tags
- sampleLogs :: !Logs
- sampleStart :: !POSIXTime
- sampleDuration :: !NominalDiffTime
}
type Tags = Map Key Value
type Logs = [(POSIXTime, Key, Value)]
pendingSpanCount :: Tracer -> TVar Int

Tracers

data Tracer Source #

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 Source #

Creates a new Tracer.

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

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 Source #

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

newtype TraceT m a Source #

A span generation monad.

Constructors

TraceT
Fields traceTReader :: ReaderT (Maybe Scope) m a

Instances

Instances details

MonadTrans TraceT Source #
Instance details Defined in Control.Monad.Trace Methods lift :: Monad m => m a -> TraceT m a #
MonadBase b m => MonadBase b (TraceT m) Source #
Instance details Defined in Control.Monad.Trace Methods liftBase :: b α -> TraceT m α #
MonadBaseControl b m => MonadBaseControl b (TraceT m) Source #
Instance details 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) Source #
Instance details 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) Source #
Instance details 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) Source #
Instance details 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) Source #
Instance details 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) Source #
Instance details 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) Source #
Instance details 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) Source #
Instance details 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) Source #
Instance details Defined in Control.Monad.Trace Methods liftIO :: IO a -> TraceT m a #
(MonadIO m, MonadBaseControl IO m) => MonadTrace (TraceT m) Source #
Instance details Defined in Control.Monad.Trace Methods trace :: Builder -> TraceT m a -> TraceT m a Source # activeSpan :: TraceT m (Maybe Span) Source # addSpanEntry :: Key -> Value -> TraceT m () Source #
type StM (TraceT m) a Source #
Instance details 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 Source #

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

data Sample Source #

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 Source #

A collection of span tags.

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

A collection of span logs.

Pending spans

pendingSpanCount :: Tracer -> TVar Int Source #

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