Skip to content
Permalink
Browse files
Add jaeger_passage module
  • Loading branch information
sile committed Oct 24, 2017
1 parent dd0a14e commit a32b90f4b6032707969fbaba6b839678c98fa473
Showing 3 changed files with 133 additions and 0 deletions.
@@ -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.
@@ -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 @@ stop(ReporterId) ->
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
%%------------------------------------------------------------------------------
@@ -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).

0 comments on commit a32b90f

Please sign in to comment.