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


-- | Distributed tracing
--   
--   <a>https://github.com/mtth/tracing</a>
@package tracing
@version 0.0.2.2


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

-- | A monad capable of generating traces.
--   
--   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 part of a trace.
data Span
Span :: !Name -> !Context -> !Set Reference -> !Bool -> !Bool -> Span
[spanName] :: Span -> !Name
[spanContext] :: Span -> !Context
[spanReferences] :: Span -> !Set Reference
[spanIsSampled] :: Span -> !Bool
[spanIsDebug] :: Span -> !Bool

-- | A fully qualified span identifier, containing both the ID of the trace
--   the span belongs to and the span's ID. Span contexts can be exported
--   (resp. imported) via their <a>toJSON</a> (resp. <a>fromJSON</a>)
--   instance.
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

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

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

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

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

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

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

-- | Starts a new trace.
rootSpan :: MonadTrace m => Sampling -> 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) -> Sampling -> Name -> m a -> m a

-- | Extends a trace if it is active, otherwise do nothing.
childSpan :: MonadTrace m => Name -> m a -> m a

-- | Extends a trace if it is active, otherwise do nothing. The active
--   span's ID will be added as a reference to the new span and it will
--   share the same trace ID (overriding any customization done to the
--   builder).
childSpanWith :: MonadTrace m => (Builder -> Builder) -> Name -> m a -> m a

-- | A trace builder.
--   
--   Note that <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 Sampling -> 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.
[builderSampling] :: Builder -> !Maybe Sampling

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

-- | A trace sampling strategy.
data Sampling

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

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

-- | Returns a <a>Sampling</a> which randomly samples one in every
--   <tt>n</tt> spans.
sampledEvery :: Int -> Sampling

-- | Returns a <a>Sampling</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 -> Sampling

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

-- | 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.Show.Show Control.Monad.Trace.Class.Builder
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 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

-- | Asynchronous trace collection monad.
data TraceT m a

-- | Trace an action.
runTraceT :: TraceT m a -> Tracer -> m a

-- | A tracer collects spans emitted inside <a>TraceT</a>.
data Tracer
Tracer :: TChan (Span, Tags, Logs, Interval) -> TVar Int -> Tracer

-- | Channel spans get written to when they complete.
[tracerChannel] :: Tracer -> TChan (Span, Tags, Logs, Interval)

-- | The number of spans currently in flight (started but not yet
--   completed).
[tracerPendingCount] :: Tracer -> TVar Int

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

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

-- | Timing information about a span.
data Interval
Interval :: !POSIXTime -> !NominalDiffTime -> Interval
[intervalStart] :: Interval -> !POSIXTime
[intervalDuration] :: Interval -> !NominalDiffTime

-- | Creates a new <a>Tracer</a>.
newTracer :: MonadIO m => m Tracer
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 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. Note that its constructor is not
--   exposed to allow backwards compatible evolution; <a>Settings</a>
--   should instead be created either via <a>defaultSettings</a> or its
--   <a>IsString</a> instance.
data Settings

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

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

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

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

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

-- | Information about a hosted service, included in spans and visible in
--   the Zipkin UI.
data Endpoint

-- | An empty endpoint.
defaultEndpoint :: 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

-- | A Zipkin trace publisher.
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. This method is
--   thread-safe.
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

-- | 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
--   <tt>b3FromRequestHeaders</tt>.
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 ()

-- | 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 traces.
--   
--   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

-- | A trace sampling strategy.
data Sampling

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

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

-- | Returns a <a>Sampling</a> which randomly samples one in every
--   <tt>n</tt> spans.
sampledEvery :: Int -> Sampling

-- | Returns a <a>Sampling</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 -> Sampling

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

-- | Starts a new trace.
rootSpan :: MonadTrace m => Sampling -> Name -> m a -> m a

-- | Extends a trace if it is active, otherwise do nothing.
childSpan :: MonadTrace m => Name -> m a -> m a

-- | A Zipkin trace publisher.
data Zipkin