Merge pull request #675 from whatyouhide/al/span-docs

Add docs to `*_processor` modules
open-telemetry · Feb 6, 2024 · a53ff15 · a53ff15
2 parents 3666088 + ce08c3c
commit a53ff15
Show file tree

Hide file tree

Showing 4 changed files with 43 additions and 7 deletions.
diff --git a/apps/opentelemetry/src/otel_batch_processor.erl b/apps/opentelemetry/src/otel_batch_processor.erl
@@ -12,14 +12,19 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc The Batch Span Processor implements the `otel_span_processor'
-%% behaviour. It stores finished Spans in a ETS table buffer and exports
+%% @doc The Batch Span Processor implements the {@link otel_span_processor}
+%% behaviour.
+%% 
+%% It stores finished Spans in a ETS table buffer and exports
 %% them on an interval or when the table reaches a maximum size.
 %%
-%% Timeouts:
-%%   exporting_timeout_ms: How long to let the exports run before killing.
-%%   check_table_size_ms: Timeout to check the size of the export table.
-%%   scheduled_delay_ms: How often to trigger running the exporters.
+%% You can configure these timeouts:
+%%
+%% <ul>
+%% <li>`exporting_timeout_ms': how long to let the exports run before killing.</li>
+%% <li>`check_table_size_ms': timeout to check the size of the export table.</li>
+%% <li>`scheduled_delay_ms': how often to trigger running the exporters.</li>
+%% </ul>
 %%
 %% The size limit of the current table where finished spans are stored can
 %% be configured with the `max_queue_size' option.
@@ -93,6 +98,8 @@ current_tab_to_list(RegName) ->
 %% require a unique name to distiguish multiple batch processors while
 %% still having a single name, instead of a possibly changing pid, to
 %% communicate with the processor
+%% @doc Starts a Batch Span Processor.
+%% @end
 -spec start_link(#{name := atom() | list()}) -> {ok, pid(), map()}.
 start_link(Config=#{name := Name}) ->
     RegisterName = ?REG_NAME(Name),
@@ -116,11 +123,13 @@ set_exporter(Name, Exporter, Options) ->
     %% eqwalizer:ignore doesn't like gen_`statem:call' returns `term()'
     gen_statem:call(?REG_NAME(Name), {set_exporter, {Exporter, Options}}).
 
+%% @private
 -spec on_start(otel_ctx:t(), opentelemetry:span(), otel_span_processor:processor_config())
               -> opentelemetry:span().
 on_start(_Ctx, Span, _) ->
     Span.
 
+%% @private
 -spec on_end(opentelemetry:span(), otel_span_processor:processor_config())
             -> true | dropped | {error, invalid_span} | {error, no_export_buffer}.
 on_end(#span{trace_flags=TraceFlags}, _) when not(?IS_SAMPLED(TraceFlags)) ->
@@ -130,10 +139,12 @@ on_end(Span=#span{}, #{reg_name := RegName}) ->
 on_end(_Span, _) ->
     {error, invalid_span}.
 
+%% @private
 -spec force_flush(#{reg_name := gen_statem:server_ref()}) -> ok.
 force_flush(#{reg_name := RegName}) ->
     gen_statem:cast(RegName, force_flush).
 
+%% @private
 init([Args=#{reg_name := RegName}]) ->
     process_flag(trap_exit, true),
 
@@ -178,9 +189,11 @@ init([Args=#{reg_name := RegName}]) ->
                      table_2=Table2,
                      reg_name=RegName}}.
 
+%% @private
 callback_mode() ->
     [state_functions, state_enter].
 
+%% @private
 idle(enter, _OldState, Data=#data{exporter=undefined,
                                   exporter_config=ExporterConfig,
                                   scheduled_delay_ms=SendInterval,
@@ -208,6 +221,7 @@ idle(EventType, Event, Data) ->
 %% receiving an `export_spans' timeout while exporting means the `ExportingTimeout'
 %% is shorter than the `SendInterval'. Postponing the event will ensure we export
 %% after
+%% @private
 exporting({timeout, export_spans}, export_spans, _) ->
     {keep_state_and_data, [postpone]};
 exporting(enter, _OldState, #data{exporter=undefined,
@@ -298,6 +312,7 @@ handle_event_(_, internal, init_exporter, Data=#data{exporter=undefined,
 handle_event_(_, _, _, _) ->
     keep_state_and_data.
 
+%% @private
 terminate(_Reason, _State, #data{exporter=Exporter,
                                  resource=Resource,
                                  reg_name=RegName}) ->
@@ -441,6 +456,7 @@ export({ExporterModule, Config}, Resource, SpansTid) ->
     end.
 
 %% logger format functions
+%% @private
 report_cb(#{source := exporter,
             during := export,
             kind := Kind,

diff --git a/apps/opentelemetry/src/otel_simple_processor.erl b/apps/opentelemetry/src/otel_simple_processor.erl
@@ -67,6 +67,8 @@
 %% require a unique name to distiguish multiple simple processors while
 %% still having a single name, instead of a possibly changing pid, to
 %% communicate with the processor
+%% @doc Starts a Simple Span Processor.
+%% @end
 -spec start_link(#{name := atom() | list()}) -> {ok, pid(), map()}.
 start_link(Config=#{name := Name}) ->
     RegisterName = ?NAME_TO_ATOM(?MODULE, Name),
@@ -90,11 +92,13 @@ set_exporter(Name, Exporter, Options) ->
     %% eqwalizer:ignore doesn't like `gen_statem:call' returns `term()'
     gen_statem:call(?REG_NAME(Name), {set_exporter, {Exporter, Options}}).
 
+%% @private
 -spec on_start(otel_ctx:t(), opentelemetry:span(), otel_span_processor:processor_config())
               -> opentelemetry:span().
 on_start(_Ctx, Span, _) ->
     Span.
 
+%% @private
 -spec on_end(opentelemetry:span(), otel_span_processor:processor_config())
             -> true | dropped | {error, invalid_span} | {error, no_export_buffer}.
 on_end(#span{trace_flags=TraceFlags}, _) when not(?IS_SAMPLED(TraceFlags)) ->
@@ -104,10 +108,12 @@ on_end(Span=#span{}, #{reg_name := RegName}) ->
 on_end(_Span, _) ->
     {error, invalid_span}.
 
+%% @private
 -spec force_flush(#{reg_name := gen_statem:server_ref()}) -> ok.
 force_flush(#{reg_name := RegName}) ->
     gen_statem:cast(RegName, force_flush).
 
+%% @private
 init([Args]) ->
     process_flag(trap_exit, true),
 
@@ -129,16 +135,19 @@ init([Args]) ->
                      exporting_timeout_ms=ExportingTimeout},
      [{next_event, internal, init_exporter}]}.
 
+%% @private
 callback_mode() ->
     state_functions.
 
+%% @private
 idle({call, From}, {export, _Span}, #data{exporter=undefined}) ->
     {keep_state_and_data, [{reply, From, dropped}]};
 idle({call, From}, {export, Span}, Data) ->
     {next_state, exporting, Data, [{next_event, internal, {export, From, Span}}]};
 idle(EventType, Event, Data) ->
     handle_event_(idle, EventType, Event, Data).
 
+%% @private
 exporting({call, _From}, {export, _}, _) ->
     {keep_state_and_data, [postpone]};
 exporting(internal, {export, From, Span}, Data=#data{exporting_timeout_ms=ExportingTimeout}) ->
@@ -175,6 +184,7 @@ handle_event_(_, {call, From}, {set_exporter, Exporter}, Data=#data{exporter=Old
 handle_event_(_, _, _, _) ->
     keep_state_and_data.
 
+%% @private
 terminate(_, _, _Data) ->
     ok.
 
@@ -250,6 +260,7 @@ export({ExporterModule, Config}, Resource, SpansTid) ->
     end.
 
 %% logger format functions
+%% @private
 report_cb(#{source := exporter,
             during := export,
             kind := Kind,

diff --git a/apps/opentelemetry/src/otel_span_processor.erl b/apps/opentelemetry/src/otel_span_processor.erl
@@ -26,15 +26,24 @@
 -callback processor_init(pid(), processor_config()) -> processor_config().
 
 -callback on_start(otel_ctx:t(), opentelemetry:span(), processor_config()) -> opentelemetry:span().
+
 -callback on_end(opentelemetry:span(), processor_config()) -> true |
                                                               dropped |
                                                               {error, invalid_span} |
                                                               {error, no_export_buffer}.
+
 -callback force_flush(processor_config()) -> ok |
                                              {error, term()}.
 
 -optional_callbacks([processor_init/2]).
 
+%% @doc Starts a span processor.
+%% 
+%% `Module' must implement the `otel_span_processor' behaviour. This function
+%% calls `Module:start_link/1' with `Config' as the argument.
+%% @end
+-spec start_link(module(), Config) -> {ok, pid(), Config} | {error, term()} when
+      Config :: processor_config().
 start_link(Module, Config) ->
     case Module:start_link(Config) of
         {ok, Pid} ->

diff --git a/apps/opentelemetry/src/otel_span_processor_sup.erl b/apps/opentelemetry/src/otel_span_processor_sup.erl
@@ -12,7 +12,7 @@
 %% See the License for the specific language governing permissions and
 %% limitations under the License.
 %%
-%% @doc
+%% @private
 %% @end
 %%%-------------------------------------------------------------------------
 -module(otel_span_processor_sup).