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
Link to this section Types
Link to this section Functions
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:
Result | trace ids? | sampled | debug | should sample? |
---|---|---|---|---|
:join | true | false | false | no |
:join | true | true | false | yes |
:join | true | false | true | yes |
:join | true | true | true | yes |
:join | true | :absent | true | yes |
:join | true | :absent | false | maybe |
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)