Add documentation
diff --git a/src/passage.erl b/src/passage.erl
index ce358f1..5398435 100644
--- a/src/passage.erl
+++ b/src/passage.erl
@@ -1,7 +1,33 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc API for operating active spans.
%%
+%% Most of the functions and types provided in this module are based on the
+%% <a href="https://github.com/opentracing/specification/blob/1.1/specification.md">OpenTracing API</a>.
+%%
+%% === Examples ===
+%%
+%% ```
+%% %% Registers `tracer'
+%% Context = passage_span_context_null,
+%% Sampler = passage_sampler_all:new(),
+%% Reporter = passage_reporter_process:new(self(), span),
+%% ok = passage_tracer_registry:register(tracer, Context, Sampler, Reporter),
+%%
+%% %% Starts a root span
+%% RootSpan = passage:start_root_span(example_root, tracer),
+%%
+%% %% Starts a child span
+%% ChildSpan = passage:start_span(example_child, {child_of, RootSpan}),
+%%
+%% %% Finishes spans
+%% passage:finish_span(ChildSpan),
+%% passage:finish_span(RootSpan),
+%%
+%% %% Receives the finished spans
+%% receive {span, FinishedChildSpan} -> ok end,
+%% receive {span, FinishedRootSpan} -> ok end.
+%% '''
-module(passage).
%%------------------------------------------------------------------------------
@@ -34,124 +60,213 @@
%% Exported Types
%%------------------------------------------------------------------------------
-type tracer_id() :: atom().
+%% Tracer identifier.
-type maybe_span() :: passage_span:span() | undefined.
+%% Sampled or unsampled span.
+%%
+%% `undefined' means the span is unsampled.
-type operation_name() :: atom().
+%% Operation name.
+
+-type refs() :: [ref()].
+%% Span references.
+
+-type ref() :: {ref_type(), maybe_span()}.
+%% Span reference.
+%%
+%% See also: <a href="https://github.com/opentracing/specification/blob/1.1/specification.md#references-between-spans">References between Spans (The OpenTracing Semantic Specification)</a>
+
+-type ref_type() :: child_of | follows_from.
+%% Span reference type.
+
+-type tags() :: #{tag_name() => tag_value()}.
+%% Span tags.
+%%
+%% See also: <a href="https://github.com/opentracing/specification/blob/1.1/semantic_conventions.md#span-tags-table">Standard span tags (OpenTracing API)</a>
+
+-type tag_name() :: atom().
+%% Tag name.
+
+-type tag_value() :: term().
+%% Tag value.
+
+-type baggage_items() :: #{baggage_item_name() => baggage_item_value()}.
+%% Baggage items.
+%%
+%% Baggage items are just key/value pairs that cross OS process boundaries.
+
+-type baggage_item_name() :: binary().
+%% Baggage item name.
+
+-type baggage_item_value() :: binary().
+%% Baggage item value.
+
+-type log_fields() :: #{log_field_name() => log_field_value()}.
+%% Span log fields.
+%%
+%% See also: <a href="https://github.com/opentracing/specification/blob/1.1/semantic_conventions.md#log-fields-table">Standard log fields (OpenTracing API)</a>
+
+-type log_field_name() :: atom().
+%% Log field name.
+
+-type log_field_value() :: term().
+%% Log field value.
-type start_root_span_options() :: [start_root_span_option()].
+%% Options for {@link start_root_span/3}.
-type start_root_span_option() :: {time, erlang:timestamp()}
| {tags, tags()}.
+%% <ul>
+%% <li><b>time</b>: Start timestamp of the span. The default value is `erlang:timestamp()'.</li>
+%% <li><b>tags</b>: Tags associated to the span. The default value is `#{}'.</li>
+%% </ul>
-type start_span_options() :: [start_span_option()].
+%% Options for {@link start_span/3}.
-type start_span_option() :: {refs, refs()}
| start_root_span_option().
+%% <ul>
+%% <li><b>refs</b>: Additional references related to the span. The default value is `[]'. </li>
+%% </ul>
-type finish_span_options() :: [finish_span_option()].
+%% Options for {@link finish_span/2}.
+
-type finish_span_option() :: {time, erlang:timestamp()}.
-
--type refs() :: [ref()].
--type ref() :: {ref_type(), maybe_span()}.
--type ref_type() :: child_of | follows_from.
-
--type tags() :: #{tag_name() => tag_value()}.
--type tag_name() :: atom().
--type tag_value() :: term().
-
--type baggage_items() :: #{baggage_item_name() => baggage_item_value()}.
--type baggage_item_name() :: binary().
--type baggage_item_value() :: binary().
-
--type log_fields() :: #{log_field_name() => log_field_value()}.
--type log_field_name() :: atom().
--type log_field_value() :: term().
+%% <ul>
+%% <li><b>time</b>: Finish timestamp of the span. The default value is `erlang:timestamp()'.</li>
+%% </ul>
-type log_options() :: [log_option()].
+%% Options for {@link log/3}.
-type log_option() :: {time, erlang:timestamp()}.
-
+%% <ul>
+%% <li><b>time</b>: Timestamp of the log. The default value is `erlang:timestamp()'.</li>
+%% </ul>
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @equiv start_root_span(OperationName, Tracer, [])
-spec start_root_span(operation_name(), tracer_id()) -> maybe_span().
start_root_span(OperationName, Tracer) ->
start_root_span(OperationName, Tracer, []).
+%% @doc Starts a root span.
+%%
+%% If the sampler associated with `Tracer' does not sample the span,
+%% this function will return `undefined'.
-spec start_root_span(operation_name(), tracer_id(), start_root_span_options()) ->
maybe_span().
start_root_span(OperationName, Tracer, Options) ->
passage_span:start_root(Tracer, OperationName, Options).
+%% @equiv start_span(OperationName, PrimaryReference, [])
-spec start_span(operation_name(), ref()) -> maybe_span().
start_span(OperationName, PrimaryReference) ->
start_span(OperationName, PrimaryReference, []).
+%% @doc Starts a span.
+%%
+%% If there is no sampled span references, this function will return `undefined'.
-spec start_span(operation_name(), ref(), start_span_options()) -> maybe_span().
-start_span(OperationName, PrimaryReference, Options0) ->
+start_span(OperationName, PrimaryReference, Options) ->
{Refs1, Options2} =
- case lists:keytake(refs, 1, Options0) of
- false -> {[], Options0};
+ case lists:keytake(refs, 1, Options) of
+ false -> {[], Options};
{value, {refs, Refs0}, Options1} -> {Refs0, Options1}
end,
Options3 = [{refs, [PrimaryReference | Refs1]} | Options2],
passage_span:start(OperationName, Options3).
+%% @equiv finish_span(Span, [])
-spec finish_span(maybe_span()) -> ok.
finish_span(Span) ->
finish_span(Span, []).
+%% @doc Finishes the span.
+%%
+%% The finished span will be sent an external observer via
+%% the reporter associated with the tracer of the span.
+%%
+%% Note that if you call this function on the same span more than once,
+%% duplicate reports will be sent.
-spec finish_span(maybe_span(), finish_span_options()) -> ok.
finish_span(undefined, _) -> ok;
finish_span(Span, Options) ->
passage_span:finish(Span, Options).
+%% @doc Sets the operation name of `Span' to `Name'.
-spec set_operation_name(maybe_span(), operation_name()) -> maybe_span().
set_operation_name(undefined, _) -> undefined;
set_operation_name(Span, Name) -> passage_span:set_operation_name(Span, Name).
+%% @doc Sets the tags of `Span' to `Tags'.
+%%
+%% Note that the existing tags which have different keys with `Tags' are preserved.
-spec set_tags(maybe_span(), tags()) -> maybe_span().
set_tags(undefined, _) -> undefined;
set_tags(Span, Tags) -> passage_span:set_tags(Span, Tags).
+%% @doc Sets the baggage items of `Span' to `Items'.
+%%
+%% Note that the existing items which have different keys with `Items' are preserved.
+%%
+%% See also: <a href="https://github.com/opentracing/specification/blob/1.1/specification.md#set-a-baggage-item">Set a baggage item (The OpenTracing Semantic Specification)</a>
-spec set_baggage_items(maybe_span(), baggage_items()) -> maybe_span().
set_baggage_items(undefined, _) -> undefined;
set_baggage_items(Span, Items) -> passage_span:set_baggage_items(Span, Items).
--spec get_baggage_items(maybe_span()) -> baggage_items().
+%% @doc Returns the baggage items carried by `Span'.
+-spec get_baggage_items(Span :: maybe_span()) -> baggage_items().
get_baggage_items(undefined) -> #{};
get_baggage_items(Span) -> passage_span:get_baggage_items(Span).
+%% @equiv log(Span, Fields, [])
-spec log(maybe_span(), log_fields()) -> maybe_span().
log(Span, Fields) ->
log(Span, Fields, []).
+%% @doc Logs the `Fields' to `Span'.
-spec log(maybe_span(), log_fields(), log_options()) -> maybe_span().
log(undefined, _, _) -> undefined;
log(Span, Fields, Options) -> passage_span:log(Span, Fields, Options).
+%% @equiv error_log(Span, Message, [])
-spec error_log(maybe_span(), iodata()) -> maybe_span().
error_log(Span, Message) ->
error_log(Span, Message, []).
+%% @equiv error_log(Span, Format, Data, #{})
-spec error_log(maybe_span(), io:format(), [term()]) -> maybe_span().
error_log(Span, Format, Data) ->
error_log(Span, Format, Data, #{}).
+%% @equiv error_log(Span, Format, Data, Fields, [])
-spec error_log(maybe_span(), io:format(), [term()], log_fields()) -> maybe_span().
error_log(Span, Format, Data, Fields) ->
error_log(Span, Format, Data, Fields, []).
+%% @doc Logs error message to `Span'.
+%%
+%% This function logs `Fields` and
+%% `#{event => error, message => io_lib:format(Format, Data)}'.
+%%
+%% In addition, it sets the tag `#{error => true}' automatically.
-spec error_log(maybe_span(), io:format(), [term()], log_fields(), log_options()) ->
maybe_span().
error_log(undefined, _, _, _, _) -> undefined;
-error_log(Span0, Format, Data, Fields0, Options) ->
+error_log(Span0, Format, Data, Fields, Options) ->
Message = io_lib:format(Format, Data),
- Fields1 = maps:merge(Fields0, #{event => error, message => Message}),
+ Fields1 = maps:merge(Fields, #{event => error, message => Message}),
Span1 = passage_span:log(Span0, Fields1, Options),
passage_span:set_tags(Span1, #{error => true}).
+%% @doc Injects `Span' into `Carrier'.
-spec inject_span(Span, Format, InjectFun, Carrier) -> Carrier when
Span :: maybe_span(),
Format :: passage_span_context:format(),
@@ -166,6 +281,9 @@
{ok, Module} -> Module:inject_span_context(Context, Format, InjectFun, Carrier)
end.
+%% @doc Extracts a span from `Carrier'.
+%%
+%% If `Carrier' has no span context, this function will return `undefined'.
-spec extract_span(Tracer, Format, IterateFun, Carrier) -> maybe_span() when
Tracer :: tracer_id(),
Format :: passage_span_context:format(),
diff --git a/src/passage_pd.erl b/src/passage_pd.erl
index 05b504a..8209b48 100644
--- a/src/passage_pd.erl
+++ b/src/passage_pd.erl
@@ -1,7 +1,33 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc Process Dictionary version of {@link passage}.
%%
+%% The functions in this module operate on the span
+%% which stored in the process dictionary of the calling process.
+%%
+%% === Examples ===
+%%
+%% ```
+%% %% Registers `tracer'
+%% Context = passage_span_context_null,
+%% Sampler = passage_sampler_all:new(),
+%% Reporter = passage_reporter_process:new(self(), span),
+%% ok = passage_tracer_registry:register(tracer, Context, Sampler, Reporter),
+%%
+%% %% Starts a root span
+%% ok = passage_pd:start_root_span(example_root, tracer),
+%%
+%% %% Starts a child span
+%% ok = passage_pd:start_span(example_child),
+%%
+%% %% Finishes spans
+%% passage_pd:finish_span(), % child
+%% passage_pd:finish_span(), % root
+%%
+%% %% Receives the finished spans
+%% receive {span, FinishedChildSpan} -> ok end,
+%% receive {span, FinishedRootSpan} -> ok end.
+%% '''
-module(passage_pd).
%%------------------------------------------------------------------------------
@@ -28,21 +54,33 @@
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @equiv start_root_span(OperationName, Tracer, [])
-spec start_root_span(passage:operation_name(), passage:tracer_id()) -> ok.
start_root_span(OperationName, Tracer) ->
start_root_span(OperationName, Tracer, []).
--spec start_root_span(passage:operation_name(), passage:tracer_id(), passage:start_root_span_options()) -> ok.
+%% @doc Starts a root span.
+%%
+%% The started span will be pushed to the process dictionary of the calling process.
+%%
+%% If the sampler associated with `Tracer' does not sample the span,
+%% the value of span will be `undefined'.
+-spec start_root_span(passage:operation_name(), passage:tracer_id(),
+ passage:start_root_span_options()) -> ok.
start_root_span(OperationName, Tracer, Options) ->
- case passage:start_root_span(OperationName, Tracer, Options) of
- undefined -> ok;
- Span -> put_ancestors([Span | get_ancestors()])
- end.
+ Span = passage:start_root_span(OperationName, Tracer, Options),
+ put_ancestors([Span | get_ancestors()]).
+%% @equiv start_span(OperationName, [])
-spec start_span(passage:operation_name()) -> ok.
start_span(OperationName) ->
start_span(OperationName, []).
+%% @doc Starts a span.
+%%
+%% The started span will be pushed to the process dictionary of the calling process.
+%%
+%% If there is no sampled span references, the value of span will be `undefined'.
-spec start_span(passage:operation_name(), passage:start_span_options()) -> ok.
start_span(OperationName, Options) ->
Ancestors = get_ancestors(),
@@ -53,27 +91,35 @@
Refs = proplists:get_value(refs, Options, []),
[{refs, [{child_of, Parent} | Refs]} | Options]
end,
- case passage_span:start(OperationName, Options1) of
- undefined -> ok;
- Span -> put_ancestors([Span | Ancestors])
- end.
+ Span = passage_span:start(OperationName, Options1),
+ put_ancestors([Span | Ancestors]).
+%% @equiv finish_span([])
-spec finish_span() -> ok.
finish_span() ->
finish_span([]).
+%% @doc Pops the current span from process dictionary and finishes the span.
+%%
+%% The finished span will be sent an external observer via
+%% the reporter associated with the tracer of the span.
-spec finish_span(passage:finish_span_options()) -> ok.
finish_span(Options) ->
- Span = pop_span(),
- passage:finish_span(Span, Options).
+ case pop_span() of
+ undefined -> ok;
+ Span -> passage:finish_span(Span, Options)
+ end.
+%% @equiv with_root_span(OperationName, Tracer, [], Fun)
-spec with_root_span(passage:operation_name(), passage:tracer_id(), Fun) -> Result when
Fun :: fun (() -> Result),
Result :: term().
with_root_span(OperationName, Tracer, Fun) ->
with_root_span(OperationName, Tracer, [], Fun).
--spec with_root_span(passage:operation_name(), passage:tracer_id(), passage:start_span_options(), Fun) -> Result when
+%% @doc Starts a root span enclosing `Fun'.
+-spec with_root_span(passage:operation_name(), passage:tracer_id(),
+ passage:start_span_options(), Fun) -> Result when
Fun :: fun (() -> Result),
Result :: term().
with_root_span(OperationName, Tracer, Options, Fun) ->
@@ -84,12 +130,14 @@
finish_span()
end.
+%% @equiv with_span(OperationName, [], Fun)
-spec with_span(passage:operation_name(), Fun) -> Result when
Fun :: fun (() -> Result),
Result :: term().
with_span(OperationName, Fun) ->
with_span(OperationName, [], Fun).
+%% @doc Starts a span enclosing `Fun'.
-spec with_span(passage:operation_name(), passage:start_span_options(), Fun) -> Result when
Fun :: fun (() -> Result),
Result :: term().
@@ -101,6 +149,7 @@
finish_span()
end.
+%% @doc Returns the current span stored in the process dictionary of the calling process.
-spec current_span() -> passage:maybe_span().
current_span() ->
case get(?ANCESTORS_KEY) of
@@ -109,44 +158,65 @@
[Span | _] -> Span
end.
+%% @doc Sets the operation name of the current span to `OperationName'.
-spec set_operation_name(passage:operation_name()) -> ok.
set_operation_name(OperationName) ->
update_current_span(
fun (Span) -> passage_span:set_operation_name(Span, OperationName) end).
+%% @doc Sets the tags of the current span to `Tags'.
+%%
+%% Note that the existing tags which have different keys with `Tags' are preserved.
-spec set_tags(passage:tags()) -> ok.
set_tags(Tags) ->
update_current_span(fun (Span) -> passage_span:set_tags(Span, Tags) end).
+%% @doc Sets the baggage items of the current span to `Items'.
+%%
+%% Note that the existing items which have different keys with `Items' are preserved.
+%%
+%% See also: <a href="https://github.com/opentracing/specification/blob/1.1/specification.md#set-a-baggage-item">Set a baggage item (The OpenTracing Semantic Specification)</a>
-spec set_baggage_items(passage:baggage_items()) -> ok.
set_baggage_items(Items) ->
update_current_span(fun (Span) -> passage_span:set_baggage_items(Span, Items) end).
+%% @doc Returns the baggage items carried by the current span.
-spec get_baggage_items() -> passage:baggage_items().
get_baggage_items() ->
Span = current_span(),
passage:get_baggage_items(Span).
+%% @equiv log(Fields, [])
-spec log(passage:log_fields()) -> ok.
log(Fields) ->
log(Fields, []).
+%% @doc Logs the `Fields' to the current span.
-spec log(passage:log_fields(), passage:log_options()) -> ok.
log(Fields, Options) ->
update_current_span(fun (Span) -> passage:log(Span, Fields, Options) end).
+%% @equiv error_log(Message, [])
-spec error_log(iodata()) -> ok.
error_log(Message) ->
error_log(Message, []).
+%% @equiv error_log(Format, Data, #{})
-spec error_log(io:format(), [term()]) -> ok.
error_log(Format, Data) ->
error_log(Format, Data, #{}).
+%% @equiv error_log(Format, Data, Fields, [])
-spec error_log(io:format(), [term()], passage:log_fields()) -> ok.
error_log(Format, Data, Fields) ->
error_log(Format, Data, Fields, []).
+%% @doc Logs error message to the current span.
+%%
+%% This function logs `Fields` and
+%% `#{event => error, message => io_lib:format(Format, Data)}'.
+%%
+%% In addition, it sets the tag `#{error => true}' automatically.
-spec error_log(io:format(), [term()], passage:log_fields(), passage:log_options()) -> ok.
error_log(Format, Data, Fields, Options) ->
update_current_span(
@@ -173,6 +243,7 @@
case get(?ANCESTORS_KEY) of
undefined -> ok;
[] -> ok;
+ [undefined | _] -> ok;
[Span0 | Spans] ->
Span1 = Fun(Span0),
put_ancestors([Span1 | Spans])
diff --git a/src/passage_reporter.erl b/src/passage_reporter.erl
index ed0f635..260ff56 100644
--- a/src/passage_reporter.erl
+++ b/src/passage_reporter.erl
@@ -1,7 +1,18 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc Span Reporter.
%%
+%% Note that this component has not been described in the
+%% <a href="https://github.com/opentracing/specification/blob/1.1/specification.md">OpenTracing Specification</a>.
+%%
+%% === Callbacks ===
+%%
+%% This module requires following callback:
+%%
+%% ```
+%% %% @doc Reports the finished span to an external observer (e.g., Jaeger agent).
+%% -callback report(state(), FinishedSpan :: passage_span:span()) -> Ignored :: term().
+%% '''
-module(passage_reporter).
%%------------------------------------------------------------------------------
@@ -40,24 +51,30 @@
%% Exported Types
%%------------------------------------------------------------------------------
-opaque reporter() :: #?REPORTER{}.
+%% Reporter.
-type state() :: term().
+%% Implementation-dependent state.
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @doc Makes a new reporter.
-spec new(module(), state()) -> passage_reporter:reporter().
new(Module, State) ->
#?REPORTER{module = Module, state = State}.
+%% @doc Returns `true' if `X' is a reporter, otherwise `false'.
-spec is_reporter(reporter() | term()) -> boolean().
is_reporter(X) ->
is_record(X, ?REPORTER).
+%% @doc Returns the module of `Reporter'.
-spec get_module(reporter()) -> module().
get_module(Reporter) ->
Reporter#?REPORTER.module.
+%% @doc Returns the state of `Reporter'.
-spec get_state(reporter()) -> state().
get_state(Reporter) ->
Reporter#?REPORTER.state.
diff --git a/src/passage_reporter_null.erl b/src/passage_reporter_null.erl
index f7cd241..b6217f3 100644
--- a/src/passage_reporter_null.erl
+++ b/src/passage_reporter_null.erl
@@ -1,7 +1,18 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc Null Reporter.
%%
+%% This reporter discards all the spans.
+%%
+%% === Examples ===
+%%
+%% ```
+%% Context = passage_span_context_null,
+%% Sampler = passage_sampler_null:new(),
+%% Reporter = passage_reporter_null:new(),
+%%
+%% ok = passage_tracer_registry:register(foo, Context, Sampler, Reporter).
+%% '''
-module(passage_reporter_null).
-behaviour(passage_reporter).
@@ -19,6 +30,7 @@
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @doc Makes a new reporter.
-spec new() -> passage_reporter:reporter().
new() ->
passage_reporter:new(?MODULE, undefined).
@@ -26,5 +38,6 @@
%%------------------------------------------------------------------------------
%% 'passage_reporter' Callback Functions
%%------------------------------------------------------------------------------
-report(_, _) ->
+%% @private
+report(_State, _Span) ->
ok.
diff --git a/src/passage_reporter_process.erl b/src/passage_reporter_process.erl
index 7de173b..02ab69a 100644
--- a/src/passage_reporter_process.erl
+++ b/src/passage_reporter_process.erl
@@ -1,7 +1,28 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc Process Reporter.
%%
+%% This reporter will send the finished spans to a process.
+%%
+%% === Examples ===
+%%
+%% ```
+%% %% Registers `tracer'
+%% Context = passage_span_context_null,
+%% Sampler = passage_sampler_all:new(),
+%% Reporter = passage_reporter_process:new(self(), span),
+%% ok = passage_tracer_registry:register(tracer, Context, Sampler, Reporter),
+%%
+%% %% Starts and finishes a span
+%% Span = passage:start_span(example, tracer),
+%% passage:finish_span(Span),
+%%
+%% %% Receives the finish span
+%% receive
+%% {span, Span} ->
+%% example = passage_span:get_operation_name(Span)
+%% end.
+%% '''
-module(passage_reporter_process).
-behaviour(passage_reporter).
@@ -19,6 +40,10 @@
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @doc Makes a new reporter.
+%%
+%% This reporter will send the finished spans to `DestinationPid'
+%% by the message `{Tag, Span}'.
-spec new(pid(), term()) -> passage_reporter:reporter().
new(DestinationPid, Tag) ->
passage_reporter:new(?MODULE, {DestinationPid, Tag}).
@@ -26,5 +51,6 @@
%%------------------------------------------------------------------------------
%% 'passage_reporter' Callback Functions
%%------------------------------------------------------------------------------
+%% @private
report({DestinationPid, Tag}, Span) ->
DestinationPid ! {Tag, Span}.
diff --git a/src/passage_sampler.erl b/src/passage_sampler.erl
index d8d5edd..ab3e2ff 100644
--- a/src/passage_sampler.erl
+++ b/src/passage_sampler.erl
@@ -1,7 +1,18 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc Span Sampler.
%%
+%% Note that this component has not been described in the
+%% <a href="https://github.com/opentracing/specification/blob/1.1/specification.md">OpenTracing Specification</a>.
+%%
+%% === Callbacks ===
+%%
+%% This module requires following callback:
+%%
+%% ```
+%% %% @doc Determines to sample the next span which has the given name and tags.
+%% -callback is_sampled(state(), passage:operation_name(), passage:tags()) -> boolean().
+%% '''
-module(passage_sampler).
%%------------------------------------------------------------------------------
@@ -23,8 +34,7 @@
%%------------------------------------------------------------------------------
%% Callback API
%%------------------------------------------------------------------------------
--callback is_sampled(state(), passage:operation_name(), passage:tags()) ->
- boolean().
+-callback is_sampled(state(), passage:operation_name(), passage:tags()) -> boolean().
%%------------------------------------------------------------------------------
%% Macros and Records
@@ -41,24 +51,32 @@
%% Exported Types
%%------------------------------------------------------------------------------
-opaque sampler() :: #?SAMPLER{}.
+%% Sampler.
-type state() :: term().
+%% Implementation-dependent state.
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @doc Makes a new sampler.
+%%
+%% Note that `Module' must be a implementation module of `passage_sampler' behaviour.
-spec new(module(), state()) -> sampler().
new(Module, State) ->
#?SAMPLER{module = Module, state = State}.
+%% @doc Returns `true' if `X' is a sampler, otherwise `false'.
-spec is_sampler(sampler() | term()) -> boolean().
is_sampler(X) ->
is_record(X, ?SAMPLER).
+%% @doc Returns the module of `Sampler'.
-spec get_module(sampler()) -> module().
get_module(Sampler) ->
Sampler#?SAMPLER.module.
+%% @doc Returns the state of `Sampler'.
-spec get_state(sampler()) -> state().
get_state(Sampler) ->
Sampler#?SAMPLER.state.
@@ -66,6 +84,7 @@
%%------------------------------------------------------------------------------
%% Application Internal Functions
%%------------------------------------------------------------------------------
+%% @private
-spec is_sampled(sampler(), passage:operation_name(), passage:tags()) -> boolean().
is_sampled(#?SAMPLER{module = Module, state = State}, Name, Tags) ->
Module:is_sampled(State, Name, Tags).
diff --git a/src/passage_sampler_all.erl b/src/passage_sampler_all.erl
index c6602d7..8733ea7 100644
--- a/src/passage_sampler_all.erl
+++ b/src/passage_sampler_all.erl
@@ -1,7 +1,18 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc All Sampler.
%%
+%% This sampler samples all the spans.
+%%
+%% === Examples ===
+%%
+%% ```
+%% Context = passage_span_context_null,
+%% Sampler = passage_sampler_all:new(),
+%% Reporter = passage_reporter_null:new(),
+%%
+%% ok = passage_tracer_registry:register(foo, Context, Sampler, Reporter).
+%% '''
-module(passage_sampler_all).
-behaviour(passage_sampler).
@@ -19,6 +30,7 @@
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @doc Makes a new sampler.
-spec new() -> passage_sampler:sampler().
new() ->
passage_sampler:new(?MODULE, undefined).
@@ -26,5 +38,6 @@
%%------------------------------------------------------------------------------
%% 'passage_sampler' Callback Functions
%%------------------------------------------------------------------------------
+%% @private
is_sampled(_State, _OperationName, _Tags) ->
true.
diff --git a/src/passage_sampler_null.erl b/src/passage_sampler_null.erl
index 76dffd7..7d36e05 100644
--- a/src/passage_sampler_null.erl
+++ b/src/passage_sampler_null.erl
@@ -1,7 +1,18 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc Null Sampler.
%%
+%% This sampler discards all the spans.
+%%
+%% === Examples ===
+%%
+%% ```
+%% Context = passage_span_context_null,
+%% Sampler = passage_sampler_null:new(),
+%% Reporter = passage_reporter_null:new(),
+%%
+%% ok = passage_tracer_registry:register(foo, Context, Sampler, Reporter).
+%% '''
-module(passage_sampler_null).
-behaviour(passage_sampler).
@@ -19,6 +30,7 @@
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @doc Makes a new sampler.
-spec new() -> passage_sampler:sampler().
new() ->
passage_sampler:new(?MODULE, undefined).
@@ -26,5 +38,6 @@
%%------------------------------------------------------------------------------
%% 'passage_sampler' Callback Functions
%%------------------------------------------------------------------------------
+%% @private
is_sampled(_State, _OperationName, _Tags) ->
false.
diff --git a/src/passage_sampler_probabilistic.erl b/src/passage_sampler_probabilistic.erl
index 2863d60..9cd1f9b 100644
--- a/src/passage_sampler_probabilistic.erl
+++ b/src/passage_sampler_probabilistic.erl
@@ -1,7 +1,18 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc Probabilistic Sampler.
%%
+%% This sampler samples the spans probabilistically.
+%%
+%% === Examples ===
+%%
+%% ```
+%% Context = passage_span_context_null,
+%% Sampler = passage_sampler_probabilistic:new(0.5),
+%% Reporter = passage_reporter_null:new(),
+%%
+%% ok = passage_tracer_registry:register(foo, Context, Sampler, Reporter).
+%% '''
-module(passage_sampler_probabilistic).
-behaviour(passage_sampler).
@@ -19,6 +30,12 @@
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @doc Makes a new sampler.
+%%
+%% This will sample spans by the given `SamplingRate'.
+%% E.g., if `SamplingRate = 0.5', the half of the spans are sampled probabilistically.
+%%
+%% The value of `SamplingRate' must be between `0.0' and `1.0'.
-spec new(float()) -> passage_sampler:sampler().
new(SamplingRate) ->
N = SamplingRate,
@@ -30,5 +47,6 @@
%%------------------------------------------------------------------------------
%% 'passage_sampler' Callback Functions
%%------------------------------------------------------------------------------
+%% @private
is_sampled(SamplingRate, _OperationName, _Tags) ->
rand:uniform() < SamplingRate.
diff --git a/src/passage_span.erl b/src/passage_span.erl
index b64e005..338f30b 100644
--- a/src/passage_span.erl
+++ b/src/passage_span.erl
@@ -1,7 +1,47 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc Span.
%%
+%% <blockquote>
+%% <b>Traces</b> in OpenTracing are defined implicitly by their <b>Spans</b>.
+%% In particular, a <b>Trace</b> can be thought of as a directed acyclic graph (DAG) of <b>Spans</b>,
+%% where the edges between <b>Spans</b> are called <b>References</b>.
+%%
+%% Each <b>Span</b> encapsulates the following state:
+%% <ul>
+%% <li>An operation name</li>
+%% <li>A start timestamp</li>
+%% <li>A finish timestamp</li>
+%% <li>A set of zero or more key:value <b>Span Tags</b>. The keys must be strings. The values may be strings, bools, or numeric types.</li>
+%% <li>A set of zero or more <b>Span Logs</b>, each of which is itself a key:value map paired with a timestamp. The keys must be strings, though the values may be of any type. Not all OpenTracing implementations must support every value type.</li>
+%% <li>A <b>SpanContext</b></li>
+%% <li><b>References</b> to zero or more causally-related <b>Spans</b> (via the <b>SpanContext</b> of those related <b>Spans</b>)</li>
+%% </ul>
+%%
+%% <a href="https://github.com/opentracing/specification/blob/1.1/specification.md#the-opentracing-data-model">
+%% The OpenTracing Data Model
+%% </a>
+%% </blockquote>
+%%
+%% === Examples ===
+%%
+%% ```
+%% %% Registers a tracer
+%% Context = passage_span_context_null,
+%% Sampler = passage_sampler_all:new(),
+%% Reporter = passage_reporter_null:new(),
+%% ok = passage_tracer_registry:register(tracer, Context, Sampler, Reporter),
+%%
+%% %% Starts a span
+%% MaybeSpan = passage:start_root_span(example, tracer),
+%% case MaybeSpan of
+%% undefined -> ok;
+%% Span -> example = passage_span:get_operation_name(Span)
+%% end,
+%%
+%% %% Finishes a span
+%% passage:finish_span(MaybeSpan).
+%% '''
-module(passage_span).
-include("opentracing.hrl").
@@ -13,6 +53,8 @@
-export([get_tags/1]).
-export([get_refs/1]).
-export([get_logs/1]).
+-export([get_start_time/1]).
+-export([get_finish_time/1]).
-export([get_context/1]).
-export_type([span/0]).
@@ -39,46 +81,74 @@
-record(?SPAN,
{
- tracer :: passage:tracer_id(),
- operation_name :: passage:operation_name(),
- start_time :: erlang:timestamp(),
+ tracer :: passage:tracer_id(),
+ operation_name :: passage:operation_name(),
+ start_time :: erlang:timestamp(),
finish_time = undefined :: erlang:timestamp() | undefined,
- refs = [] :: normalized_refs(),
- tags = #{} :: passage:tags(),
- logs = [] :: [log()],
- context :: passage_span_context:context()
+ refs = [] :: normalized_refs(),
+ tags = #{} :: passage:tags(),
+ logs = [] :: [log()],
+ context :: passage_span_context:context()
}).
%%------------------------------------------------------------------------------
%% Exported Types
%%------------------------------------------------------------------------------
-opaque span() :: #?SPAN{}.
+%% Span.
-type normalized_refs() :: [normalized_ref()].
+%% Normalized span references.
+%%
+%% Unlike `passage:refs/0', this cannot contain unsampled (i.e., `undefined') spans.
-type normalized_ref() :: {passage:ref_type(), span()}.
+%% Normalized span reference.
+%%
+%% Note that the values of tags, references and logs are set to empty
+%% when the span is created.
-type log() :: {passage:log_fields(), erlang:timestamp()}.
+%% Timestamped span log fields.
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @doc Returns the operation name of `Span'.
-spec get_operation_name(span()) -> passage:operation_name().
get_operation_name(Span) ->
Span#?SPAN.operation_name.
+%% @doc Returns the tags of `Span'.
-spec get_tags(span()) -> passage:tags().
get_tags(Span) ->
Span#?SPAN.tags.
+%% @doc Returns the references of `Span'.
-spec get_refs(span()) -> normalized_refs().
get_refs(Span) ->
Span#?SPAN.refs.
+%% @doc Returns the logs of `Span'.
-spec get_logs(span()) -> [log()].
get_logs(Span) ->
Span#?SPAN.logs.
+%% @doc Returns the start time of `Span'.
+-spec get_start_time(span()) -> erlang:timestamp().
+get_start_time(Span) ->
+ Span#?SPAN.start_time.
+
+%% @doc Returns the finish time of `Span'.
+%%
+%% If the span has not been finished, it will return `error'.
+-spec get_finish_time(Span :: span()) -> {ok, erlang:timestamp()} | error.
+get_finish_time(#?SPAN{finish_time = undefined}) ->
+ error;
+get_finish_time(Span) ->
+ {ok, Span#?SPAN.finish_time}.
+
+%% @doc Returns the context of `Span'.
-spec get_context(span()) -> passage_span_context:context().
get_context(Span) ->
Span#?SPAN.context.
@@ -205,7 +275,7 @@
-spec get_time([{time, erlang:timestamp()}]) -> erlang:timestamp().
get_time(Options) ->
case lists:keyfind(time, 1, Options) of
- false -> os:timestamp();
+ false -> erlang:timestamp();
{_, Time} -> Time
end.
diff --git a/src/passage_span_context.erl b/src/passage_span_context.erl
index 144a22f..df0abf1 100644
--- a/src/passage_span_context.erl
+++ b/src/passage_span_context.erl
@@ -1,7 +1,38 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc Span Context.
%%
+%% <blockquote>
+%% Each <b>SpanContext</b> encapsulates the following state: <br />
+%% <ul>
+%% <li>Any OpenTracing-implementation-dependent state (for example, trace and span ids)
+%% needed to refer to a distinct <b>Span</b> across a process boundary</li>
+%% <li><b>Baggage Items</b>, which are just key:value pairs that
+%% cross process boundaries</li>
+%% </ul>
+%% <a href="https://github.com/opentracing/specification/blob/1.1/specification.md#the-opentracing-data-model">The OpenTracing Data Model</a>
+%% </blockquote>
+%%
+%% === Callbacks ===
+%%
+%% This module requires following callbacks:
+%%
+%% ```
+%% %% @doc Creates the state of a span context from the given references.
+%% -callback make_span_context_state(passage_span:normalized_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.
+%%
+%% '''
-module(passage_span_context).
%%------------------------------------------------------------------------------
@@ -31,7 +62,8 @@
-callback inject_span_context(context(), format(), inject_fun(), carrier()) -> carrier().
--callback extract_span_context(format(), iterate_fun(), carrier()) -> {ok, context()} | error.
+-callback extract_span_context(format(), iterate_fun(), carrier()) ->
+ {ok, context()} | error.
%%------------------------------------------------------------------------------
%% Macros & Records
@@ -48,27 +80,59 @@
%% Exported Types
%%------------------------------------------------------------------------------
-opaque context() :: #?CONTEXT{}.
+%% Span context.
-type implementation_module() :: module().
+%% Implementation module of this behaviour.
-type state() :: term().
+%% Implementation-dependent state.
-type format() :: text_map | http_header | binary.
+%% The standard injection/extraction format.
+%%
+%% <blockquote>
+%% Both injection and extraction rely on an extensible <b>format</b> parameter
+%% that dictates the type of the associated "carrier" as well as
+%% how a `SpanContext' is encoded in that carrier.
+%% All of the following <b>format</b>s must be supported by all Tracer implementations.
+%% <ul>
+%% <li><b>Text Map</b>: an arbitrary string-to-string map with an unrestricted character set for both keys and values</li>
+%% <li><b>HTTP Headers</b>: 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.</li>
+%% <li><b>Binary</b>: a (single) arbitrary binary blob representing a `SpanContext'</li>
+%% </ul>
+%% <a href="https://github.com/opentracing/specification/blob/1.1/specification.md#note-required-formats-for-injection-and-extraction">
+%% Note: required formats for injection and extraction
+%% (The OpenTracing Semantic Specification)
+%% </a>
+%% </blockquote>
-type carrier() :: term().
+%% Carrier for propagating span contexts.
-type 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'.
-type 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'.
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @doc Returns the baggage items of `Context'.
-spec get_baggage_items(context()) -> passage:baggage_items().
get_baggage_items(Context) ->
Context#?CONTEXT.baggage_items.
+%% @doc Returns the state of `Context'.
-spec get_state(context()) -> state().
get_state(Context) ->
Context#?CONTEXT.state.
diff --git a/src/passage_span_context_null.erl b/src/passage_span_context_null.erl
index 132407b..ca038b6 100644
--- a/src/passage_span_context_null.erl
+++ b/src/passage_span_context_null.erl
@@ -1,7 +1,19 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc A null implementation of the {@link passage_span_context} behaviour.
%%
+%% Note that this implementation is provided only for testing purposes.
+%%
+%% === Examples ===
+%%
+%% ```
+%% Context = passage_span_context_null,
+%% Sampler = passage_sampler_null:new(),
+%% Reporter = passage_reporter_null:new(),
+%%
+%% ok = passage_tracer_registry:register(foo, Context, Sampler, Reporter),
+%% [foo] = passage_tracer_registry:which_tracers(),
+%% '''
-module(passage_span_context_null).
-behaviour(passage_span_context).
diff --git a/src/passage_tracer_registry.erl b/src/passage_tracer_registry.erl
index aee17fd..f26adfd 100644
--- a/src/passage_tracer_registry.erl
+++ b/src/passage_tracer_registry.erl
@@ -1,7 +1,22 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc TODO
+%% @doc Tracer Registry.
%%
+%% === Examples ===
+%%
+%% ```
+%% Context = passage_span_context_null,
+%% Sampler = passage_sampler_null:new(),
+%% Reporter = passage_reporter_null:new(),
+%%
+%% %% Registers
+%% ok = passage_tracer_registry:register(foo, Context, Sampler, Reporter),
+%% [foo] = passage_tracer_registry:which_tracers(),
+%%
+%% %% Deregisters
+%% ok = passage_tracer_registry:deregister(foo),
+%% [] = passage_tracer_registry:which_tracers()
+%% '''
-module(passage_tracer_registry).
-behavior(gen_server).
@@ -43,6 +58,7 @@
%%------------------------------------------------------------------------------
%% Application Internal Functions
%%------------------------------------------------------------------------------
+%% @private
-spec start_link() -> {ok, pid()} | {error, Reason :: term()}.
start_link() ->
gen_server:start_link({local, ?MODULE}, ?MODULE, [], []).
@@ -50,6 +66,7 @@
%%------------------------------------------------------------------------------
%% Exported Functions
%%------------------------------------------------------------------------------
+%% @doc Registers the tracer.
-spec register(Tracer, Module, Sampler, Reporter) -> ok | {error, Reason} when
Tracer :: passage:tracer_id(),
Module :: passage_span_context:implementation_module(),
@@ -65,14 +82,21 @@
gen_server:call(?MODULE, {register, {Tracer, Module, Sampler, Reporter}}).
+%% @doc Deregisters the tracer.
+%%
+%% If `Tracer' has not been registered, it will be simply ignored.
-spec deregister(passage:tracer_id()) -> ok.
deregister(Tracer) ->
gen_server:cast(?MODULE, {deregister, Tracer}).
+%% @doc Returns the list of the registered tracers.
-spec which_tracers() -> [passage:tracer_id()].
which_tracers() ->
gen_server:call(?MODULE, which_tracers).
+%% @doc Returns the `passage_span_context' implementation module associated with `Tracer'.
+%%
+%% If `Tracer' has not been registered, it will return `error'.
-spec get_span_context_module(passage:tracer_id()) -> {ok, Module} | error when
Module :: passage_span_context:implementation_module().
get_span_context_module(Tracer) ->
@@ -81,6 +105,9 @@
_ -> error
end.
+%% @doc Returns the sampler associated with `Tracer'.
+%%
+%% If `Tracer' has not been registered, it will return `error'.
-spec get_sampler(passage:tracer_id()) -> {ok, passage_sampler:sampler()} | error.
get_sampler(Tracer) ->
case ets:lookup(?TABLE, {sampler, Tracer}) of
@@ -88,10 +115,16 @@
_ -> error
end.
+%% @doc Updates the sampler associated with `Tracer' to `Sampler'.
+%%
+%% If `Tracer' has not been registered, it will be simply ignored.
-spec set_sampler(passage:tracer_id(), passage_sampler:sampler()) -> ok.
set_sampler(Tracer, Sampler) ->
gen_server:cast(?MODULE, {set_sampler, {Tracer, Sampler}}).
+%% @doc Returns the reporter associated with `Tracer'.
+%%
+%% If `Tracer' has not been registered, it will return `error'.
-spec get_reporter(passage:tracer_id()) -> {ok, passage_reporter:reporter()} | error.
get_reporter(TracerId) ->
case ets:lookup(?TABLE, {reporter, TracerId}) of
@@ -99,6 +132,9 @@
_ -> error
end.
+%% @doc Updates the reporter associated with `Tracer' to `Reporter'.
+%%
+%% If `Tracer' has not been registered, it will be simply ignored.
-spec set_reporter(passage:tracer_id(), passage_reporter:reporter()) -> ok.
set_reporter(Tracer, Reporter) ->
gen_server:cast(?MODULE, {set_reporter, {Tracer, Reporter}}).
@@ -106,11 +142,13 @@
%%------------------------------------------------------------------------------
%% 'gen_server' Callback Functions
%%------------------------------------------------------------------------------
+%% @private
init([]) ->
_ = ets:new(?MODULE, [named_table, protected, {read_concurrency, true}]),
State = #?STATE{},
{ok, State}.
+%% @private
handle_call({register, Args}, _From, State) ->
handle_register(Args, State);
handle_call(which_tracers, _From, State) ->
@@ -118,6 +156,7 @@
handle_call(_Request, _From, State) ->
{noreply, State}.
+%% @private
handle_cast({deregister, Args}, State) ->
handle_deregister(Args, State);
handle_cast({set_sampler, Args}, State) ->
@@ -127,12 +166,15 @@
handle_cast(_Request, State) ->
{noreply, State}.
+%% @private
handle_info(_Info, State) ->
{noreply, State}.
+%% @private
terminate(_Reason, _State) ->
ok.
+%% @private
code_change(_OldVsn, State, _Extra) ->
{ok, State}.
