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

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

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

Internals

createIdentifierTrace :: TimeStamp -> 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 randomness are in the middle.

Since: 0.1.9

createIdentifierSpan :: TimeStamp -> Word16 -> Span

Generate an identifier for a span. We only have 8 bytes to work with. We use the nanosecond prescision timestamp with the nibbles reversed, and then overwrite the last two bytes with a 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 the 16 byte trace identifier and the 8 byte span identifier formatted as follows:

traceparent: 00-fd533dbf96ecdc610156482ae36c24f7-1d1e9dbf96ec4649-00

Since: 0.1.9