Module passage_span_context

Description
Data Types
Function Index
Function Details

Span Context.

This module defines the passage_span_context behaviour.
Required callback functions: make_span_context_state/1, inject_span_context/4, extract_span_context/3.

Description

Span Context.

Each SpanContext encapsulates the following state:

Any OpenTracing-implementation-dependent state (for example, trace and span ids) needed to refer to a distinct Span across a process boundary

Baggage Items, which are just key:value pairs that cross process boundaries

The OpenTracing Data Model

Callbacks

This module requires following callbacks:

  %% @doc Creates the state of a span context from the given references.
  -callback make_span_context_state(passage:refs()) ->
      state().
 
  %% @doc Injects the span context into the carrier by the specified format.
  -callback inject_span_context(context(), format(), inject_fun(), carrier()) ->
      carrier().
 
  %% @doc Extracts a span context from the carrier using the specified format.
  %%
  %% If the carrier contains no span context, it will return `error'.
  -callback extract_span_context(format(), iterate_fun(), carrier()) ->
      {ok, context()} | error.

Data Types

carrier()

carrier() = term()

Carrier for propagating span contexts.

context()

abstract datatype: context()

Span context.

format()

format() = text_map | http_header | binary

The standard injection/extraction format.

Both injection and extraction rely on an extensible format parameter that dictates the type of the associated "carrier" as well as how a SpanContext is encoded in that carrier. All of the following formats must be supported by all Tracer implementations.

Text Map: an arbitrary string-to-string map with an unrestricted character set for both keys and values

HTTP Headers: a string-to-string map with keys and values that are suitable for use in HTTP headers (a la RFC 7230. In practice, since there is such "diversity" in the way that HTTP headers are treated in the wild, it is strongly recommended that Tracer implementations use a limited HTTP header key space and escape values conservatively.

Binary: a (single) arbitrary binary blob representing a SpanContext

Note: required formats for injection and extraction (The OpenTracing Semantic Specification)

implementation_module()

implementation_module() = module()

Implementation module of this behaviour.

inject_fun()

inject_fun() = fun((Key::binary(), Value::binary(), carrier()) -> carrier())

Span context injection function.

If this function is called, the carrier should update own state for injecting Key and Value.

iterate_fun()

iterate_fun() = fun((carrier()) -> {ok, Key::binary(), Value::binary(), carrier()} | error)

Iterator function.

If the carrier has any remaining elements, it will return an ok tuple that contains a key/value pair and updated state. Otherwise, it will return error.

state()

state() = term()

Implementation-dependent state.

Function Index

get_baggage_items/1	Returns the baggage items of `Context`.
get_state/1	Returns the state of `Context`.
make/2	Makes a new span context.

Function Details

get_baggage_items/1

get_baggage_items(Context::context()) -> passage:baggage_items()

Returns the baggage items of Context.

get_state/1

get_state(Context::context()) -> state()

Returns the state of Context.

make/2

make(State::state(), BaggageItems::passage:baggage_items()) -> context()

Makes a new span context.

Generated by EDoc