Tapper Plug v0.5.0 Tapper.Plug.HeaderPropagation View Source

Decode/Encode B3 headers to/from trace context.

Sub-module Tapper.Plug.HeaderPropagation.B3Multi supports the orginal B3 multi-header format, whilst Tapper.Plug.HeaderPropagation.B3Single supports the newer B3 Single format.

On decode, this module first tries to locate and decode a b3 header in B3 Single format, and if it doesn’t exist, tries to find and decode the multiple B3 headers format. If neither exist, the caller is free to decide whether to sample the trace.

On encode the format is entirely up to the caller, and which module they choose to call.

NB The decode APIs are currently semi-private to this module (and Tapper.Plug), and are therefore subject to change in minor versions. The encoding APIs are stable across minor versions.

Link to this section Summary

Functions

Decode B3 headers from a list of {header_name, header_value} tuples, supporting multiple B3 propagation formats

Encode a Tapper id into a list of B3 Multi format propagation headers, i.e. a list of 2-tuples like {"x-b3-traceid", "463ac35c9f6413ad48485a3953bb6124"}

Link to this section Types

Link to this type sampled() View Source
sampled() :: boolean() | :absent

Link to this section Functions

Link to this function decode(headers) View Source
decode([{String.t(), String.t()}] | map()) ::
  {:join, Tapper.TraceId.t(), Tapper.SpanId.t(), Tapper.SpanId.t(), sampled(),
   boolean()}
  | :start

Decode B3 headers from a list of {header_name, header_value} tuples, supporting multiple B3 propagation formats.

Returns either the atom :start if (valid) B3 headers were not present (which is a suggestion, rather than an instruction, since sampling is a separate concern), or the tuple {:join, trace_id, span_id, parent_span_id, sampled, debug} which passes on the decoded values of the B3 headers. Note that if the parent_span_id is absent, implying the root span, this function sets it to the atom :root, rather than nil.

Whether the trace should be sampled on a :join result depends on the values of sampled and debug. sampled can be true (the originator is sampling this trace, and expects us to do so too) or false when the originator is not sampling this trace and doesn’t expect us to either, or the atom :absent when the originator does not pass the X-B3-Sampled header, implying that determining whether to trace is up to us. The debug flag, if true implies we should always sample the trace regardless of the sampled status:

Resulttrace ids?sampleddebugshould sample?
:jointruefalsefalseno
:jointruetruefalseyes
:jointruefalsetrueyes
:jointruetruetrueyes
:jointrue:absenttrueyes
:jointrue:absentfalsemaybe

Encode a Tapper id into a list of B3 Multi format propagation headers, i.e. a list of 2-tuples like {"x-b3-traceid", "463ac35c9f6413ad48485a3953bb6124"}.

This encodes to headers in the original B3 multi-header format, to use the B3 Single format, use Tapper.Plug.HeaderPropagation.B3Single.encode_value/1.

Example

  id = Tapper.start_span(id, name: "foo")
...
  headers = Tapper.Plug.HeaderPropagation.encode(id)
  response = HTTPoison.get("http://some.service.com/some/api", headers)