Update documentation
diff --git a/src/jaeger_passage_reporter.erl b/src/jaeger_passage_reporter.erl
index a2a4a68..5054ae9 100644
--- a/src/jaeger_passage_reporter.erl
+++ b/src/jaeger_passage_reporter.erl
@@ -1,6 +1,6 @@
%% @copyright 2017 Takeru Ohta <phjgt308@gmail.com>
%%
-%% @doc A reporter that sends the spans to an jaeger agent
+%% @doc A reporter that sends the spans to an jaeger agent (UDP) or collector (HTTP).
%%
%% === Examples ===
%%
@@ -57,27 +57,11 @@
-type start_options() :: [start_option()].
%% Options for {@link start/2}.
--type start_option() :: jaeger_passage_reporter_udp:start_option()
- | jaeger_passage_reporter_http:start_option()
- | {protocol, udp | http}
- | {default_service_name, atom()}
- | {process_tags, passage:tags()}.
-
-%% Common reporter options
+-type start_option() :: {protocol, udp | http}
+ | jaeger_passage_reporter_udp:start_option()
+ | jaeger_passage_reporter_http:start_option().
%% <ul>
%% <li><b>protocol</b>: Communication protocol used to connect to jaeger. The value is used to select reporter module. Possible values are: `udp' | `http'. The default value is `udp'.</li>
-%% <li><b>default_service_name</b>: The default service name. If a reporting span has `location.application' tag, the value is used as the service name instead of this. The default value is `ReporterId'.</li>
-%% <li><b>process_tags</b>: The tags of the reporting process. The default value is `#{}'.</li>
-%% </ul>
-%% UDP reporter specific options
-%% <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>
-%% </ul>
-%% HTTP reporter specific options
-%% <ul>
-%% <li><b>endpoint</b>: The jaeger endpoint URL for sending thrift messages. The default value is `http://127.0.0.1:14268'.</li>
%% </ul>
%%------------------------------------------------------------------------------
diff --git a/src/jaeger_passage_reporter_http.erl b/src/jaeger_passage_reporter_http.erl
index 0b0097c..e226d6c 100644
--- a/src/jaeger_passage_reporter_http.erl
+++ b/src/jaeger_passage_reporter_http.erl
@@ -1,4 +1,7 @@
-%% @doc A reporter that sends the spans to an jaeger agent
+%% @doc A reporter that sends the spans to an jaeger collector using HTTP.
+%%
+%% To start a reporter process, please use {@link jaeger_passage_reporter:start/1} or {@link jaeger_passage_reporter:start/2}.
+%%
%%
%% === Examples ===
%%
@@ -15,15 +18,8 @@
%% %% Starts and finishes a span
%% Span = passage:start_span(example, [{tracer, example_tracer}]).
%%
-%% passage:finish_span(Span). % The span will send to the jaeger agent on the localhost
+%% passage:finish_span(Span). % The span will send to the jaeger collector 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_http).
-behaviour(gen_server).
@@ -33,6 +29,8 @@
%%------------------------------------------------------------------------------
%% Exported API
%%------------------------------------------------------------------------------
+-export([httpc_client/5]).
+
-export_type([start_option/0, start_options/0]).
%%------------------------------------------------------------------------------
@@ -66,25 +64,28 @@
%%------------------------------------------------------------------------------
-type start_options() :: [start_option()].
-%% Options for {@link start/2}.
+%% Options for {@link jaeger_passage_reporter:start/2}.
--type start_option() :: {endpoint, string()}
+-type start_option() :: {default_service_name, atom()}
+ | {process_tags, passage:tags()}
+ | {endpoint, string()}
| {http_client, http_client()}
- | {default_service_name, atom()}
- | {process_tags, passage:tags()}.
+ | (HttpClientSpecificOption :: any()).
%% <ul>
-%% <li><b>endpoint</b>: The jaeger endpoint URL for sending thrift messages. The default value is `http://127.0.0.1:14268'.</li>
-%% <li><b>http_client</b>: The callback to call to send span to jaeger. The httpc client is used by default.</li>
%% <li><b>default_service_name</b>: The default service name. If a reporting span has `location.application' tag, the value is used as the service name instead of this. The default value is `ReporterId'.</li>
%% <li><b>process_tags</b>: The tags of the reporting process. The default value is `#{}'.</li>
+%% <li><b>endpoint</b>: The jaeger endpoint URL for sending thrift messages. The default value is `http://127.0.0.1:14268'.</li>
+%% <li><b>http_client</b>: The callback to call to send span to jaeger. {@link httpc_client/5} is used by default.</li>
%% </ul>
-%% Example of a http_client calback
+%%
+%% Example of a `http_client' calback:
+%% ```
%% Client = fun(Url, Method, Headers, Body, ReporterOptions) ->
%% User = proplists:get_value(user, ReporterOptions),
%% Password = proplists:get_value(password, ReporterOptions),
%% ibrowse:send_req(Url, Headers, Method, Body, [{basic_auth, {User, Password}}])
%% end.
-
+%% '''
-type http_client() :: fun((
Url :: string(),
@@ -93,6 +94,15 @@
Body :: string() | binary(),
ReporterOptions :: start_options()) ->
ok).
+%% Type of HTTP client.
+
+%%------------------------------------------------------------------------------
+%% Exported Functions
+%%------------------------------------------------------------------------------
+%% @doc The default HTTP client based on the standard `httpc' module.
+httpc_client(Url, Method, _Headers, Body, _ReporterOptions) ->
+ httpc:request(Method, {Url, [], "application/x-thrift", Body}, [], []),
+ ok.
%%------------------------------------------------------------------------------
%% Application Internal Functions
@@ -171,15 +181,3 @@
Headers = [?CONTENT_TYPE],
HttpClient(URI, post, Headers, Encoded, Options),
{noreply, State}.
-
--spec httpc_client(
- Url :: string(),
- Method :: post,
- Headers :: [{string(), string()}],
- Body :: string() | binary(),
- ReporterOptions :: start_options()) ->
- ok.
-
-httpc_client(Url, Method, _Headers, Body, _ReporterOptions) ->
- httpc:request(Method, {Url, [], "application/x-thrift", Body}, [], []),
- ok.
diff --git a/src/jaeger_passage_reporter_udp.erl b/src/jaeger_passage_reporter_udp.erl
index 485c258..650da52 100644
--- a/src/jaeger_passage_reporter_udp.erl
+++ b/src/jaeger_passage_reporter_udp.erl
@@ -1,4 +1,6 @@
-%% @doc A reporter that sends the spans to an jaeger agent
+%% @doc A reporter that sends the spans to an jaeger agent using UDP.
+%%
+%% To start a reporter process, please use {@link jaeger_passage_reporter:start/1} or {@link jaeger_passage_reporter:start/2}.
%%
%% === Examples ===
%%
@@ -17,13 +19,6 @@
%%
%% 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_udp).
-behaviour(gen_server).
@@ -65,17 +60,19 @@
%%------------------------------------------------------------------------------
-type start_options() :: [start_option()].
-%% Options for {@link start/2}.
+%% Options for {@link jaeger_passage_reporter:start/2}.
--type start_option() :: {thrift_format, thrift_protocol:format()}
+-type start_option() :: {default_service_name, atom()}
+ | {process_tags, passage:tags()}
+ | {thrift_format, thrift_protocol:format()}
| {agent_host, inet:hostname()}
| {agent_port, inet:port_number()}.
%% <ul>
+%% <li><b>default_service_name</b>: The default service name. If a reporting span has `location.application' tag, the value is used as the service name instead of this. The default value is `ReporterId'.</li>
+%% <li><b>process_tags</b>: The tags of the reporting process. The default value is `#{}'.</li>
%% <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>default_service_name</b>: The default service name. If a reporting span has `location.application' tag, the value is used as the service name instead of this. The default value is `ReporterId'.</li>
-%% <li><b>process_tags</b>: The tags of the reporting process. The default value is `#{}'.</li>
%% </ul>
%%------------------------------------------------------------------------------
