Merge branch 'main' into al/document-samplers

Author: whatyouhide

apps/opentelemetry/src/otel_batch_processor.erl

@@ -437,18 +437,18 @@ completed(FromPid) ->
 
 export(undefined, _, _) ->
     true;
-export({ExporterModule, Config}, Resource, SpansTid) ->
+export(Exporter, Resource, SpansTid) ->
     %% don't let a exporter exception crash us
     %% and return true if exporter failed
     try
-        otel_exporter:export_traces(ExporterModule, SpansTid, Resource, Config) =:= failed_not_retryable
+        otel_exporter_traces:export(Exporter, SpansTid, Resource) =:= failed_not_retryable
     catch
         Kind:Reason:StackTrace ->
             ?LOG_INFO(#{source => exporter,
                         during => export,
                         kind => Kind,
                         reason => Reason,
-                        exporter => ExporterModule,
+                        exporter => Exporter,
                         stacktrace => StackTrace}, #{report_cb => fun ?MODULE:report_cb/1}),
             true
     end.
@@ -459,7 +459,7 @@ report_cb(#{source := exporter,
             during := export,
             kind := Kind,
             reason := Reason,
-            exporter := ExporterModule,
+            exporter := {ExporterModule, _},
             stacktrace := StackTrace}) ->
     {"span exporter threw exception: exporter=~p ~ts",
      [ExporterModule, otel_utils:format_exception(Kind, Reason, StackTrace)]}.

apps/opentelemetry/src/otel_exporter.erl

@@ -21,21 +21,25 @@
          export_traces/4,
          export_metrics/4,
          export_logs/4,
+         export_traces/3,
+         export_metrics/3,
+         export_logs/3,
          shutdown/1,
          report_cb/1]).
 
-%% Do any initialization of the exporter here and return configuration
-%% that will be passed along with a list of spans to the `export' function.
+%% Kept only for backwards compatibility. Look at `otel_exporter_traces', `otel_exporter_metrics'
+%% and `otel_exporter_logs' instead.
 -callback init(term()) -> {ok, term()} | ignore.
 
-%% This function is called when the configured interval expires with any
-%% spans that have been collected so far and the configuration returned in `init'.
-%% Do whatever needs to be done to export each span here, the caller will block
-%% until it returns.
--callback export(traces | metrics, ets:tab(), otel_resource:t(), term()) -> ok |
-                                                                            success |
-                                                                            failed_not_retryable |
-                                                                            failed_retryable.
+%% Kept only for backwards compatibility. Look at `otel_exporter_traces', `otel_exporter_metrics'
+%% and `otel_exporter_logs' instead.
+-callback export(traces | logs | metrics, ets:tab(), otel_resource:t(), term()) -> ok |
+                                                                                   success |
+                                                                                   failed_not_retryable |
+                                                                                   failed_retryable.
+
+%% Kept only for backwards compatibility. Look at `otel_exporter_traces', `otel_exporter_metrics'
+%% and `otel_exporter_logs' instead.failed_retryable.
 -callback shutdown(term()) -> ok.
 
 -include_lib("kernel/include/logger.hrl").
@@ -116,6 +120,17 @@ init(Exporter) when Exporter =:= none ; Exporter =:= undefined ->
 init(ExporterModule) when is_atom(ExporterModule) ->
     init({ExporterModule, []}).
 
+export_traces({ExporterModule, Config}, SpansTid, Resource) ->
+    ExporterModule:export(traces, SpansTid, Resource, Config).
+
+export_metrics({ExporterModule, Config}, MetricsTid, Resource) ->
+    ExporterModule:export(metrics, MetricsTid, Resource, Config).
+
+export_logs({ExporterModule, Config}, Batch, Resource) ->
+    ExporterModule:export(logs, Batch, Resource, Config).
+
+%% below export_* functions are for backwards compatibility
+
 export_traces(ExporterModule, SpansTid, Resource, Config) ->
     ExporterModule:export(traces, SpansTid, Resource, Config).
 

apps/opentelemetry/src/otel_exporter_pid.erl

@@ -17,16 +17,16 @@
 %%%-----------------------------------------------------------------------
 -module(otel_exporter_pid).
 
--behaviour(otel_exporter).
+-behaviour(otel_exporter_traces).
 
 -export([init/1,
-         export/4,
+         export/3,
          shutdown/1]).
 
 init(Pid) ->
     {ok, Pid}.
 
-export(traces, SpansTid, _Resource, Pid) ->
+export(SpansTid, _Resource, Pid) ->
     ets:foldl(fun(Span, _Acc) ->
                       Pid ! {span, Span}
               end, [], SpansTid),

apps/opentelemetry/src/otel_exporter_stdout.erl

@@ -17,16 +17,16 @@
 %%%-----------------------------------------------------------------------
 -module(otel_exporter_stdout).
 
--behaviour(otel_exporter).
+-behaviour(otel_exporter_traces).
 
 -export([init/1,
-         export/4,
+         export/3,
          shutdown/1]).
 
 init(_) ->
     {ok, []}.
 
-export(_, SpansTid, _Resource, _) ->
+export(SpansTid, _Resource, _) ->
     io:format("*SPANS FOR DEBUG*~n"),
     ets:foldl(fun(Span, _Acc) ->
                       io:format("~p~n", [Span])

apps/opentelemetry/src/otel_exporter_tab.erl

@@ -17,16 +17,16 @@
 %%%-----------------------------------------------------------------------
 -module(otel_exporter_tab).
 
--behaviour(otel_exporter).
+-behaviour(otel_exporter_traces).
 
 -export([init/1,
-         export/4,
+         export/3,
          shutdown/1]).
 
 init(Tid) ->
     {ok, Tid}.
 
-export(traces, SpansTid, _Resource, Tid) ->
+export(SpansTid, _Resource, Tid) ->
     ets:foldl(fun(Span, _Acc) ->
                       ets:insert(Tid, Span)
               end, [], SpansTid),

apps/opentelemetry/src/otel_exporter_traces.erl

@@ -0,0 +1,45 @@
+%%%------------------------------------------------------------------------
+%% Copyright 2019, OpenTelemetry Authors
+%% Licensed under the Apache License, Version 2.0 (the "License");
+%% you may not use this file except in compliance with the License.
+%% You may obtain a copy of the License at
+%%
+%% http://www.apache.org/licenses/LICENSE-2.0
+%%
+%% Unless required by applicable law or agreed to in writing, software
+%% distributed under the License is distributed on an "AS IS" BASIS,
+%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+%% See the License for the specific language governing permissions and
+%% limitations under the License.
+%%
+%% @doc
+%% @end
+%%%-----------------------------------------------------------------------
+-module(otel_exporter_traces).
+
+-export([init/1,
+         export/3,
+         shutdown/1]).
+
+%% Do any initialization of the exporter here and return configuration
+%% that will be passed along with a list of spans to the `export' function.
+-callback init(term()) -> {ok, term()} | ignore.
+
+%% This function is called when the configured interval expires with any
+%% spans that have been collected so far and the configuration returned in `init'.
+%% Do whatever needs to be done to export each span here, the caller will block
+%% until it returns.
+-callback export(ets:tab(), otel_resource:t(), term()) -> ok |
+                                                          success |
+                                                          failed_not_retryable |
+                                                          failed_retryable.
+-callback shutdown(term()) -> ok.
+
+init(Opts) ->
+    otel_exporter:init(Opts).
+
+export({ExporterModule, Config}, Metrics, Resource) ->
+    ExporterModule:export(Metrics, Resource, Config).
+
+shutdown(Exporter) ->
+    otel_exporter:shutdown(Exporter).

apps/opentelemetry/src/otel_simple_processor.erl

@@ -241,18 +241,18 @@ completed(FromPid) ->
 
 export(undefined, _, _) ->
     true;
-export({ExporterModule, Config}, Resource, SpansTid) ->
+export(Exporter, Resource, SpansTid) ->
     %% don't let a exporter exception crash us
     %% and return true if exporter failed
     try
-        otel_exporter:export_traces(ExporterModule, SpansTid, Resource, Config) =:= failed_not_retryable
+        otel_exporter_traces:export(Exporter, SpansTid, Resource) =:= failed_not_retryable
     catch
         Kind:Reason:StackTrace ->
             ?LOG_INFO(#{source => exporter,
                         during => export,
                         kind => Kind,
                         reason => Reason,
-                        exporter => ExporterModule,
+                        exporter => Exporter,
                         stacktrace => StackTrace}, #{report_cb => fun ?MODULE:report_cb/1}),
             true
     end.
@@ -263,7 +263,7 @@ report_cb(#{source := exporter,
             during := export,
             kind := Kind,
             reason := Reason,
-            exporter := ExporterModule,
+            exporter := {ExporterModule, _},
             stacktrace := StackTrace}) ->
     {"exporter threw exception: exporter=~p ~ts",
      [ExporterModule, otel_utils:format_exception(Kind, Reason, StackTrace)]}.

apps/opentelemetry_api/src/opentelemetry.erl

@@ -343,9 +343,11 @@ convert_timestamp(Timestamp, Unit) ->
     Offset = erlang:time_offset(),
     erlang:convert_time_unit(Timestamp + Offset, native, Unit).
 
--spec links([{TraceId, SpanId, Attributes, TraceState} | span_ctx() | {span_ctx(), Attributes}]) -> [link()] when
-      TraceId :: trace_id(),
-      SpanId :: span_id(),
+%% @doc Creates a list of Span links from the given `List'.
+%%
+%% This is equivalent to calling {@link link/2} or {@link link/4} multiple times.
+-spec links([TraceIdAndSpanId | span_ctx() | {span_ctx(), Attributes}]) -> [link()] when
+      TraceIdAndSpanId :: {trace_id(), span_id(), Attributes, TraceState},
       Attributes :: attributes_map(),
       TraceState :: otel_tracestate:t() | [{string(), string()}].
 links(List) when is_list(List) ->
@@ -368,18 +370,26 @@ links(List) when is_list(List) ->
 links(_) ->
     [].
 
+
+%% @equiv link(SpanCtx, [])
 -spec link(span_ctx() | undefined) -> link() | undefined.
 link(SpanCtx) ->
     link(SpanCtx, []).
 
+%% @doc Creates a Span link to the Span represented by the given `SpanCtx'.
+%%
+%% The returned link can be used in the `links' field of a Span.
 -spec link(span_ctx() | undefined, attributes_map()) -> link() | undefined.
-link(#span_ctx{trace_id=TraceId,
-               span_id=SpanId,
-               tracestate=TraceState}, Attributes) ->
+link(_SpanCtx = #span_ctx{trace_id=TraceId,
+                          span_id=SpanId,
+                          tracestate=TraceState}, Attributes) ->
     ?MODULE:link(TraceId, SpanId, otel_attributes:process_attributes(Attributes), TraceState);
 link(_, _) ->
     undefined.
 
+%% @doc Creates a Span link to the Span represented by the given `TraceId' and `SpanId'.
+%%
+%% The returned link can be used in the `links' field of a Span.
 -spec link(TraceId, SpanId, Attributes, TraceState) -> link() | undefined when
       TraceId :: trace_id(),
       SpanId :: span_id(),
@@ -395,12 +405,18 @@ link(TraceId, SpanId, Attributes, TraceState) when is_integer(TraceId),
 link(_, _, _, _) ->
     undefined.
 
+%% @equiv event(opentelemetry:timestamp(), Name, Attributes)
 -spec event(Name, Attributes) -> event() | undefined when
       Name :: event_name(),
       Attributes :: attributes_map().
 event(Name, Attributes) ->
     event(opentelemetry:timestamp(), Name, Attributes).
 
+%% @doc Creates a Span event with the given `Name' and `Attributes'.
+%%
+%% The Span event is marked to have happened at `Timestamp'. The returned
+%% event can be used to add an event to a Span through {@link otel_span:add_events/2},
+%% for example.
 -spec event(Timestamp, Name, Attributes) -> event() | undefined when
       Timestamp :: integer(),
       Name :: event_name(),
@@ -419,7 +435,16 @@ event(Timestamp, Name, Attributes) when is_integer(Timestamp),
 event(_, _, _) ->
     undefined.
 
-events(List) ->
+%% @doc Creates a list of Span events from the given `List'.
+%%
+%% This is a conveneince function to create a list of Span events from a list
+%% of `{Time, Name, Attributes}' or `{Name, Attributes}' tuples. It's equivalent
+%% to calling {@link event/2} or {@link event/3} multiple times. This function
+%% also automatically filters out any invalid tuple.
+-spec events([Event]) -> [event()] when
+      Event :: {Timestamp :: integer(), event_name(), attributes_map()} |
+               {event_name(), attributes_map()}.
+events(Events) ->
     Now = opentelemetry:timestamp(),
     lists:filtermap(fun({Time, Name, Attributes}) ->
                             case event(Time, Name, Attributes) of
@@ -437,13 +462,21 @@ events(List) ->
                             end;
                        (_) ->
                             false
-                    end, List).
+                    end, Events).
 
+%% @doc Create a Span status from the given `Code'.
+%%
+%% The returned status can be used to set the status of a Span through
+%% {@link otel_span:set_status/2}, for example.
 -spec status(Code) -> status() | undefined when
       Code :: status_code().
 status(Code) ->
     status(Code, <<>>).
 
+%% @doc Create a Span status from the given `Code' and with the given `Message'.
+%%
+%% The returned status can be used to set the status of a Span through
+%% {@link otel_span:set_status/2}, for example.
 -spec status(Code, Message) -> status() | undefined when
       Code :: status_code(),
       Message :: unicode:unicode_binary().
@@ -458,6 +491,7 @@ status(_, _) ->
 
 %% internal functions
 
+%% @private
 -spec verify_and_set_term(module() | {module(), term()}, term(), atom()) -> boolean().
 verify_and_set_term(Module, TermKey, Behaviour) ->
     case verify_module_exists(Module) of
@@ -471,6 +505,7 @@ verify_and_set_term(Module, TermKey, Behaviour) ->
             false
     end.
 
+%% @private
 -spec verify_module_exists(module() | {module(), term()}) -> boolean().
 verify_module_exists({Module, _}) ->
     verify_module_exists(Module);
@@ -486,6 +521,7 @@ verify_module_exists(Module) ->
 %% for use in a filtermap
 %% return {true, Link} if a link is returned or return false
 %% a list is supported for tracestate for backwards compatibility
+%% @private
 link_or_false(TraceId, SpanId, Attributes, TraceState) when is_list(TraceState) ->
     link_or_false(TraceId, SpanId, Attributes, otel_tracestate:new(TraceState));
 link_or_false(TraceId, SpanId, Attributes, TraceState) ->
@@ -519,6 +555,7 @@ schema_url_to_binary(_) ->
 
 %% Vsn can't be an atom or anything but a list or binary
 %% so return empty binary string if it isn't a list or binary.
+%% @private
 vsn_to_binary(Vsn) when is_binary(Vsn) ; is_list(Vsn) ->
     unicode:characters_to_binary(Vsn);
 vsn_to_binary(_) ->

apps/opentelemetry_experimental/src/otel_aggregation.erl

@@ -45,15 +45,15 @@ maybe_init_aggregate(Ctx, MetricsTab, ExemplarsTab, Stream=#stream{aggregation_m
                                                                    attribute_keys=AttributeKeys},
                      Value, Attributes) ->
     {FilteredAttributes, DroppedAttributes} = filter_attributes(AttributeKeys, Attributes),
-    case AggregationModule:aggregate(Ctx, MetricsTab, ExemplarsTab, Stream, Value, FilteredAttributes, DroppedAttributes) of
+    case AggregationModule:aggregate(Ctx, MetricsTab, ExemplarsTab, Stream, Value, term_to_binary(FilteredAttributes), DroppedAttributes) of
         true ->
             true;
         false ->
             %% entry doesn't exist, create it and rerun the aggregate function
-            Metric = AggregationModule:init(Stream, FilteredAttributes),
+            Metric = AggregationModule:init(Stream, term_to_binary(FilteredAttributes)),
             %% don't overwrite a possible concurrent measurement doing the same
             _ = ets:insert_new(MetricsTab, Metric),
-            AggregationModule:aggregate(Ctx, MetricsTab, ExemplarsTab, Stream, Value, FilteredAttributes, DroppedAttributes)
+            AggregationModule:aggregate(Ctx, MetricsTab, ExemplarsTab, Stream, Value, term_to_binary(FilteredAttributes), DroppedAttributes)
     end.
 
 filter_attributes(undefined, Attributes) ->

apps/opentelemetry_experimental/src/otel_aggregation_histogram_explicit.erl

@@ -308,7 +308,7 @@ datapoint(ExemplarReservoir, ExemplarsTab, CollectionStartTime,
     Exemplars = otel_metric_exemplar_reservoir:collect(ExemplarReservoir, ExemplarsTab, Key),
     Buckets = get_buckets(BucketCounts, Boundaries),
     #histogram_datapoint{
-       attributes=Attributes,
+       attributes=binary_to_term(Attributes),
        start_time=StartTime,
        time=CollectionStartTime,
        count=lists:sum(Buckets),
@@ -333,7 +333,7 @@ datapoint(ExemplarReservoir, ExemplarsTab, CollectionStartTime,
     Exemplars = otel_metric_exemplar_reservoir:collect(ExemplarReservoir, ExemplarsTab, Key),
     Buckets = get_buckets(BucketCounts, Boundaries),
     #histogram_datapoint{
-       attributes=Attributes,
+       attributes=binary_to_term(Attributes),
        start_time=StartTime,
        time=CollectionStartTime,
        count=lists:sum(Buckets),