Add `jaeger_passage` module
diff --git a/src/jaeger_passage.erl b/src/jaeger_passage.erl
new file mode 100644
index 0000000..a65efdf
--- /dev/null
+++ b/src/jaeger_passage.erl
@@ -0,0 +1,91 @@
+%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
+%%
+%% @doc Utility Functions
+-module(jaeger_passage).
+
+%%------------------------------------------------------------------------------
+%% Exported API
+%%------------------------------------------------------------------------------
+-export([start_tracer/2, start_tracer/3]).
+-export([stop_tracer/1]).
+
+-export_type([start_tracer_option/0, start_tracer_options/0]).
+
+%%------------------------------------------------------------------------------
+%% Exported Types
+%%------------------------------------------------------------------------------
+-type start_tracer_options() :: [start_tracer_option()].
+%% Options for {@link start_tracer/3}.
+
+-type start_tracer_option() :: {reporter_id, jaeger_passage_reporter:reporter_id()}
+ | jaeger_passage_reporter:start_option().
+%% <ul>
+%% <li><b>reporter_id</b>: In {@link start_tracer/3} function, it starts a reporter with this identifier. The default value is `Tracer'.</li>
+%% </ul>
+
+%%------------------------------------------------------------------------------
+%% Exported Functions
+%%------------------------------------------------------------------------------
+%% @equiv start_tracer(TracerId, Sampler, [])
+-spec start_tracer(Tracer, Sampler) -> ok | {error, Reason :: term()} when
+ Tracer :: passage:tracer_id(),
+ Sampler :: passage_sampler:sampler().
+start_tracer(Tracer, Sampler) ->
+ start_tracer(Tracer, Sampler, []).
+
+%% @doc Starts a tracer for Jaeger.
+%%
+%% This function also starts a reporter for the jaeger agent.
+%%
+%% Conceptually this is equivalent to the following code:
+%%
+%% ```
+%% ReporterId = proplists:get_value(reporter_id, Options, Tracer),
+%% Context = jaeger_passage_span_context,
+%% {ok, Reporter} = jaeger_passage_reporter:start(ReporterId, Options),
+%% passage_tracer_registry:register(Tracer, Context, Sampler, Reporter).
+%% '''
+%%
+%% === Examples ===
+%%
+%% ```
+%% %% Starts `test_tracer'
+%% Sampler = passage_sampler_all:new().
+%% ok = jaeger_passage:start_tracer(example_tracer, Sampler).
+%%
+%% [example_tracer] = passage_tracer_registry:which_tracers().
+%% [example_tracer] = jaeger_passage_reporter:which_reporters().
+%%
+%% %% Starts and finishes spans
+%% passage_pd:start_root_span(example_span, example_tracer).
+%% passage_pd:error_log("Hello World").
+%% passage_pd:finish_span().
+%%
+%% %% Stops `example_tracer'
+%% ok = jaeger_passage:stop_tracer(example_tracer).
+%% [] = passage_tracer_registry:which_tracers().
+%% [] = jaeger_passage_reporter:which_reporters().
+%% '''
+-spec start_tracer(Tracer, Sampler, Options) -> ok | {error, Reason :: term()} when
+ Tracer :: passage:tracer_id(),
+ Sampler :: passage_sampler:sampler(),
+ Options :: start_tracer_options().
+start_tracer(Tracer, Sampler, Options) ->
+ ReporterId = proplists:get_value(reporter_id, Options, Tracer),
+ Context = jaeger_passage_span_context,
+ case jaeger_passage_reporter:start(ReporterId, Options) of
+ {error, Reason} -> {error, Reason};
+ {ok, Reporter} ->
+ passage_tracer_registry:register(Tracer, Context, Sampler, Reporter)
+ end.
+
+%% @doc Stops the tracer which has been started by {@link start_tracer/3}.
+-spec stop_tracer(passage:tracer_id()) -> ok.
+stop_tracer(Tracer) ->
+ case passage_tracer_registry:get_reporter(Tracer) of
+ error -> ok;
+ {ok, Reporter} ->
+ ReporterId = jaeger_passage_reporter:get_id(Reporter),
+ jaeger_passage_reporter:stop(ReporterId),
+ passage_tracer_registry:deregister(Tracer)
+ end.
diff --git a/src/jaeger_passage_reporter.erl b/src/jaeger_passage_reporter.erl
index adf97e1..98f8ffb 100644
--- a/src/jaeger_passage_reporter.erl
+++ b/src/jaeger_passage_reporter.erl
@@ -39,6 +39,7 @@
-export([start/1, start/2]).
-export([stop/1]).
-export([which_reporters/0]).
+-export([get_id/1]).
-export_type([reporter_id/0]).
-export_type([start_option/0, start_options/0]).
@@ -141,6 +142,15 @@
which_reporters() ->
jaeger_passage_reporter_sup:which_children().
+%% @doc Returns the identifier of `Reporter'.
+%%
+%% Note that if `Reporter' is one which has not been created by {@link start/2},
+%% this function will crash.
+-spec get_id(passage_reporter:reporter()) -> reporter_id().
+get_id(Reporter) ->
+ ?MODULE = passage_reporter:get_module(Reporter),
+ passage_reporter:get_state(Reporter).
+
%%------------------------------------------------------------------------------
%% 'passage_reporter' Callback Functions
%%------------------------------------------------------------------------------
diff --git a/test/jaeger_passage_tests.erl b/test/jaeger_passage_tests.erl
new file mode 100644
index 0000000..93ed769
--- /dev/null
+++ b/test/jaeger_passage_tests.erl
@@ -0,0 +1,32 @@
+%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
+-module(jaeger_passage_tests).
+
+-include_lib("eunit/include/eunit.hrl").
+
+%%------------------------------------------------------------------------------
+%% Test Cases
+%%------------------------------------------------------------------------------
+basic_test() ->
+ {ok, _} = application:ensure_all_started(jaeger_passage),
+
+ %% Starts `test_tracer'
+ Sampler = passage_sampler_all:new(),
+ ok = jaeger_passage:start_tracer(test_tracer, Sampler),
+
+ [test_tracer] = passage_tracer_registry:which_tracers(),
+ [test_tracer] = jaeger_passage_reporter:which_reporters(),
+
+ %% Starts and finishes spans
+ passage_pd:start_root_span(test_root, test_tracer),
+ passage_pd:start_span(test_child),
+ passage_pd:error_log("Hello World"),
+ passage_pd:finish_span(),
+ passage_pd:finish_span(),
+ timer:sleep(50),
+
+ %% Stops `test_tracer'
+ ok = jaeger_passage:stop_tracer(test_tracer),
+ [] = passage_tracer_registry:which_tracers(),
+ [] = jaeger_passage_reporter:which_reporters(),
+
+ ok = application:stop(jaeger_passage).
