From d5fe7e00fcf658984b74d431e723007559365318 Mon Sep 17 00:00:00 2001 From: Andrea Leopardi Date: Mon, 22 Jan 2024 12:12:47 +0100 Subject: [PATCH] Add docs to *_processor modules --- .../src/otel_batch_processor.erl | 28 +++++++++++++++---- .../src/otel_simple_processor.erl | 11 ++++++++ .../opentelemetry/src/otel_span_processor.erl | 9 ++++++ .../src/otel_span_processor_sup.erl | 2 +- 4 files changed, 43 insertions(+), 7 deletions(-) diff --git a/apps/opentelemetry/src/otel_batch_processor.erl b/apps/opentelemetry/src/otel_batch_processor.erl index 433dea95..c18e4055 100644 --- 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: +%% +%% %% %% 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 index bb877c4b..b9a38bde 100644 --- 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,9 +135,11 @@ 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) -> @@ -139,6 +147,7 @@ idle({call, From}, {export, Span}, Data) -> 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 index 8a46a4d7..44b84052 100644 --- 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 index 93e9cc1b..dcf78ba5 100644 --- 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).