Tapper Plug v0.2.0 Tapper.Plug.HeaderPropagation

Decode/Encode B3 Headers to/from trace properties.

Summary

Functions

Decode B3 headers from a list of {header_name, header_value} tuples

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

Types

sampled()
sampled() :: boolean | :absent

Functions

decode(headers)
decode([{String.t, String.t}]) ::
  {:join, Tapper.Id.TraceId.t, Tapper.Id.SpanId.t, Tapper.Id.SpanId.t, sampled, boolean} |
  :start

Decode B3 headers from a list of {header_name, header_value} tuples.

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:

Resultsampleddebugshould sample?
:joinfalsefalseno
:jointruefalseyes
:joinfalsetrueyes
:jointruetrueyes
:join:absenttrueyes
:join:absentfalsemaybe
encode(arg1)
encode(Tapper.Id.t | {String.t, String.t, String.t, boolean, boolean}) :: [{String.t, String.t}]

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

Example

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