Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Machinery for generating identifiers to be used in traces and spans. Meets the
requirements of the W3C Trace
Context
specification, specifically as relates to forming trace identifiers and span
identifiers into traceparent
headers. The key requirements are that traces
be globally unique and that spans be unique within a trace.
Synopsis
- data Trace
- getIdentifierTrace :: Program τ (Maybe Trace)
- data Span
- getIdentifierSpan :: Program τ (Maybe Span)
- setIdentifierSpan :: Span -> Program t ()
- createIdentifierTrace :: Time -> Word16 -> MAC -> Trace
- createIdentifierSpan :: Time -> Word16 -> Span
- hostMachineIdentity :: MAC
- createTraceParentHeader :: Trace -> Span -> Rope
- parseTraceParentHeader :: Rope -> Maybe (Trace, Span)
Traces and Spans
Unique identifier for a trace. If your program is the top of an service stack
then you can use beginTrace
to generate a new
idenfifier for this request or iteration. More commonly, however, you will
inherit the trace identifier from the application or service which invokes
this program or request handler, and you can specify it by using
usingTrace
.
getIdentifierTrace :: Program τ (Maybe Trace) Source #
Get the identifier of the current trace, if you are within a trace started by
beginTrace
or
usingTrace
.
Since: 0.1.9
Unique identifier for a span. This will be generated by
encloseSpan
but for the case where you are
continuing an inherited trace and passed the identifier of the parent span you
can specify it using this constructor.
getIdentifierSpan :: Program τ (Maybe Span) Source #
Get the identifier of the current span, if you are currently within a span
created by encloseSpan
.
Since: 0.1.9
setIdentifierSpan :: Span -> Program t () Source #
Override the identifier of the current span, if you are currently within a
span created by encloseSpan
. This is an unsafe
action, specifically and only for the situation where you need create a parent
span for an asynchronous process whose unique identifier has already been
nominated. In this scenario all child spans would already have been created
with this span identifier as their parent, leaving you with the final task of
creating a "root" span within the trace with that parent identifier.
Since: 0.2.1
Internals
createIdentifierTrace :: Time -> Word16 -> MAC -> Trace Source #
Generate an identifier suitable for use in a trace context. Trace identifiers are 16 bytes. We incorporate the time to nanosecond precision, the host system's MAC address, and a random element. This is similar to a version 1 UUID, but we render the least significant bits of the time stamp ordered first so that visual distinctiveness is on the left. The MAC address in the lower 48 bits is not reversed, leaving the most distinctiveness [the actual host as opposed to manufacturer OIN] hanging on the right hand edge of the identifier. The two bytes of supplied randomness are put in the middle.
Since: 0.1.9
createIdentifierSpan :: Time -> Word16 -> Span Source #
Generate an identifier for a span. We only have 8 bytes to work with. We use the nanosecond prescision Time with the nibbles reversed, and then overwrite the last two bytes with the supplied random value.
Since: 0.1.9
hostMachineIdentity :: MAC Source #
Get the MAC address of the first interface that's not the loopback device. If something goes weird then we return a valid but bogus address (in the locally administered addresses block).
Since: 0.1.9
createTraceParentHeader :: Trace -> Span -> Rope Source #
Render the Trace
and Span
identifiers representing a span calling onward
to another component in a distributed system. The W3C Trace Context
recommendation specifies the HTTP header traceparent
with a version sequence
(currently hard coded at 00
), the 16 byte trace identifier, the 8 byte span
identifier, and a flag sequence (currently quite ignored), all formatted as
follows:
traceparent: 00-fd533dbf96ecdc610156482ae36c24f7-1d1e9dbf96ec4649-00
Since: 0.1.9
parseTraceParentHeader :: Rope -> Maybe (Trace, Span) Source #
Parse a traceparent
header into a Trace
and Span
, assuming it was a
valid pair according to the W3C Trace Context recommendation. The expectation
is that, if present in an HTTP request, these values would be passed to
usingTrace
to allow the program to contribute
spans to an existing trace started by another program or service.
Since: 0.1.10