-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Distributed tracing
--   
--   An OpenTracing-compliant, simple, and extensible distributed tracing
--   library.
@package tracing
@version 0.0.3.0


-- | This module exposes the generic <a>MonadTrace</a> class.
module Control.Monad.Trace.Class

-- | A part of a trace.
data Span
Span :: !Name -> !Context -> !Set Reference -> !SamplingDecision -> Span
[spanName] :: Span -> !Name
[spanContext] :: Span -> !Context
[spanReferences] :: Span -> !Set Reference
[spanSamplingDecision] :: Span -> !SamplingDecision

-- | Returns whether the span is sampled.
spanIsSampled :: Span -> Bool

-- | Returns whether the span has debug enabled.
spanIsDebug :: Span -> Bool

-- | A fully qualified span identifier, containing both the ID of the trace
--   the span belongs to and the span's ID.
data Context
Context :: !TraceID -> !SpanID -> !Map Key ByteString -> Context
[contextTraceID] :: Context -> !TraceID
[contextSpanID] :: Context -> !SpanID
[contextBaggages] :: Context -> !Map Key ByteString

-- | A 128-bit trace identifier.
newtype TraceID
TraceID :: ByteString -> TraceID

-- | Decodes a traced ID from a hex-encoded string.
decodeTraceID :: Text -> Maybe TraceID

-- | Hex-encodes a trace ID.
encodeTraceID :: TraceID -> Text

-- | A 64-bit span identifier.
newtype SpanID
SpanID :: ByteString -> SpanID

-- | Decodes a span ID from a hex-encoded string.
decodeSpanID :: Text -> Maybe SpanID

-- | Hex-encodes a span ID.
encodeSpanID :: SpanID -> Text

-- | 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:
--   <a>https://github.com/opentracing/specification/blob/master/specification.md</a>.
data Reference

-- | <a>ChildOf</a> 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.
ChildOf :: !SpanID -> Reference

-- | If the parent does not depend on the child, we use a
--   <a>FollowsFrom</a> reference.
FollowsFrom :: !Context -> Reference

-- | A monad capable of generating and modifying trace spans.
--   
--   There are currently two instances of this monad:
--   
--   <ul>
--   <li><a>TraceT</a>, which emits spans for each trace in <a>IO</a> and
--   is meant to be used in production.</li>
--   <li><a>Identity</a>, where tracing is a no-op and allows testing
--   traced functions without any overhead or complex setup.</li>
--   </ul>
class Monad m => MonadTrace m

-- | Trace an action, wrapping it inside a new span.
trace :: MonadTrace m => Builder -> m a -> m a

-- | Extracts the currently active span, or <a>Nothing</a> if the action is
--   not being traced.
activeSpan :: MonadTrace m => m (Maybe Span)

-- | Extracts the currently active span, or <a>Nothing</a> if the action is
--   not being traced.
activeSpan :: (MonadTrace m, MonadTrace n, MonadTrans t, m ~ t n) => m (Maybe Span)

-- | Adds information to the active span, if present.
addSpanEntry :: MonadTrace m => Key -> Value -> m ()

-- | Adds information to the active span, if present.
addSpanEntry :: (MonadTrace m, MonadTrace n, MonadTrans t, m ~ t n) => Key -> Value -> m ()

-- | A span builder.
--   
--   <a>Builder</a> has an <a>IsString</a> instance, producing a span with
--   the given string as name, no additional references, tags, or baggages.
--   This allows convenient creation of spans via the
--   <tt>OverloadedStrings</tt> pragma.
data Builder
Builder :: !Name -> !Maybe TraceID -> !Maybe SpanID -> !Set Reference -> !Map Key Value -> !Map Key ByteString -> !Maybe SamplingPolicy -> Builder

-- | Name of the generated span.
[builderName] :: Builder -> !Name

-- | 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.
[builderTraceID] :: Builder -> !Maybe TraceID

-- | The ID of the generated span, otherwise the ID will be auto-generated.
[builderSpanID] :: Builder -> !Maybe SpanID

-- | Span references.
[builderReferences] :: Builder -> !Set Reference

-- | Initial set of tags.
[builderTags] :: Builder -> !Map Key Value

-- | Span context baggages.
[builderBaggages] :: Builder -> !Map Key ByteString

-- | 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.
[builderSamplingPolicy] :: Builder -> !Maybe SamplingPolicy

-- | The name of a span.
type Name = Text

-- | Returns a <a>Builder</a> with the given input as name and all other
--   fields empty.
builder :: Name -> Builder

-- | 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 <tt>sampledWithProbability 0.01</tt>.
rootSpan :: MonadTrace m => 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.
rootSpanWith :: MonadTrace m => (Builder -> Builder) -> SamplingPolicy -> 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, <a>childSpan</a> is a no-op.
childSpan :: MonadTrace m => Name -> m a -> m a

-- | Extends a trace, same as <a>childSpan</a> but also customizing the
--   builder.
childSpanWith :: MonadTrace m => (Builder -> Builder) -> Name -> m a -> m a

-- | A span's sampling decision.
data SamplingDecision
Always :: SamplingDecision
Never :: SamplingDecision
Debug :: SamplingDecision

-- | An action to determine how a span should be sampled.
type SamplingPolicy = IO SamplingDecision

-- | Returns a <a>SamplingPolicy</a> which always samples.
alwaysSampled :: SamplingPolicy

-- | Returns a <a>SamplingPolicy</a> which never samples.
neverSampled :: SamplingPolicy

-- | Returns a <a>SamplingPolicy</a> which randomly samples spans.
sampledWithProbability :: Double -> SamplingPolicy

-- | Returns a <a>SamplingPolicy</a> which samples a span iff the input is
--   <a>True</a>. It is equivalent to:
--   
--   <pre>
--   sampledWhen b = if b then alwaysSampled else neverSampled
--   </pre>
sampledWhen :: Bool -> SamplingPolicy

-- | Returns a debug <a>SamplingPolicy</a>. Debug spans are always sampled.
debugEnabled :: SamplingPolicy

-- | The type of annotations' keys.
--   
--   Keys starting with double underscores are reserved and should not be
--   used.
type Key = Text

-- | Metadata attached to a span.
data Value

-- | Generates a tag value from a double.
tagDoubleValue :: Double -> Value

-- | Generates a 64-bit integer tag value from any integer.
tagInt64Value :: Integral a => a -> Value

-- | Generates a Unicode text tag value.
tagTextValue :: Text -> 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 <a>logValueAt</a>.
logValue :: ToJSON a => a -> Value

-- | Generates a log value with a custom time.
logValueAt :: ToJSON a => POSIXTime -> a -> Value
instance (GHC.Base.Monad m, Control.Monad.Trace.Class.MonadTrace m) => Control.Monad.Trace.Class.MonadTrace (Control.Monad.Trans.Except.ExceptT e m)
instance (GHC.Base.Monad m, Control.Monad.Trace.Class.MonadTrace m) => Control.Monad.Trace.Class.MonadTrace (Control.Monad.Trans.Reader.ReaderT r m)
instance (GHC.Base.Monad m, Control.Monad.Trace.Class.MonadTrace m, GHC.Base.Monoid w) => Control.Monad.Trace.Class.MonadTrace (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance (GHC.Base.Monad m, Control.Monad.Trace.Class.MonadTrace m, GHC.Base.Monoid w) => Control.Monad.Trace.Class.MonadTrace (Control.Monad.Trans.RWS.Strict.RWST r w s m)
instance (GHC.Base.Monad m, Control.Monad.Trace.Class.MonadTrace m) => Control.Monad.Trace.Class.MonadTrace (Control.Monad.Trans.State.Lazy.StateT s m)
instance (GHC.Base.Monad m, Control.Monad.Trace.Class.MonadTrace m) => Control.Monad.Trace.Class.MonadTrace (Control.Monad.Trans.State.Strict.StateT s m)
instance (GHC.Base.Monad m, Control.Monad.Trace.Class.MonadTrace m, GHC.Base.Monoid w) => Control.Monad.Trace.Class.MonadTrace (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance (GHC.Base.Monad m, Control.Monad.Trace.Class.MonadTrace m, GHC.Base.Monoid w) => Control.Monad.Trace.Class.MonadTrace (Control.Monad.Trans.Writer.Strict.WriterT w m)
instance Control.Monad.Trace.Class.MonadTrace Data.Functor.Identity.Identity
instance Data.String.IsString Control.Monad.Trace.Class.Builder


-- | This module is useful mostly for tracing backend implementors. If you
--   are only interested in adding tracing to an application, start at
--   <a>Monitor.Tracing</a>.
module Control.Monad.Trace

-- | A tracer is a producer of spans.
--   
--   More specifically, a tracer:
--   
--   <ul>
--   <li>runs <a>MonadTrace</a> actions via <a>runTraceT</a>,</li>
--   <li>transparently collects their generated spans,</li>
--   <li>and outputs them to a channel (available via
--   <a>spanSamples</a>).</li>
--   </ul>
--   
--   These samples can then be consumed independently, decoupling
--   downstream span processing from their production.
data Tracer

-- | Creates a new <a>Tracer</a>.
newTracer :: MonadIO m => m Tracer

-- | 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. <a>run</a> for Zipkin). To
--   ease debugging in certain cases, <a>collectSpanSamples</a> is also
--   available.
runTraceT :: TraceT m a -> Tracer -> m a

-- | A span generation monad.
data TraceT m a

-- | Returns all newly completed spans' samples. The samples become
--   available in the same order they are completed.
spanSamples :: Tracer -> TChan Sample

-- | A sampled span, and its associated metadata.
data Sample
Sample :: !Span -> !Tags -> !Logs -> !POSIXTime -> !NominalDiffTime -> Sample

-- | The sampled span.
[sampleSpan] :: Sample -> !Span

-- | Tags collected during this span.
[sampleTags] :: Sample -> !Tags

-- | Logs collected during this span, sorted in chronological order.
[sampleLogs] :: Sample -> !Logs

-- | The time the span started at.
[sampleStart] :: Sample -> !POSIXTime

-- | The span's duration.
[sampleDuration] :: Sample -> !NominalDiffTime

-- | A collection of span tags.
type Tags = Map Key Value

-- | A collection of span logs.
type Logs = [(POSIXTime, Key, Value)]

-- | Returns the number of spans currently in flight (started but not yet
--   completed).
pendingSpanCount :: Tracer -> TVar Int
instance Control.Monad.Trans.Class.MonadTrans Control.Monad.Trace.TraceT
instance Control.Monad.IO.Class.MonadIO m => Control.Monad.IO.Class.MonadIO (Control.Monad.Trace.TraceT m)
instance GHC.Base.Monad m => GHC.Base.Monad (Control.Monad.Trace.TraceT m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Control.Monad.Trace.TraceT m)
instance GHC.Base.Functor m => GHC.Base.Functor (Control.Monad.Trace.TraceT m)
instance Control.Monad.Reader.Class.MonadReader r m => Control.Monad.Reader.Class.MonadReader r (Control.Monad.Trace.TraceT m)
instance Control.Monad.IO.Unlift.MonadUnliftIO m => Control.Monad.Trace.Class.MonadTrace (Control.Monad.Trace.TraceT m)
instance Control.Monad.IO.Unlift.MonadUnliftIO m => Control.Monad.IO.Unlift.MonadUnliftIO (Control.Monad.Trace.TraceT m)


-- | This module provides convenience functionality to debug traces
--   locally. For production use, prefer alternatives, e.g.
--   <a>Monitor.Tracing.Zipkin</a>.
module Monitor.Tracing.Local

-- | Runs a <a>TraceT</a> action, returning any collected samples alongside
--   its output. The samples are sorted chronologically by completion time
--   (e.g. the head is the first span to complete).
--   
--   Spans which start before the action returns are guaranteed to be
--   collected, even if they complete after (in this case collection will
--   block until their completion). More precisely, <tt>collectSamples</tt>
--   will return the first time there are no pending spans after the action
--   is done.
collectSpanSamples :: MonadUnliftIO m => TraceT m a -> m (a, [Sample])


-- | This module implements a <a>Zipkin</a>-powered trace publisher. You
--   will almost certainly want to import it qualified.
module Monitor.Tracing.Zipkin

-- | <a>Zipkin</a> creation settings.
data Settings
Settings :: !Maybe HostName -> !Maybe PortNumber -> !Maybe Endpoint -> !Maybe Manager -> !Maybe NominalDiffTime -> Settings

-- | The Zipkin server's hostname, defaults to <tt>localhost</tt> if unset.
[settingsHostname] :: Settings -> !Maybe HostName

-- | The port the Zipkin server is listening on, defaults to <tt>9411</tt>
--   if unset.
[settingsPort] :: Settings -> !Maybe PortNumber

-- | Local endpoint included in all published spans.
[settingsEndpoint] :: Settings -> !Maybe Endpoint

-- | An optional HTTP manager to use for publishing spans on the Zipkin
--   server.
[settingsManager] :: Settings -> !Maybe Manager

-- | If set to a positive value, traces will be flushed in the background
--   every such period.
[settingsPublishPeriod] :: Settings -> !Maybe NominalDiffTime

-- | Creates empty <a>Settings</a>. You will typically use this (or the
--   <a>IsString</a> instance) as starting point to only fill in the fields
--   you care about:
--   
--   <pre>
--   let settings = defaultSettings { settingsPort = Just 2222 }
--   </pre>
defaultSettings :: Settings

-- | Information about a hosted service, included in spans and visible in
--   the Zipkin UI.
data Endpoint
Endpoint :: !Maybe Text -> !Maybe Int -> !Maybe IPv4 -> !Maybe IPv6 -> Endpoint

-- | The endpoint's service name.
[endpointService] :: Endpoint -> !Maybe Text

-- | The endpoint's port, if applicable and known.
[endpointPort] :: Endpoint -> !Maybe Int

-- | The endpoint's IPv4 address.
[endpointIPv4] :: Endpoint -> !Maybe IPv4

-- | The endpoint's IPv6 address.
[endpointIPv6] :: Endpoint -> !Maybe IPv6

-- | An empty endpoint.
defaultEndpoint :: Endpoint

-- | A Zipkin trace publisher.
--   
--   All publisher functionality is thread-safe. In particular it is safe
--   to <a>publish</a> concurrently with <a>run</a>, and/or <a>run</a>
--   multiple actions concurrently. Note also that all sampled spans are
--   retained in memory until they are published.
data Zipkin

-- | Creates a <a>Zipkin</a> publisher for the input <a>Settings</a>.
new :: MonadIO m => Settings -> m Zipkin

-- | Runs a <a>TraceT</a> action, sampling spans appropriately. Note that
--   this method does not publish spans on its own; to do so, either call
--   <a>publish</a> manually or specify a positive
--   <a>settingsPublishPeriod</a> to publish in the background.
run :: TraceT m a -> Zipkin -> m a

-- | Flushes all complete spans to the Zipkin server.
publish :: MonadIO m => Zipkin -> m ()

-- | Convenience method to start a <a>Zipkin</a>, run an action, and
--   publish all spans before returning.
with :: MonadUnliftIO m => Settings -> (Zipkin -> m a) -> m a

-- | Exportable trace information, used for cross-process traces.
data B3
B3 :: !TraceID -> !SpanID -> !Bool -> !Bool -> !Maybe SpanID -> B3

-- | The span's trace ID.
[b3TraceID] :: B3 -> !TraceID

-- | The span's ID.
[b3SpanID] :: B3 -> !SpanID

-- | Whether the span was sampled.
[b3IsSampled] :: B3 -> !Bool

-- | Whether the span has debug enabled (which implies that the span is
--   sampled).
[b3IsDebug] :: B3 -> !Bool

-- | The span's parent's ID, or <a>Nothing</a> for root spans.
[b3ParentSpanID] :: B3 -> !Maybe SpanID

-- | Serializes the <a>B3</a> to multiple headers, suitable for HTTP
--   requests. All byte-strings are UTF-8 encoded.
b3ToHeaders :: B3 -> Map (CI ByteString) ByteString

-- | Deserializes the <a>B3</a> from multiple headers.
b3FromHeaders :: Map (CI ByteString) ByteString -> Maybe B3

-- | Serializes the <a>B3</a> to a single UTF-8 encoded header value. It
--   will typically be set as <a>b3 header</a>.
b3ToHeaderValue :: B3 -> ByteString

-- | Deserializes a single header value into a <a>B3</a>.
b3FromHeaderValue :: ByteString -> Maybe B3

-- | Generates a child span with <tt>CLIENT</tt> kind. This function also
--   provides the corresponding <a>B3</a> (or <a>Nothing</a> if tracing is
--   inactive) so that it can be forwarded to the server. For example, to
--   emit an HTTP request and forward the trace information in the headers:
--   
--   <pre>
--   clientSpan "api-call" $ \(Just b3) -&gt; $ do
--     res &lt;- httpLbs "http://host/api" { requestHeaders = b3ToHeaders b3 }
--     process res -- Do something with the response.
--   </pre>
clientSpan :: MonadTrace m => Maybe Endpoint -> Name -> (Maybe B3 -> m a) -> m a

-- | Generates a child span with <tt>SERVER</tt> kind. The client's
--   <a>B3</a> should be provided as input, for example parsed using
--   <a>b3FromHeaders</a>.
serverSpan :: MonadTrace m => Maybe Endpoint -> B3 -> m a -> m a

-- | Generates a child span with <tt>PRODUCER</tt> kind. This function also
--   provides the corresponding <a>B3</a> so that it can be forwarded to
--   the consumer.
producerSpan :: MonadTrace m => Maybe Endpoint -> Name -> (Maybe B3 -> m a) -> m a

-- | Generates a child span with <tt>CONSUMER</tt> kind. The producer's
--   <a>B3</a> should be provided as input.
consumerSpan :: MonadTrace m => Maybe Endpoint -> B3 -> m a -> m a

-- | Adds a tag to the active span.
tag :: MonadTrace m => Text -> Text -> m ()

-- | Adds a tag to a builder. This is a convenience method to use with
--   <a>childSpanWith</a>, for example:
--   
--   <pre>
--   childSpanWith (addTag "key" "value") "run" $ action
--   </pre>
--   
--   Note that there is not difference with adding the tag after the span.
--   So the above code is equivalent to:
--   
--   <pre>
--   childSpan "run" $ tag "key" "value" &gt;&gt; action
--   </pre>
addTag :: Text -> Text -> Builder -> Builder

-- | Adds an inherited tag to a builder. Unlike a tag added via
--   <a>addTag</a>, this tag:
--   
--   <ul>
--   <li>will be inherited by all the span's children.</li>
--   <li>can only be added at span construction time.</li>
--   </ul>
--   
--   For example, to add an ID tag to all spans inside a trace:
--   
--   <pre>
--   rootSpanWith (addInheritedTag "id" "abcd-efg") alwaysSampled "run" $ action
--   </pre>
addInheritedTag :: Text -> Text -> Builder -> Builder

-- | Annotates the active span using the current time.
annotate :: MonadTrace m => Text -> m ()

-- | Annotates the active span at the given time.
annotateAt :: MonadTrace m => POSIXTime -> Text -> m ()
instance GHC.Show.Show Monitor.Tracing.Zipkin.Endpoint
instance GHC.Classes.Ord Monitor.Tracing.Zipkin.Endpoint
instance GHC.Classes.Eq Monitor.Tracing.Zipkin.Endpoint
instance GHC.Show.Show Monitor.Tracing.Zipkin.B3
instance GHC.Classes.Ord Monitor.Tracing.Zipkin.B3
instance GHC.Classes.Eq Monitor.Tracing.Zipkin.B3
instance Data.Aeson.Types.ToJSON.ToJSON Monitor.Tracing.Zipkin.ZipkinSpan
instance Data.Aeson.Types.ToJSON.ToJSON Monitor.Tracing.Zipkin.ZipkinAnnotation
instance Data.String.IsString Monitor.Tracing.Zipkin.Settings
instance Data.String.IsString Monitor.Tracing.Zipkin.Endpoint
instance Data.Aeson.Types.ToJSON.ToJSON Monitor.Tracing.Zipkin.Endpoint


-- | This module is where you should start if you are interested in adding
--   tracing to an application. It provides backend-agnostic utilities to
--   generate traces. Trace publication and other backend-specific features
--   are available in the modules below <tt>Monitor.Tracing</tt> (e.g.
--   <a>Monitor.Tracing.Zipkin</a>). The additional functionality exposed
--   under <tt>Control.Monad</tt> in this package is useful if you wish to
--   implement a new tracing backend.
module Monitor.Tracing

-- | A monad capable of generating and modifying trace spans.
--   
--   There are currently two instances of this monad:
--   
--   <ul>
--   <li><a>TraceT</a>, which emits spans for each trace in <a>IO</a> and
--   is meant to be used in production.</li>
--   <li><a>Identity</a>, where tracing is a no-op and allows testing
--   traced functions without any overhead or complex setup.</li>
--   </ul>
class Monad m => MonadTrace m

-- | 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 <tt>sampledWithProbability 0.01</tt>.
rootSpan :: MonadTrace m => SamplingPolicy -> Name -> m a -> m a

-- | Returns a <a>SamplingPolicy</a> which always samples.
alwaysSampled :: SamplingPolicy

-- | Returns a <a>SamplingPolicy</a> which never samples.
neverSampled :: SamplingPolicy

-- | Returns a <a>SamplingPolicy</a> which samples a span iff the input is
--   <a>True</a>. It is equivalent to:
--   
--   <pre>
--   sampledWhen b = if b then alwaysSampled else neverSampled
--   </pre>
sampledWhen :: Bool -> SamplingPolicy

-- | Returns a <a>SamplingPolicy</a> which randomly samples spans.
sampledWithProbability :: Double -> SamplingPolicy

-- | Returns a debug <a>SamplingPolicy</a>. Debug spans are always sampled.
debugEnabled :: SamplingPolicy

-- | 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, <a>childSpan</a> is a no-op.
childSpan :: MonadTrace m => Name -> m a -> m a

-- | A Zipkin trace publisher.
--   
--   All publisher functionality is thread-safe. In particular it is safe
--   to <a>publish</a> concurrently with <a>run</a>, and/or <a>run</a>
--   multiple actions concurrently. Note also that all sampled spans are
--   retained in memory until they are published.
data Zipkin