mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-20 22:11:45 +03:00
cf531b05cb
This PR is on top of #7789. ### Description This PR entirely rewrites the API of the Tracing library, to make `interpTraceT` a thing of the past. Before this change, we ran traces by sticking a `TraceT` on top of whatever we were doing. This had several major drawbacks: - we were carrying a bunch of `TraceT` across the codebase, and the entire codebase had to know about it - we needed to carry a second class constraint around (`HasReporterM`) to be able to run all of those traces - we kept having to do stack rewriting with `interpTraceT`, which went from inconvenient to horrible - we had to declare several behavioral instances on `TraceT m` This PR rewrite all of `Tracing` using a more conventional model: there is ONE `TraceT` at the bottom of the stack, and there is an associated class constraint `MonadTrace`: any part of the code that happens to satisfy `MonadTrace` is able to create new traces. We NEVER have to do stack rewriting, `interpTraceT` is gone, and `TraceT` and `Reporter` become implementation details that 99% of the code is blissfully unaware of: code that needs to do tracing only needs to declare that the monad in which it operates implements `MonadTrace`. In doing so, this PR revealed **several bugs in the codebase**: places where we were expecting to trace something, but due to the default instance of `HasReporterM IO` we would actually not do anything. This PR also splits the code of `Tracing` in more byte-sized modules, with the goal of potentially moving to `server/lib` down the line. ### Remaining work This PR is a draft; what's left to do is: - [x] make Pro compile; i haven't updated `HasuraPro/Main` yet - [x] document Tracing by writing a note that explains how to use the library, and the meaning of "reporter", "trace" and "span", as well as the pitfalls - [x] discuss some of the trade-offs in the implementation, which is why i'm opening this PR already despite it not fully building yet - [x] it depends on #7789 being merged first PR-URL: https://github.com/hasura/graphql-engine-mono/pull/7791 GitOrigin-RevId: cadd32d039134c93ddbf364599a2f4dd988adea8
92 lines
3.0 KiB
Haskell
92 lines
3.0 KiB
Haskell
-- | Defines the Tracing API.
|
|
--
|
|
-- The 'MonadTrace' class defines the "public API" of this component.
|
|
module Hasura.Tracing.Class
|
|
( MonadTrace (..),
|
|
newTrace,
|
|
newSpan,
|
|
)
|
|
where
|
|
|
|
import Control.Monad.Morph
|
|
import Control.Monad.Trans.Maybe
|
|
import Hasura.Prelude
|
|
import Hasura.Tracing.Context
|
|
import Hasura.Tracing.Sampling
|
|
import Hasura.Tracing.TraceId
|
|
|
|
--------------------------------------------------------------------------------
|
|
-- MonadTrace
|
|
|
|
class Monad m => MonadTrace m where
|
|
-- | Trace the execution of a block of code, attaching a human-readable
|
|
-- name. This starts a new trace and its corresponding root span, to which
|
|
-- subsequent spans will be attached.
|
|
newTraceWith ::
|
|
TraceContext ->
|
|
SamplingPolicy ->
|
|
Text ->
|
|
m a ->
|
|
m a
|
|
|
|
-- | Starts a new span within the current trace. No-op if there's no current
|
|
-- trace.
|
|
--
|
|
-- TODO: we could rewrite this to start a new trace if there isn't one, using
|
|
-- the default reporter and policy? This would guarantee that no span is ever
|
|
-- lost, but would also risk reporting undesired spans.
|
|
newSpanWith ::
|
|
SpanId ->
|
|
Text ->
|
|
m a ->
|
|
m a
|
|
|
|
-- | Ask for the current tracing context, so that we can provide it to any
|
|
-- downstream services, e.g. in HTTP headers. Returns 'Nothing' if we're not
|
|
-- currently tracing anything.
|
|
currentContext :: m (Maybe TraceContext)
|
|
|
|
-- | Log some arbitrary metadata to be attached to the current span, if any.
|
|
attachMetadata :: TraceMetadata -> m ()
|
|
|
|
instance MonadTrace m => MonadTrace (ReaderT r m) where
|
|
newTraceWith c p n = mapReaderT (newTraceWith c p n)
|
|
newSpanWith i n = mapReaderT (newSpanWith i n)
|
|
currentContext = lift currentContext
|
|
attachMetadata = lift . attachMetadata
|
|
|
|
instance MonadTrace m => MonadTrace (StateT e m) where
|
|
newTraceWith c p n = mapStateT (newTraceWith c p n)
|
|
newSpanWith i n = mapStateT (newSpanWith i n)
|
|
currentContext = lift currentContext
|
|
attachMetadata = lift . attachMetadata
|
|
|
|
instance MonadTrace m => MonadTrace (ExceptT e m) where
|
|
newTraceWith c p n = mapExceptT (newTraceWith c p n)
|
|
newSpanWith i n = mapExceptT (newSpanWith i n)
|
|
currentContext = lift currentContext
|
|
attachMetadata = lift . attachMetadata
|
|
|
|
instance MonadTrace m => MonadTrace (MaybeT m) where
|
|
newTraceWith c p n = mapMaybeT (newTraceWith c p n)
|
|
newSpanWith i n = mapMaybeT (newSpanWith i n)
|
|
currentContext = lift currentContext
|
|
attachMetadata = lift . attachMetadata
|
|
|
|
--------------------------------------------------------------------------------
|
|
-- Trace helpers
|
|
|
|
-- | Create a new trace using a randomly-generated context.
|
|
newTrace :: (MonadIO m, MonadTrace m) => SamplingPolicy -> Text -> m a -> m a
|
|
newTrace policy name body = do
|
|
traceId <- randomTraceId
|
|
spanId <- randomSpanId
|
|
let context = TraceContext traceId spanId Nothing SamplingDefer
|
|
newTraceWith context policy name body
|
|
|
|
-- | Create a new span with a randomly-generated id.
|
|
newSpan :: (MonadIO m, MonadTrace m) => Text -> m a -> m a
|
|
newSpan name body = do
|
|
spanId <- randomSpanId
|
|
newSpanWith spanId name body
|