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


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

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

-- | A 64-bit span identifier.
data SpanID

-- | A 128-bit trace identifier.
data TraceID

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

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

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

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

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


-- | Non-intrusive distributed tracing
--   
--   Let's assume for example we are interested in tracing the two
--   following functions and publishing their traces to Zipkin:
--   
--   <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>localSpan</a> call
--   and adding a <a>MonadTrace</a> constraint:
--   
--   <pre>
--   listTaskIDs' :: (MonadIO m, MonadTrace m) =&gt; m [Int]
--   listTaskIDs' = localSpan "list-task-ids" listTaskIDs
--   
--   fetchTasks' :: (MonadIO m, MonadTrace m) =&gt; [Int] -&gt; m [Task]
--   fetchTasks' = localSpan "fetch-tasks" . fetchTasks
--   </pre>
--   
--   Spans will now automatically get generated and published each time
--   these actions are run! Each publication will include various useful
--   pieces of metadata, including lineage. For example, if we wrap the two
--   above functions in a root span, the spans will correctly be nested:
--   
--   <pre>
--   main :: IO ()
--   main = do
--     zipkin &lt;- new defaultSettings
--     tasks &lt;- run zipkin $ rootSpan "list-tasks" (listTaskIDs' &gt;&gt;= fetchTasks')
--     publish zipkin
--     print tasks
--   </pre>
--   
--   For clarity the above example imported all functions unqualified. In
--   general, the recommended pattern when using this library is to import
--   this module unqualified and the backend-specific module qualified. For
--   example:
--   
--   <pre>
--   import Monitor.Tracing
--   import qualified Monitor.Tracing.Zipkin as ZPK
--   </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>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 :: Zipkin -> TraceT m a -> 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

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

-- | The sampling applied to a trace.
--   
--   Note that non-sampled traces still yield active spans. However these
--   spans are not published to Zipkin.
data Sampling

-- | Sample it.
Accept :: Sampling

-- | Sample it and mark it as debug.
Debug :: Sampling

-- | Do not sample it.
Deny :: Sampling

-- | Continues an existing trace if present, otherwise does nothing.
localSpan :: MonadTrace m => Name -> m a -> m a

-- | Exportable trace information, used for cross-process traces.
data B3
clientSpan :: MonadTrace m => Maybe Endpoint -> Name -> (Maybe B3 -> m a) -> m a
serverSpan :: MonadTrace m => Maybe Endpoint -> B3 -> m a -> m a
producerSpan :: MonadTrace m => Maybe Endpoint -> Name -> (Maybe B3 -> m a) -> m a
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 GHC.Show.Show Monitor.Tracing.Zipkin.Sampling
instance GHC.Enum.Enum Monitor.Tracing.Zipkin.Sampling
instance GHC.Classes.Ord Monitor.Tracing.Zipkin.Sampling
instance GHC.Classes.Eq Monitor.Tracing.Zipkin.Sampling
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