2022-09-20 05:48:21 +03:00
|
|
|
module Hasura.Tracing.TraceId
|
|
|
|
( -- * TraceId
|
|
|
|
TraceId,
|
|
|
|
randomTraceId,
|
|
|
|
traceIdFromBytes,
|
|
|
|
traceIdToBytes,
|
|
|
|
traceIdFromHex,
|
|
|
|
traceIdToHex,
|
|
|
|
|
|
|
|
-- * SpanId
|
|
|
|
SpanId,
|
|
|
|
randomSpanId,
|
|
|
|
spanIdFromBytes,
|
|
|
|
spanIdToBytes,
|
|
|
|
spanIdFromHex,
|
|
|
|
spanIdToHex,
|
|
|
|
)
|
|
|
|
where
|
|
|
|
|
|
|
|
import Data.Bits ((.|.))
|
|
|
|
import Data.ByteString (ByteString)
|
|
|
|
import Data.ByteString qualified as ByteString
|
|
|
|
import Data.ByteString.Base16 qualified as Base16
|
|
|
|
import Data.Serialize qualified as Serialize
|
|
|
|
import Hasura.Prelude
|
|
|
|
import System.Random.Stateful qualified as Random
|
|
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
Rewrite `Tracing` to allow for only one `TraceT` in the entire stack.
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
2023-03-13 20:37:16 +03:00
|
|
|
-- TraceId
|
2022-09-20 05:48:21 +03:00
|
|
|
|
|
|
|
-- | 128-bit trace identifiers.
|
|
|
|
--
|
|
|
|
-- 'TraceId's are guaranteed to have at least one non-zero bit.
|
|
|
|
data TraceId
|
|
|
|
= TraceId
|
|
|
|
{-# UNPACK #-} !Word64
|
|
|
|
{-# UNPACK #-} !Word64
|
|
|
|
deriving (Eq)
|
|
|
|
|
|
|
|
-- 128 bits
|
|
|
|
traceIdBytes :: Int
|
|
|
|
traceIdBytes = 16
|
|
|
|
|
2023-05-24 16:51:56 +03:00
|
|
|
randomTraceId :: (MonadIO m) => m TraceId
|
Rewrite `Tracing` to allow for only one `TraceT` in the entire stack.
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
2023-03-13 20:37:16 +03:00
|
|
|
randomTraceId = liftIO do
|
2022-09-20 05:48:21 +03:00
|
|
|
(w1, w2) <-
|
|
|
|
flip Random.applyAtomicGen Random.globalStdGen $ \gen0 ->
|
|
|
|
let (!w1, !gen1) = Random.random gen0
|
|
|
|
(!w2, !gen2) = Random.random gen1
|
|
|
|
in ((w1, w2), gen2)
|
|
|
|
if w1 .|. w2 == 0
|
|
|
|
then randomTraceId
|
|
|
|
else pure $ TraceId w1 w2
|
|
|
|
|
|
|
|
-- | Create a 'TraceId' from a 'ByteString'.
|
|
|
|
--
|
|
|
|
-- Fails if the 'ByteString' is not exactly 16 bytes long, or if it contains
|
|
|
|
-- only zero bytes.
|
|
|
|
traceIdFromBytes :: ByteString -> Maybe TraceId
|
|
|
|
traceIdFromBytes bs = do
|
|
|
|
guard $ ByteString.length bs == traceIdBytes
|
|
|
|
(w1, w2) <-
|
2023-05-24 16:51:56 +03:00
|
|
|
eitherToMaybe
|
|
|
|
$ flip Serialize.runGet bs
|
|
|
|
$ (,)
|
|
|
|
<$> Serialize.getWord64be
|
|
|
|
<*> Serialize.getWord64be
|
2022-09-20 05:48:21 +03:00
|
|
|
guard $ w1 .|. w2 /= 0
|
|
|
|
pure $ TraceId w1 w2
|
|
|
|
|
|
|
|
-- | Convert a 'TraceId' to a 'ByteString' of 16 bytes.
|
|
|
|
traceIdToBytes :: TraceId -> ByteString
|
|
|
|
traceIdToBytes (TraceId w1 w2) =
|
|
|
|
Serialize.runPut $ Serialize.putWord64be w1 >> Serialize.putWord64be w2
|
|
|
|
|
|
|
|
-- | Create a 'TraceId' from a 'ByteString' of hex characters.
|
|
|
|
--
|
|
|
|
-- Fails if the 'ByteString' is not exactly 32 characters long, or if it
|
|
|
|
-- contains only zero characters.
|
|
|
|
traceIdFromHex :: ByteString -> Maybe TraceId
|
|
|
|
traceIdFromHex = traceIdFromBytes <=< eitherToMaybe . Base16.decode
|
|
|
|
|
|
|
|
-- | Convert a 'TraceId' to a 'ByteString' of 32 lowercase hex characters.
|
|
|
|
traceIdToHex :: TraceId -> ByteString
|
|
|
|
traceIdToHex = Base16.encode . traceIdToBytes
|
|
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
Rewrite `Tracing` to allow for only one `TraceT` in the entire stack.
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
2023-03-13 20:37:16 +03:00
|
|
|
-- SpanId
|
2022-09-20 05:48:21 +03:00
|
|
|
|
|
|
|
-- | 64-bit span identifiers
|
|
|
|
--
|
|
|
|
-- 'SpanId's are guaranteed to have at least one non-zero bit.
|
|
|
|
newtype SpanId = SpanId Word64
|
|
|
|
deriving (Eq)
|
|
|
|
|
|
|
|
-- 64 bits
|
|
|
|
spanIdBytes :: Int
|
|
|
|
spanIdBytes = 8
|
|
|
|
|
2023-05-24 16:51:56 +03:00
|
|
|
randomSpanId :: (MonadIO m) => m SpanId
|
Rewrite `Tracing` to allow for only one `TraceT` in the entire stack.
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
2023-03-13 20:37:16 +03:00
|
|
|
randomSpanId = liftIO do
|
2022-09-20 05:48:21 +03:00
|
|
|
w <- Random.uniformM Random.globalStdGen
|
|
|
|
if w == 0
|
|
|
|
then randomSpanId
|
|
|
|
else pure $ SpanId w
|
|
|
|
|
|
|
|
-- | Create a 'SpanId' from a 'ByteString'.
|
|
|
|
--
|
|
|
|
-- Fails if the 'ByteString' is not exactly 8 bytes long, or if it contains
|
|
|
|
-- only zero bytes.
|
|
|
|
spanIdFromBytes :: ByteString -> Maybe SpanId
|
|
|
|
spanIdFromBytes bs = do
|
|
|
|
guard $ ByteString.length bs == spanIdBytes
|
|
|
|
w <- eitherToMaybe $ Serialize.runGet Serialize.getWord64be bs
|
|
|
|
guard $ w /= 0
|
|
|
|
pure $ SpanId w
|
|
|
|
|
|
|
|
-- | Convert a 'SpanId' to a 'ByteString' of 8 bytes.
|
|
|
|
spanIdToBytes :: SpanId -> ByteString
|
|
|
|
spanIdToBytes (SpanId w) = Serialize.runPut $ Serialize.putWord64be w
|
|
|
|
|
|
|
|
-- | Create a 'SpanId' from a 'ByteString' of hex characters.
|
|
|
|
--
|
|
|
|
-- Fails if the 'ByteString' is not exactly 16 characters long, or if it
|
|
|
|
-- contains only zero characters.
|
|
|
|
spanIdFromHex :: ByteString -> Maybe SpanId
|
|
|
|
spanIdFromHex = spanIdFromBytes <=< eitherToMaybe . Base16.decode
|
|
|
|
|
|
|
|
-- | Convert a 'SpanId' to a 'ByteString' of 16 lowercase hex characters.
|
|
|
|
spanIdToHex :: SpanId -> ByteString
|
|
|
|
spanIdToHex = Base16.encode . spanIdToBytes
|