documenting modules and functions related to propagators

apps/opentelemetry_api/src/otel_propagator.erl

@@ -12,14 +12,28 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
+%% @doc A Propagator injects or extracts data from a Context so information
+%% like baggage and trace context can be transported along with cross service
+%% requests, like an HTTP request.
+%%
+%% Propagators are defined based on the type of encoding they inject and
+%% extract. At this time there is only a TextMapPropagator,
+%% {@link otel_propagator_text_map}, which works on ASCII keys and values.
+%%
+%% This behaviour is only for defining the callbacks used by each propagator
+%% per type and is only used by developers adding a new type of propagator
+%% (like for binary protocols), not implementations of propagators themselves
+%% (like B3 or W3C TraceContext).
+%%
+%% Users configure and call propagators based on their type. See the docs
+%% for {@link otel_propagator_text_map} for more details.
 %% @end
 %%%-------------------------------------------------------------------------
 -module(otel_propagator).
 
 -export([builtin_to_module/1]).
 
-%% sets a value into a carrier
+%% Sets a value into a carrier
 -callback inject(otel_ctx:t(), carrier()) -> carrier().
 %% extracts values from a carrier and sets them in the context
 -callback extract(otel_ctx:t(), carrier()) -> otel_ctx:t().
@@ -31,6 +45,7 @@
 
 %% convert the short name of a propagator to its module name if it is a builtin
 %% if the name doens't match a builtin it is assumed to be a module
+%% @hidden
 builtin_to_module(tracecontext) ->
     otel_propagator_trace_context;
 builtin_to_module(trace_context) ->

apps/opentelemetry_api/src/otel_propagator_b3.erl

@@ -12,7 +12,41 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
+%% @doc An implementation of {@link otel_propagator_text_map} that injects and
+%% extracts trace context using the B3 specification from Zipkin.
+%%
+%% Since `trace_context' and `baggage' are the two default propagators the
+%% global TextMap Propagators must be configured if B3 is to be used for
+%% propagation:
+%%
+%% ```
+%% {text_map_propagators, [b3, baggage]},
+%% '''
+%%
+%% ```
+%% opentelemetry:set_text_map_propagators([b3]).
+%% '''
+%%
+%% It is also possible to set a separate list of injectors or extractors.
+%% For example, if the service should extract B3 encoded context but you
+%% only want to inject context encoded with the W3C TraceContext format
+%% (maybe you have some services only supporting B3 that are making requests
+%% to your server but you have no reason to continue propagating in both
+%% formats when communicating to other services further down the stack).
+%% In that case you would instead set configuration like:
+%%
+%%
+%% ```
+%% {text_map_extractors, [b3, trace_context, baggage]},
+%% {text_map_injectors, [trace_context, baggage]},
+%% '''
+%%
+%% Or using calls to {@link opentelemetry} at runtime:
+%%
+%% ```
+%% opentelemetry:set_text_map_extractors([b3, trace_context, baggage]),
+%% opentelemetry:set_text_map_injectors([trace_context, baggage]).
+%% '''
 %% @end
 %%%-----------------------------------------------------------------------
 -module(otel_propagator_b3).

apps/opentelemetry_api/src/otel_propagator_baggage.erl

@@ -12,7 +12,19 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
+%% @doc An implementation of {@link otel_propagator_text_map} that injects and
+%% extracts baggage using the
+%% <a href="https://w3c.github.io/baggage/">W3C Baggage format</a>.
+%%
+%% This propagator along with {@link otel_propagator_trace_context} are used
+%% by default. The global TextMap Propagators can be configured in the
+%% application environment:
+%%
+%% ```
+%% {text_map_propagators, [trace_context, baggage]},
+%% '''
+%%
+%% Or by calling {@link opentelemetry:set_text_map_propagators/1}.
 %% @end
 %%%-----------------------------------------------------------------------
 -module(otel_propagator_baggage).

apps/opentelemetry_api/src/otel_propagator_text_map.erl

@@ -12,7 +12,45 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
+%% @doc A TextMap Propagator is a Propagator that performs injection and
+%% extraction with ASCII keys and values.
+%%
+%% An example of
+%% configuring the TextMap Propagator to inject and extract Baggage and
+%% TraceContext:
+%%
+%% ```
+%% {text_map_propagators, [trace_context, baggage]},
+%% '''
+%%
+%% The propagators are then used at the points that cross service
+%% communication is performed. By default `inject' and `extract' work on a
+%% generic list of 2-tuple's with binary string keys and values. A user
+%% defined function for setting a key/value in the carrier and for getting
+%% the value of a key from a carrier can be passed as an argument. For
+%% example, injecting and extracting to and from Hackney headers could be
+%% done with <a href="https://github.com/benoitc/hackney">Hackney</a> specific functions:
+%%
+%% ```
+%% set_header(Headers, Key, Value) ->
+%%   hackney_headers:store(Key, Value, Headers).
+%%
+%% some_fun_calling_hackney() ->
+%%   Headers = otel_propagator_text_map:inject(hackney_headers:new(), fun set_header/2),
+%%   ...
+%% '''
+%%
+%% An example of extraction in an <a href="https://github.com/elli-lib/elli">Elli</a> request handler:
+%%
+%% ```
+%% get_header(Req, Key) ->
+%%   elli_request:get_header(Key, Req, Default).
+%%
+%% handle(Req, _Args) ->
+%%   otel_propagator_text_map:extract(Req, fun get_header/2),
+%%   ...
+%%   {ok, [], <<"hello world">>}.
+%% '''
 %% @end
 %%%-------------------------------------------------------------------------
 -module(otel_propagator_text_map).
@@ -32,9 +70,13 @@
 
 -include_lib("kernel/include/logger.hrl").
 
+%% Sets a value into a carrier
 -callback inject(otel_ctx:t(), otel_propagator:carrier(), carrier_set()) -> otel_propagator:carrier().
+
+%% Extracts values from a carrier and sets them in the context
 -callback extract(otel_ctx:t(), otel_propagator:carrier(), carrier_keys(), carrier_get()) -> term().
-%% returns all the keys the propagator sets with `inject'
+
+%% Returns all the keys the propagator sets with `inject'
 -callback fields() -> [field_key()].
 
 -type field_key() :: unicode:latin1_binary().
@@ -44,7 +86,7 @@
 %% for example: with the jaeger propagation format this would be
 %% all keys found with prefix "uberctx-"
 -type carrier_keys() :: fun((otel_propagator:carrier()) -> [unicode:latin1_binary()]).
--type carrier_get() :: fun((otel_propagator:carrier(), unicode:latin1_binary()) -> unicode:latin1_binary()).
+-type carrier_get() :: fun((otel_propagator:carrier(), unicode:latin1_binary()) -> unicode:latin1_binary() | undefined).
 -type carrier_set() :: fun((otel_propagator:carrier(), unicode:latin1_binary(), unicode:latin1_binary()) -> otel_propagator:carrier()).
 
 -type default_text_map_carrier() :: [{unicode:latin1_binary(), unicode:latin1_binary()}].

apps/opentelemetry_api/src/otel_propagator_trace_context.erl

@@ -12,7 +12,19 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
+%% @doc An implementation of {@link otel_propagator_text_map} that injects and
+%% extracts trace context using the
+%% <a href="https://www.w3.org/TR/trace-context/">W3C TraceContext format</a>.
+%%
+%% This propagator along with {@link otel_propagator_baggage} are used
+%% by default. The global TextMap Propagators can be configured in the
+%% application environment:
+%%
+%% ```
+%% {text_map_propagators, [trace_context, baggage]},
+%% '''
+%%
+%% Or by calling {@link opentelemetry:set_text_map_propagators/1}.
 %% @end
 %%%-----------------------------------------------------------------------
 -module(otel_propagator_trace_context).