| %% @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()} |
| | {max_queue_len, non_neg_integer() | infinity} |
| | jaeger_passage_reporter:start_option(). |
| %% <ul> |
| %% <li>`reporter_id': In {@link start_tracer/3} function, it starts a reporter with this identifier. The default value is `Tracer'.</li> |
| %% <li>`max_queue_len': While the queue length of the reporter process exceeds this value, all new spans are rejected by the sampler. The default value is `1024'. Note that this value only affects the root spans (e.g., the child spans never be discarded by this limitation).</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, [{protocol, udp}]). |
| |
| %% @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_span(example_span, [{tracer, example_tracer}]). |
| %% passage_pd:log(#{message => "something wrong"}, [error]). |
| %% 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, Sampler0, Options) -> |
| ReporterId = proplists:get_value(reporter_id, Options, Tracer), |
| MaxQueueLen = proplists:get_value(max_queue_len, Options, 1024), |
| Context = jaeger_passage_span_context, |
| Sampler1 = |
| case MaxQueueLen of |
| infinity -> Sampler0; |
| Max -> |
| (is_integer(Max) andalso Max >= 0) orelse |
| error(badarg, [Tracer, Sampler0, Options]), |
| jaeger_passage_sampler_queue_limit:new(Sampler0, ReporterId, Max) |
| end, |
| |
| ReporterOptions = |
| lists:filter(fun ({reporter_id, _}) -> false; |
| ({max_queue_len, _}) -> false; |
| (_) -> true |
| end, |
| Options), |
| case jaeger_passage_reporter:start(ReporterId, ReporterOptions) of |
| {error, Reason} -> {error, Reason}; |
| {ok, Reporter} -> |
| passage_tracer_registry:register(Tracer, Context, Sampler1, 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. |