Control.Monad.Trace.Class

This module exposes the generic MonadTrace class.

Types

data Span

A part of a trace.

Constructors

Span

Fields

• spanName :: !Name
• spanContext :: !Context
• spanReferences :: !(Set Reference)
• spanSamplingDecision :: !SamplingDecision

spanIsSampled :: Span -> Bool

Returns whether the span is sampled.

spanIsDebug :: Span -> Bool

Returns whether the span has debug enabled.

data Context

A fully qualified span identifier, containing both the ID of the trace the span belongs to and the span's ID.

Constructors

Context

Fields

• contextTraceID :: !TraceID
• contextSpanID :: !SpanID
• contextBaggages :: !(Map Key ByteString)

Instances

Eq Context

Defined in Control.Monad.Trace.Internal

Methods

(==) :: Context -> Context -> Bool

(/=) :: Context -> Context -> Bool

Ord Context

Defined in Control.Monad.Trace.Internal

Methods

compare :: Context -> Context -> Ordering

(<) :: Context -> Context -> Bool

(<=) :: Context -> Context -> Bool

(>) :: Context -> Context -> Bool

(>=) :: Context -> Context -> Bool

max :: Context -> Context -> Context

min :: Context -> Context -> Context

Show Context

Defined in Control.Monad.Trace.Internal

Methods

showsPrec :: Int -> Context -> ShowS

show :: Context -> String

showList :: [Context] -> ShowS

newtype TraceID

A 128-bit trace identifier.

Constructors

TraceID ByteString

Instances

Eq TraceID

Defined in Control.Monad.Trace.Internal

Methods

(==) :: TraceID -> TraceID -> Bool

(/=) :: TraceID -> TraceID -> Bool

Ord TraceID

Defined in Control.Monad.Trace.Internal

Methods

compare :: TraceID -> TraceID -> Ordering

(<) :: TraceID -> TraceID -> Bool

(<=) :: TraceID -> TraceID -> Bool

(>) :: TraceID -> TraceID -> Bool

(>=) :: TraceID -> TraceID -> Bool

max :: TraceID -> TraceID -> TraceID

min :: TraceID -> TraceID -> TraceID

Show TraceID

Defined in Control.Monad.Trace.Internal

Methods

showsPrec :: Int -> TraceID -> ShowS

show :: TraceID -> String

showList :: [TraceID] -> ShowS

ToJSON TraceID

Defined in Control.Monad.Trace.Internal

Methods

toJSON :: TraceID -> Value

toEncoding :: TraceID -> Encoding

toJSONList :: [TraceID] -> Value

toEncodingList :: [TraceID] -> Encoding

FromJSON TraceID

Defined in Control.Monad.Trace.Internal

Methods

parseJSON :: Value -> Parser TraceID

parseJSONList :: Value -> Parser [TraceID]

decodeTraceID :: Text -> Maybe TraceID

Decodes a traced ID from a hex-encoded string.

encodeTraceID :: TraceID -> Text

Hex-encodes a trace ID.

newtype SpanID

A 64-bit span identifier.

Constructors

SpanID ByteString

Instances

Eq SpanID

Defined in Control.Monad.Trace.Internal

Methods

(==) :: SpanID -> SpanID -> Bool

(/=) :: SpanID -> SpanID -> Bool

Ord SpanID

Defined in Control.Monad.Trace.Internal

Methods

compare :: SpanID -> SpanID -> Ordering

(<) :: SpanID -> SpanID -> Bool

(<=) :: SpanID -> SpanID -> Bool

(>) :: SpanID -> SpanID -> Bool

(>=) :: SpanID -> SpanID -> Bool

max :: SpanID -> SpanID -> SpanID

min :: SpanID -> SpanID -> SpanID

Show SpanID

Defined in Control.Monad.Trace.Internal

Methods

showsPrec :: Int -> SpanID -> ShowS

show :: SpanID -> String

showList :: [SpanID] -> ShowS

ToJSON SpanID

Defined in Control.Monad.Trace.Internal

Methods

toJSON :: SpanID -> Value

toEncoding :: SpanID -> Encoding

toJSONList :: [SpanID] -> Value

toEncodingList :: [SpanID] -> Encoding

FromJSON SpanID

Defined in Control.Monad.Trace.Internal

Methods

parseJSON :: Value -> Parser SpanID

parseJSONList :: Value -> Parser [SpanID]

decodeSpanID :: Text -> Maybe SpanID

Decodes a span ID from a hex-encoded string.

encodeSpanID :: SpanID -> Text

Hex-encodes a span ID.

data Reference

A relationship between spans.

There are currently two types of references, both of which model direct causal relationships between a child and a parent. More background on references is available in the opentracing specification: https://github.com/opentracing/specification/blob/master/specification.md.

Constructors

ChildOf !SpanID

ChildOf references imply that the parent span depends on the child span in some capacity. Note that this reference type is only valid within a single trace.

FollowsFrom !Context

If the parent does not depend on the child, we use a FollowsFrom reference.

Instances

Eq Reference

Defined in Control.Monad.Trace.Internal

Methods

(==) :: Reference -> Reference -> Bool

(/=) :: Reference -> Reference -> Bool

Ord Reference

Defined in Control.Monad.Trace.Internal

Methods

compare :: Reference -> Reference -> Ordering

(<) :: Reference -> Reference -> Bool

(<=) :: Reference -> Reference -> Bool

(>) :: Reference -> Reference -> Bool

(>=) :: Reference -> Reference -> Bool

max :: Reference -> Reference -> Reference

min :: Reference -> Reference -> Reference

Show Reference

Defined in Control.Monad.Trace.Internal

Methods

showsPrec :: Int -> Reference -> ShowS

show :: Reference -> String

showList :: [Reference] -> ShowS

Generating traces

Individual spans

class Monad m => MonadTrace m where

A monad capable of generating and modifying trace spans.

This package currently provides two instances of this class:

• 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

Methods

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

Trace an action, wrapping it inside a new span. If the action isn't currently being traced, trace should be a no-op. Otherwise, the new span should share the active span's trace ID, sampling decision, and baggages unless overridden by the input Builder.

activeSpan :: m (Maybe Span)

Extracts the currently active span, or Nothing if the action is not being traced.

default activeSpan :: (MonadTrace n, MonadTrans t, m ~ t n) => m (Maybe Span)

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

Adds information to the active span, if present.

default addSpanEntry :: (MonadTrace n, MonadTrans t, m ~ t n) => Key -> Value -> m ()

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

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

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

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

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

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

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

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

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

data Builder

A span builder.

Builder has an IsString instance, producing a span with the given string as name, no additional references, tags, or baggages. This allows convenient creation of spans via the OverloadedStrings pragma.

Constructors

Builder

Fields

• builderName :: !Name

  Name of the generated span.

• builderTraceID :: !(Maybe TraceID)

  The trace ID of the generated span. If unset, the active span's trace ID will be used if present, otherwise a new ID will be generated.

• builderSpanID :: !(Maybe SpanID)

  The ID of the generated span, otherwise the ID will be auto-generated.

• builderReferences :: !(Set Reference)

  Span references.

• builderTags :: !(Map Key Value)

  Initial set of tags.

• builderBaggages :: !(Map Key ByteString)

  Span context baggages.

• builderSamplingPolicy :: !(Maybe SamplingPolicy)

  How the span should be sampled. If unset, the active's span sampling will be used if present, otherwise the span will not be sampled.

Instances

IsString Builder

Defined in Control.Monad.Trace.Class

Methods

fromString :: String -> Builder

type Name = Text

The name of a span.

builder :: Name -> Builder

Returns a Builder with the given input as name and all other fields empty.

Structured traces

rootSpan :: MonadTrace m => SamplingPolicy -> Name -> m a -> m a

Starts a new trace. For performance reasons, it is possible to customize how frequently tracing information is collected. This allows fine-grain control on the overhead induced by tracing. For example, you might only want to sample 1% of a very actively used call-path with sampledWithProbability 0.01.

rootSpanWith :: MonadTrace m => (Builder -> Builder) -> SamplingPolicy -> Name -> m a -> m a

Starts a new trace, customizing the span builder. Note that the sampling input will override any sampling customization set on the builder.

childSpan :: MonadTrace m => Name -> m a -> m a

Extends a trace: the active span's ID will be added as a reference to a newly created span and both spans will share the same trace ID. If no span is active, childSpan is a no-op.

childSpanWith :: MonadTrace m => (Builder -> Builder) -> Name -> m a -> m a

Extends a trace, same as childSpan but also customizing the builder.

Sampling

data SamplingDecision

A span's sampling decision.

Constructors

Always

Never

Debug

Instances

Enum SamplingDecision

Defined in Control.Monad.Trace.Internal

Methods

succ :: SamplingDecision -> SamplingDecision

pred :: SamplingDecision -> SamplingDecision

toEnum :: Int -> SamplingDecision

fromEnum :: SamplingDecision -> Int

enumFrom :: SamplingDecision -> [SamplingDecision]

enumFromThen :: SamplingDecision -> SamplingDecision -> [SamplingDecision]

enumFromTo :: SamplingDecision -> SamplingDecision -> [SamplingDecision]

enumFromThenTo :: SamplingDecision -> SamplingDecision -> SamplingDecision -> [SamplingDecision]

Eq SamplingDecision

Defined in Control.Monad.Trace.Internal

Methods

(==) :: SamplingDecision -> SamplingDecision -> Bool

(/=) :: SamplingDecision -> SamplingDecision -> Bool

Ord SamplingDecision

Defined in Control.Monad.Trace.Internal

Methods

compare :: SamplingDecision -> SamplingDecision -> Ordering

(<) :: SamplingDecision -> SamplingDecision -> Bool

(<=) :: SamplingDecision -> SamplingDecision -> Bool

(>) :: SamplingDecision -> SamplingDecision -> Bool

(>=) :: SamplingDecision -> SamplingDecision -> Bool

max :: SamplingDecision -> SamplingDecision -> SamplingDecision

min :: SamplingDecision -> SamplingDecision -> SamplingDecision

Show SamplingDecision

Defined in Control.Monad.Trace.Internal

Methods

showsPrec :: Int -> SamplingDecision -> ShowS

show :: SamplingDecision -> String

showList :: [SamplingDecision] -> ShowS

type SamplingPolicy = IO SamplingDecision

An action to determine how a span should be sampled.

alwaysSampled :: SamplingPolicy

Returns a SamplingPolicy which always samples.

neverSampled :: SamplingPolicy

Returns a SamplingPolicy which never samples.

sampledWithProbability :: Double -> SamplingPolicy

Returns a SamplingPolicy which randomly samples spans.

sampledWhen :: Bool -> SamplingPolicy

Returns a SamplingPolicy which samples a span iff the input is True. It is equivalent to:

sampledWhen b = if b then alwaysSampled else neverSampled

debugEnabled :: SamplingPolicy

Returns a debug SamplingPolicy. Debug spans are always sampled.

Annotating traces

Note that not all annotation types are supported by all backends. For example Zipkin only supports string tags (refer to Monitor.Tracing.Zipkin for the full list of supported span metadata).

type Key = Text

The type of annotations' keys.

Keys starting with double underscores are reserved and should not be used.

data Value

Metadata attached to a span.

tagDoubleValue :: Double -> Value

Generates a tag value from a double.

tagInt64Value :: Integral a => a -> Value

Generates a 64-bit integer tag value from any integer.

tagTextValue :: Text -> Value

Generates a Unicode text tag value.

logValue :: ToJSON a => a -> Value

Generates a log value with the time of writing as timestamp. Note that the value may be written later than it is created. For more control on the timestamp, use logValueAt.

logValueAt :: ToJSON a => POSIXTime -> a -> Value

Generates a log value with a custom time.