Skip to content

Commit

Permalink
Add documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@sile
sile committed Oct 23, 2017
1 parent b13e08a commit bad0d01
Show file tree
Hide file tree
Showing 8 changed files with 254 additions and 92 deletions.
42 changes: 42 additions & 0 deletions doc/overview.edoc
View file
@@ -0,0 +1,42 @@
@copyright 2017 Takeru Ohta <phjgt308@gmail.com>

@doc Jaeger client library for Erlang

This is an extention of <a href="https://github.com/sile/passage">passage</a>(An OpenTracing library).

=== Examples ===

```
// Starts Jaeger in the background
$ docker run -d -p6831:6831/udp -p6832:6832/udp -p16686:16686 jaegertracing/all-in-one:latest

// Starts Erlang Shell
$ rebar3 shell
> Context = jaeger_passage_span_context.
> Sampler = passage_sampler_all:new().
> {ok, Reporter} = jaeger_passage_reporter:start(example_repoter).
> ok = passage_tracer_registry:register(example_tracer, Context, Sampler, Reporter).

%% Starts a root span.
> RootSpan = passage:start_root_span(example_root, example_tracer).

%% Starts a child span.
> ChildSpan = passage:start_span(example_child, {child_of, RootSpan}).

%% Finishes the spans
> passage:finish_span(ChildSpan).
> passage:finish_span(RootSpan).

> q().

// Browses the tracing result
$ firefox localhost:16686
'''

=== References ===

<ul>
<li><a href="http://opentracing.io/">OpenTracing</a></li>
<li><a href="https://uber.github.io/jaeger/">Jaeger</a></li>
<li><a href="https://github.com/jaegertracing/jaeger-client-go/blob/v2.9.0/README.md">jaeger-client-go/README.md</a></li>
</ul>
9 changes: 9 additions & 0 deletions src/jaeger_passage_app.erl
View file
@@ -1,9 +1,18 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
%% @private
-module(jaeger_passage_app).

-behaviour(application).

%%------------------------------------------------------------------------------
%% 'application' Callback API
%%------------------------------------------------------------------------------
-export([start/2, stop/1]).

%%------------------------------------------------------------------------------
%% 'application' Callback Functions
%%------------------------------------------------------------------------------
start(_StartType, _StartArgs) ->
jaeger_passage_sup:start_link().

Expand Down
11 changes: 11 additions & 0 deletions src/jaeger_passage_local_ns.erl
View file
@@ -1,8 +1,19 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
%% @doc Application Local Name Server
%%
%% @private
-module(jaeger_passage_local_ns).

%%------------------------------------------------------------------------------
%% Application Internal API
%%------------------------------------------------------------------------------
-export([child_spec/0]).
-export([reporter_name/1]).

%%------------------------------------------------------------------------------
%% Application Internal Functions
%%------------------------------------------------------------------------------
-spec child_spec() -> supervisor:child_spec().
child_spec() ->
local:name_server_child_spec(?MODULE).
Expand Down
51 changes: 50 additions & 1 deletion src/jaeger_passage_reporter.erl
View file
@@ -1,3 +1,31 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
%% @doc A reporter that sends the spans to an jaeger agent
%%
%% === Examples ===
%%
%% ```
%% %% Starts `example_reporter'
%% {ok, Reporter} = jaeger_passage_reporter:start(example_reporter).
%% [example_reporter] = jaeger_passage_reporter:which_reporters().
%%
%% %% Registers `example_tracer'
%% Context = jaeger_passage_span_context.
%% Sampler = passage_sampler_all:new().
%% ok = passage_tracer_registry:register(example_tracer, Context, Sampler, Reporter).
%%
%% %% Starts and finishes a span
%% Span = passage:start_root_span(example, example_tracer).
%%
%% passage:finish_span(Span). % The span will send to the jaeger agent on the localhost
%% '''
%%
%% === Refereces ===
%%
%% <ul>
%% <li><a href="http://jaeger.readthedocs.io/en/latest/architecture/#agent">Jaeger - Architecture - Agent</a></li>
%% <li><a href="http://jaeger.readthedocs.io/en/latest/deployment/#agent">Jaeger - Deployment - Agent</a></li>
%% </ul>
-module(jaeger_passage_reporter).

-behaviour(passage_reporter).
Expand Down Expand Up @@ -49,18 +77,28 @@
%% Exported Types
%%------------------------------------------------------------------------------
-type reporter_id() :: atom().
%% Reporter identifier.

-type start_options() :: [start_option()].
%% Options for {@link start/2}.

-type start_option() :: {thrift_format, thrift_protocol:format()}
| {agent_host, inet:hostname()}
| {agent_port, inet:port_number()}
| {service_name, atom()}
| {service_tags, passage:tags()}.
%% <ul>
%% <li><b>thrift_format</b>: The format for encoding thrift messages. The default value is `compact'.</li>
%% <li><b>agent_host</b>: The hostname of the jaeger agent. The default value is `"127.0.0.1"'.</li>
%% <li><b>agent_port</b>: The port of the jaeger agent. The default values for the thrift format `compact' and `binary' are `6831' and `6832' respectively.</li>
%% <li><b>service_name</b>: The name of the service which reports the spans. The default value is `ReporterId'.</li>
%% <li><b>service_tags</b>: The tags of the service. The default value is `#{}'.</li>
%% </ul>

%%------------------------------------------------------------------------------
%% Application Internal Functions
%%------------------------------------------------------------------------------
%% @private
-spec start_link(reporter_id(), start_options()) -> {ok, pid()} | {error, Reason} when
Reason :: {already_started, pid()} | term().
start_link(ReporterId, Options) ->
Expand All @@ -76,18 +114,29 @@ start_link(ReporterId, Options) ->
start(ReporterId) ->
start(ReporterId, []).

-spec start(reporter_id(), start_options()) -> {ok, passage_reporter:reporter()} | {error, Reason} when
%% @doc Starts a reporter process.
-spec start(reporter_id(), start_options()) -> {ok, Reporter} | {error, Reason} when
Reporter :: passage_reporter:reporter(),
Reason :: {already_started, pid()} | term().
start(ReporterId, Options) ->
Args = [ReporterId, Options],
is_atom(ReporterId) orelse error(badarg, Args),
is_list(Options) orelse error(badarg, Args),

case jaeger_passage_reporter_sup:start_child(ReporterId, Options) of
{error, Reason} -> {error, Reason};
{ok, _Pid} -> {ok, passage_reporter:new(?MODULE, ReporterId)}
end.

%% @doc Stops the reporter process.
%%
%% If the reporter which has the identifier `ReporterId' has not been started,
%% it will be simply ignored.
-spec stop(reporter_id()) -> ok.
stop(ReporterId) ->
jaeger_passage_reporter_sup:stop_child(ReporterId).

%% @doc Returns the list of the running reporters.
-spec which_reporters() -> [reporter_id()].
which_reporters() ->
jaeger_passage_reporter_sup:which_children().
Expand Down
25 changes: 20 additions & 5 deletions src/jaeger_passage_reporter_sup.erl
View file
@@ -1,21 +1,33 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
%% @private
-module(jaeger_passage_reporter_sup).

-behaviour(supervisor).

%%------------------------------------------------------------------------------
%% Application Internal API
%%------------------------------------------------------------------------------
-export([start_link/0]).
-export([start_child/2]).
-export([stop_child/1]).
-export([which_children/0]).

%%------------------------------------------------------------------------------
%% 'supervisor' Callback API
%%------------------------------------------------------------------------------
-export([init/1]).

-define(SERVER, ?MODULE).

%%------------------------------------------------------------------------------
%% Application Internal Functions
%%------------------------------------------------------------------------------
-spec start_link() -> {ok, pid()} | {error, Reason :: term()}.
start_link() ->
supervisor:start_link({local, ?SERVER}, ?MODULE, []).
supervisor:start_link({local, ?MODULE}, ?MODULE, []).

-spec start_child(jaeger_passage_reporter:reporter_id(), jaeger_passage_reporter:start_options()) ->
{ok, pid()} | {error, Reason} when
-spec start_child(ReporterId, Options) -> {ok, pid()} | {error, Reason} when
ReporterId :: jaeger_passage_reporter:reporter_id(),
Options :: jaeger_passage_reporter:start_options(),
Reason :: {already_started, pid()} | term().
start_child(ReporterId, Options) ->
Child = #{
Expand All @@ -35,5 +47,8 @@ stop_child(ReporterId) ->
which_children() ->
[Id || {Id, _, _, _} <- supervisor:which_children(?MODULE)].

%%------------------------------------------------------------------------------
%% 'supervisor' Callback Functions
%%------------------------------------------------------------------------------
init([]) ->
{ok, {#{}, []}}.
51 changes: 41 additions & 10 deletions src/jaeger_passage_span_context.erl
View file
@@ -1,3 +1,15 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
%% @doc Span context for Jaeger
%%
%% === References ===
%%
%% <ul>
%% <li><a href="https://github.com/jaegertracing/jaeger-client-go/blob/v2.9.0/README.md">jaeger-client-go/README.md</a></li>
%% <li><a href="https://github.com/uber/jaeger-client-go/tree/v2.9.0/context.go">context.go</a></li>
%% <li><a href="https://github.com/uber/jaeger-client-go/tree/v2.9.0/propagation.go">propagation.go</a></li>
%% </ul>

-module(jaeger_passage_span_context).

-behaviour(passage_span_context).
Expand All @@ -7,15 +19,16 @@
%%------------------------------------------------------------------------------
%% Exported API
%%------------------------------------------------------------------------------
-export_type([state/0]).

%%------------------------------------------------------------------------------
%% Application Internal API
%%------------------------------------------------------------------------------
-export([get_trace_id/1]).
-export([get_span_id/1]).
-export([get_debug_id/1]).
-export([get_flags/1]).

-export_type([state/0]).
-export_type([trace_id/0]).
-export_type([span_id/0]).

%%------------------------------------------------------------------------------
%% 'passage_span_context' Callback API
%%------------------------------------------------------------------------------
Expand All @@ -41,22 +54,39 @@
%% Exported Types
%%------------------------------------------------------------------------------
-opaque state() :: #?STATE{}.
%% The state of a jaeger span context.

-type trace_id() :: 0..16#FFFFFFFFFFFFFFFF.
%%------------------------------------------------------------------------------
%% Types
%%------------------------------------------------------------------------------
-type trace_id() :: 0..16#FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF.
%% Tracer identifier (128-bit unsigned integer).
%%
%% This represents globally unique ID of the trace.
%% Usually generated as a random number.

-type span_id() :: 0..16#FFFFFFFF.
-type span_id() :: 0..16#FFFFFFFFFFFFFFFF.
%% Span identifier (64-bit unsigned integer).
%%
%% This represents span ID that must be unique within its trace,
%% but does not have to be globally unique.
%%
%% Note that the ID `0' is used for representing invalid spans.

%%------------------------------------------------------------------------------
%% Exported Functions
%% Application Internal Functions
%%------------------------------------------------------------------------------
%% @private
-spec get_trace_id(passage_span_context:context()) -> trace_id().
get_trace_id(Context) ->
(passage_span_context:get_state(Context))#?STATE.trace_id.

%% @private
-spec get_span_id(passage_span_context:context()) -> span_id().
get_span_id(Context) ->
(passage_span_context:get_state(Context))#?STATE.span_id.

%% @private
-spec get_debug_id(passage_span_context:context()) -> {ok, binary()} | eror.
get_debug_id(Context) ->
State = passage_span_context:get_state(Context),
Expand All @@ -65,6 +95,7 @@ get_debug_id(Context) ->
DebugId -> {ok, DebugId}
end.

%% @private
-spec get_flags(passage_span_context:context()) -> 0..16#FFFFFFFF.
get_flags(Context) ->
State = passage_span_context:get_state(Context),
Expand All @@ -76,15 +107,15 @@ get_flags(Context) ->
%% @private
make_span_context_state([]) ->
#?STATE{
trace_id = rand:uniform(16#FFFFFFFFFFFFFFFF),
span_id = rand:uniform(16#FFFFFFFF),
trace_id = rand:uniform(16#FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF),
span_id = rand:uniform(16#FFFFFFFFFFFFFFFF),
is_sampled = true
};
make_span_context_state([{_, Ref} | _]) ->
#?STATE{trace_id = TraceId} = passage_span_context:get_state(passage_span:get_context(Ref)),
#?STATE{
trace_id = TraceId,
span_id = rand:uniform(16#FFFFFFFF),
span_id = rand:uniform(16#FFFFFFFFFFFFFFFF),
is_sampled = true
}.

Expand Down
20 changes: 17 additions & 3 deletions src/jaeger_passage_sup.erl
View file
@@ -1,16 +1,30 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
%% @private
-module(jaeger_passage_sup).

-behaviour(supervisor).

%%------------------------------------------------------------------------------
%% Application Internal API
%%------------------------------------------------------------------------------
-export([start_link/0]).

%%------------------------------------------------------------------------------
%% 'supervisor' Callback API
%%------------------------------------------------------------------------------
-export([init/1]).

-define(SERVER, ?MODULE).

%%------------------------------------------------------------------------------
%% Application Internal Functions
%%-------------------------------------------------------------------------------
-spec start_link() -> {ok, pid()} | {error, Reason :: term()}.
start_link() ->
supervisor:start_link({local, ?SERVER}, ?MODULE, []).
supervisor:start_link({local, ?MODULE}, ?MODULE, []).

%%------------------------------------------------------------------------------
%% 'supervisor' Callback Functions
%%------------------------------------------------------------------------------
init([]) ->
NameServer = jaeger_passage_local_ns:child_spec(),
ReporterSup = #{
Expand Down

0 comments on commit bad0d01

Please sign in to comment.