| %% @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. |