Core.Telemetry.Identifiers

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.

Traces and Spans

data Trace

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.

Instances

IsString Trace

Defined in Core.Program.Context

Methods

fromString :: String -> Trace

Show Trace

Defined in Core.Program.Context

Methods

showsPrec :: Int -> Trace -> ShowS

show :: Trace -> String

showList :: [Trace] -> ShowS

Eq Trace

Defined in Core.Program.Context

Methods

(==) :: Trace -> Trace -> Bool

(/=) :: Trace -> Trace -> Bool

getIdentifierTrace :: Program τ (Maybe Trace)

Get the identifier of the current trace, if you are within a trace started by beginTrace or usingTrace.

Since: 0.1.9

data Span

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.

Instances

IsString Span

Defined in Core.Program.Context

Methods

fromString :: String -> Span

Show Span

Defined in Core.Program.Context

Methods

showsPrec :: Int -> Span -> ShowS

show :: Span -> String

showList :: [Span] -> ShowS

Eq Span

Defined in Core.Program.Context

Methods

(==) :: Span -> Span -> Bool

(/=) :: Span -> Span -> Bool

getIdentifierSpan :: Program τ (Maybe Span)

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

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

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

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

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

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)

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