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


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


-- | The <a>TraceT</a> class.
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
[tracerChannel] :: Tracer -> TChan (Span, Tags, Logs, Interval)
[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)


-- | <a>Jaeger</a> trace publisher.
module Monitor.Tracing.Jaeger

-- | Jaeger publisher, not implemented yet.
data Jaeger


-- | <a>Zipkin</a> trace publisher.
module Monitor.Tracing.Zipkin

-- | A Zipkin trace publisher.
data Zipkin

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

-- | Zipkin creating settings.
data Settings
Settings :: !HostName -> !PortNumber -> !Maybe Endpoint -> !Maybe Manager -> !NominalDiffTime -> Settings

-- | The Zipkin server's hostname.
[settingsHostname] :: Settings -> !HostName

-- | The port the Zipkin server is listening on.
[settingsPort] :: Settings -> !PortNumber

-- | Local endpoint used for 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 -> !NominalDiffTime

-- | Creates <a>Settings</a> pointing to a Zikpin server at host
--   <tt>"localhost"</tt> and port <tt>9411</tt>, without background
--   flushing.
defaultSettings :: Settings

-- | Information about a hosted service.
data Endpoint
Endpoint :: !Maybe Text -> !Maybe Int -> !Maybe IPv4 -> !Maybe IPv6 -> Endpoint
[endpointService] :: Endpoint -> !Maybe Text
[endpointPort] :: Endpoint -> !Maybe Int
[endpointIPv4] :: Endpoint -> !Maybe IPv4
[endpointIPv6] :: Endpoint -> !Maybe IPv6

-- | An empty endpoint.
defaultEndpoint :: Endpoint

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

-- | Deserializes the <a>B3</a> from headers.
b3FromHeaders :: Map Text Text -> Maybe B3

-- | Serializes the <a>B3</a> to headers, suitable for HTTP requests.
b3ToHeaders :: B3 -> Map Text Text

-- | Generates a child span with <tt>CLIENT</tt> kind. This function also
--   provides the corresponding <a>B3</a> so that it can be forwarded to
--   the server.
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.
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.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.Aeson.Types.ToJSON.ToJSON Monitor.Tracing.Zipkin.Endpoint
instance Data.Aeson.Types.FromJSON.FromJSON Monitor.Tracing.Zipkin.B3
instance Data.Aeson.Types.ToJSON.ToJSON Monitor.Tracing.Zipkin.B3


-- | Non-intrusive distributed tracing
--   
--   Let's assume for example we are interested in tracing the two
--   following functions:
--   
--   <pre>
--   listTaskIDs' :: MonadIO m =&gt; m [Int] -- Returns a list of all task IDs.
--   fetchTasks' :: MonadIO m =&gt; [Int] -&gt; m [Task] -- Resolves IDs into tasks.
--   </pre>
--   
--   We can do so simply by wrapping them inside a <a>childSpan</a> call
--   and adding a <a>MonadTrace</a> constraint:
--   
--   <pre>
--   import Monitor.Tracing
--   
--   listTaskIDs :: (MonadIO m, MonadTrace m) =&gt; m [Int]
--   listTaskIDs = childSpan "list-task-ids" listTaskIDs'
--   
--   fetchTasks :: (MonadIO m, MonadTrace m) =&gt; [Int] -&gt; m [Task]
--   fetchTasks = childSpan "fetch-tasks" . fetchTasks'
--   </pre>
--   
--   Spans will now automatically get generated any time these actions are
--   run! Each span will be associated with various useful pieces of
--   metadata, including lineage. For example, if we wrap the two above
--   functions in a <a>rootSpan</a>, the spans will correctly be nested:
--   
--   <pre>
--   printTasks :: (MonadIO m, MonadTrace m) =&gt; m ()
--   printTasks = rootSpan alwaysSampled "list-tasks" $ listTaskIDs &gt;&gt;= fetchTasks &gt;&gt;= print
--   </pre>
--   
--   Spans can then be published to various backends. For example, to run
--   the above action and publish its spans using Zipkin:
--   
--   <pre>
--   import qualified Monitor.Tracing.Zipkin as ZPK
--   
--   main :: IO ()
--   main = ZPK.with ZPK.defaultSettings $ ZPK.run printTasks
--   </pre>
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>.
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

-- | 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 Zipkin trace publisher.
data Zipkin