Merge pull request #628 from albertored/advisory-parameters

Tristan Sloughter · web-flow · commit 623a1fef8e00 · 2023-10-02T04:37:39.000-06:00
Support explicit_bucket_boundaries advisory parameters
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -30,13 +30,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changes
 
 - [Allow to create observable instruments without passing callback arguments](https://github.com/open-telemetry/opentelemetry-erlang/pull/604)
+- [Allow to give `advisory_params` to instrument creation functions](https://github.com/open-telemetry/opentelemetry-erlang/pull/628)
 
 ## Experimental SDK
 
 ### Added
 
 - [Add `instrument_unit` to view criteria](https://github.com/open-telemetry/opentelemetry-erlang/pull/604)
 - [Validate instrument name](https://github.com/open-telemetry/opentelemetry-erlang/pull/604)
+- [Handle `explict_bucket_boundaries` advisory parameter](https://github.com/open-telemetry/opentelemetry-erlang/pull/628)
+- [Rename `boundaries` to `explict_bucket_boundaries` in histogram explicit aggregation options](https://github.com/open-telemetry/opentelemetry-erlang/pull/628)
 
 ### Changes
 
diff --git a/apps/opentelemetry_api_experimental/include/otel_metrics.hrl b/apps/opentelemetry_api_experimental/include/otel_metrics.hrl
@@ -1,12 +1,13 @@
--record(instrument, {module        :: module(),
-                     meter         :: otel_meter:t(),
-                     name          :: otel_instrument:name(),
-                     description   :: otel_instrument:description() | undefined,
-                     kind          :: otel_instrument:kind(),
-                     unit          :: otel_instrument:unit() | undefined,
-                     temporality   :: otel_instrument:temporality(),
-                     callback      :: otel_instrument:callback() | undefined,
-                     callback_args :: otel_instrument:callback_args() | undefined}).
+-record(instrument, {module          :: module(),
+                     meter           :: otel_meter:t(),
+                     name            :: otel_instrument:name(),
+                     description     :: otel_instrument:description() | undefined,
+                     kind            :: otel_instrument:kind(),
+                     unit            :: otel_instrument:unit() | undefined,
+                     temporality     :: otel_instrument:temporality(),
+                     callback        :: otel_instrument:callback() | undefined,
+                     callback_args   :: otel_instrument:callback_args() | undefined,
+                     advisory_params :: otel_instrument:advisory_params() | undefined}).
 
 -define(TEMPORALITY_DELTA, temporality_delta).
 -define(TEMPORALITY_CUMULATIVE, temporality_cumulative).
diff --git a/apps/opentelemetry_api_experimental/src/otel_counter.erl b/apps/opentelemetry_api_experimental/src/otel_counter.erl
@@ -28,7 +28,7 @@
 -spec create(Meter, Name, Opts) -> otel_instrument:t() when
       Meter :: otel_meter:t(),
       Name :: otel_instrument:name(),
-      Opts :: otel_meter:opts().
+      Opts :: otel_instrument:opts().
 create(Meter, Name, Opts) ->
     otel_meter:create_counter(Meter, Name, Opts).
 
diff --git a/apps/opentelemetry_api_experimental/src/otel_histogram.erl b/apps/opentelemetry_api_experimental/src/otel_histogram.erl
@@ -29,7 +29,7 @@
 -spec create(Meter, Name, Opts) -> otel_instrument:t() when
       Meter :: otel_meter:t(),
       Name :: otel_instrument:name(),
-      Opts :: otel_meter:opts().
+      Opts :: otel_instrument:opts().
 create(Meter, Name, Opts) ->
     otel_meter:create_histogram(Meter, Name, Opts).
 
diff --git a/apps/opentelemetry_api_experimental/src/otel_instrument.erl b/apps/opentelemetry_api_experimental/src/otel_instrument.erl
@@ -17,8 +17,8 @@
 %%%-------------------------------------------------------------------------
 -module(otel_instrument).
 
--export([new/6,
-         new/8,
+-export([new/5,
+         new/7,
          is_monotonic/1,
          temporality/1]).
 
@@ -38,6 +38,12 @@
 
 -type temporality() :: ?TEMPORALITY_DELTA | ?TEMPORALITY_CUMULATIVE.
 
+-type advisory_params() :: #{explicit_bucket_boundaries => [number(), ...]}.
+
+-type opts() :: #{description => description(),
+                  unit => unit(),
+                  advisory_params => advisory_params()}.
+
 -type t() :: #instrument{}.
 
 -export_type([t/0,
@@ -48,29 +54,39 @@
               temporality/0,
               callback/0,
               callback_args/0,
-              callback_result/0]).
+              callback_result/0,
+              advisory_params/0,
+              opts/0]).
 
--spec new(module(), otel_meter:t(), kind(), name(), description() | undefined, unit() | undefined) -> t().
-new(Module, Meter, Kind, Name, Description, Unit) ->
-    #instrument{module      = Module,
-                meter       = Meter,
-                name        = Name,
-                description = Description,
-                temporality = ?TEMPORALITY_DELTA,
-                kind        = Kind,
-                unit        = Unit}.
+-spec new(module(), otel_meter:t(), kind(), name(), opts()) -> t().
+new(Module, Meter, Kind, Name, Opts) ->
+    Description = maps:get(description, Opts, undefined),
+    Unit = maps:get(unit, Opts, undefined),
+    AdvisoryParams = maps:get(advisory_params, Opts, undefined),
+    #instrument{module          = Module,
+                meter           = Meter,
+                name            = Name,
+                description     = Description,
+                temporality     = ?TEMPORALITY_DELTA,
+                kind            = Kind,
+                unit            = Unit,
+                advisory_params = AdvisoryParams}.
 
--spec new(module(), otel_meter:t(), kind(), name(), description() | undefined, unit() | undefined, callback(), callback_args()) -> t().
-new(Module, Meter, Kind, Name, Description, Unit, Callback, CallbackArgs) ->
-    #instrument{module        = Module,
-                meter         = Meter,
-                name          = Name,
-                description   = Description,
-                kind          = Kind,
-                unit          = Unit,
-                temporality   = ?TEMPORALITY_CUMULATIVE,
-                callback      = Callback,
-                callback_args = CallbackArgs}.
+-spec new(module(), otel_meter:t(), kind(), name(), callback(), callback_args(), opts()) -> t().
+new(Module, Meter, Kind, Name, Callback, CallbackArgs, Opts) ->
+    Description = maps:get(description, Opts, undefined),
+    Unit = maps:get(unit, Opts, undefined),
+    AdvisoryParams = maps:get(advisory_params, Opts, undefined),
+    #instrument{module          = Module,
+                meter           = Meter,
+                name            = Name,
+                description     = Description,
+                kind            = Kind,
+                unit            = Unit,
+                temporality     = ?TEMPORALITY_CUMULATIVE,
+                callback        = Callback,
+                callback_args   = CallbackArgs,
+                advisory_params = AdvisoryParams}.
 
 is_monotonic(#instrument{kind=?KIND_COUNTER}) ->
     true;
diff --git a/apps/opentelemetry_api_experimental/src/otel_meter.erl b/apps/opentelemetry_api_experimental/src/otel_meter.erl
@@ -42,55 +42,51 @@
       Meter :: t(),
       Name :: otel_instrument:name(),
       Kind :: otel_instrument:kind(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 
 -callback create_instrument(Meter, Name, Kind, Callback, CallbackArgs, Opts) -> otel_instrument:t() when
       Meter :: t(),
       Name :: otel_instrument:name(),
       Kind :: otel_instrument:kind(),
       Callback :: otel_instrument:callback(),
       CallbackArgs :: otel_instrument:callback_args(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 
 -callback register_callback(Meter, Instruments, Callback, CallbackArgs) -> ok when
       Meter :: t(),
       Instruments :: otel_instrument:t(),
       Callback :: otel_instrument:callback(),
       CallbackArgs :: otel_instrument:callback_args().
 
--type opts() :: #{description => otel_instrument:description(),
-                  unit => otel_instrument:unit()}.
-
 -type t() :: {module(), term()}.
 
--export_type([t/0,
-              opts/0]).
+-export_type([t/0]).
 
 -spec create_counter(Meter, Name, Opts) -> otel_instrument:t() when
       Meter :: t(),
       Name :: otel_instrument:name(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 create_counter(Meter, Name, Opts) ->
     create_instrument(Meter, Name, ?KIND_COUNTER, Opts).
 
 -spec create_updown_counter(Meter, Name, Opts) -> otel_instrument:t() when
       Meter :: t(),
       Name :: otel_instrument:name(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 create_updown_counter(Meter, Name, Opts) ->
     create_instrument(Meter, Name, ?KIND_UPDOWN_COUNTER, Opts).
 
 -spec create_histogram(Meter, Name, Opts) -> otel_instrument:t() when
       Meter :: t(),
       Name :: otel_instrument:name(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 create_histogram(Meter, Name, Opts) ->
     create_instrument(Meter, Name, ?KIND_HISTOGRAM, Opts).
 
 -spec create_observable_counter(Meter, Name, Opts) -> otel_instrument:t() when
       Meter :: t(),
       Name :: otel_instrument:name(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 create_observable_counter(Meter, Name, Opts) ->
     create_instrument(Meter, Name, ?KIND_OBSERVABLE_COUNTER, Opts).
 
@@ -99,14 +95,14 @@ create_observable_counter(Meter, Name, Opts) ->
       Name :: otel_instrument:name(),
       Callback :: otel_instrument:callback(),
       CallbackArgs :: otel_instrument:callback_args(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 create_observable_counter(Meter, Name, Callback, CallbackArgs, Opts) ->
     create_instrument(Meter, Name, ?KIND_OBSERVABLE_COUNTER, Callback, CallbackArgs, Opts).
 
 -spec create_observable_gauge(Meter, Name, Opts) -> otel_instrument:t() when
       Meter :: t(),
       Name :: otel_instrument:name(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 create_observable_gauge(Meter, Name, Opts) ->
     create_instrument(Meter, Name, ?KIND_OBSERVABLE_GAUGE, Opts).
 
@@ -115,14 +111,14 @@ create_observable_gauge(Meter, Name, Opts) ->
       Name :: otel_instrument:name(),
       Callback :: otel_instrument:callback(),
       CallbackArgs :: otel_instrument:callback_args(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 create_observable_gauge(Meter, Name, Callback, CallbackArgs, Opts) ->
     create_instrument(Meter, Name, ?KIND_OBSERVABLE_GAUGE, Callback, CallbackArgs, Opts).
 
 -spec create_observable_updowncounter(Meter, Name, Opts) -> otel_instrument:t() when
       Meter :: t(),
       Name :: otel_instrument:name(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 create_observable_updowncounter(Meter, Name, Opts) ->
     create_instrument(Meter, Name, ?KIND_OBSERVABLE_UPDOWNCOUNTER, Opts).
 
@@ -131,7 +127,7 @@ create_observable_updowncounter(Meter, Name, Opts) ->
       Name :: otel_instrument:name(),
       Callback :: otel_instrument:callback(),
       CallbackArgs :: otel_instrument:callback_args(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 create_observable_updowncounter(Meter, Name, Callback, CallbackArgs, Opts) ->
     create_instrument(Meter, Name, ?KIND_OBSERVABLE_UPDOWNCOUNTER, Callback, CallbackArgs, Opts).
 
@@ -145,7 +141,7 @@ scope(Meter={Module, _}) ->
       Meter :: t(),
       Name :: otel_instrument:name(),
       Kind :: otel_instrument:kind(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 create_instrument(Meter={Module, _}, Name, Kind, Opts) ->
     Module:create_instrument(Meter, Name, Kind, Opts).
 
@@ -155,7 +151,7 @@ create_instrument(Meter={Module, _}, Name, Kind, Opts) ->
       Kind :: otel_instrument:kind(),
       Callback :: otel_instrument:callback(),
       CallbackArgs :: otel_instrument:callback_args(),
-      Opts :: opts().
+      Opts :: otel_instrument:opts().
 create_instrument(Meter={Module, _}, Name, Kind, Callback, CallbackArgs, Opts) ->
     Module:create_instrument(Meter, Name, Kind, Callback, CallbackArgs, Opts).
 
diff --git a/apps/opentelemetry_api_experimental/src/otel_meter_noop.erl b/apps/opentelemetry_api_experimental/src/otel_meter_noop.erl
@@ -41,9 +41,7 @@ register_callback(_Meter, _Instruments, _Callback, _CallbackArgs) ->
     ok.
 
 create_instrument(Meter, Name, Kind, Opts) ->
-    otel_instrument:new(?MODULE, Meter, Kind, Name, maps:get(description, Opts, undefined),
-                        maps:get(unit, Opts, undefined)).
+    otel_instrument:new(?MODULE, Meter, Kind, Name, Opts).
 
 create_instrument(Meter, Name, Kind, Callback, CallbackArgs, Opts) ->
-    otel_instrument:new(?MODULE, Meter, Kind, Name, maps:get(description, Opts, undefined),
-                        maps:get(unit, Opts, undefined), Callback, CallbackArgs).
+    otel_instrument:new(?MODULE, Meter, Kind, Name, Callback, CallbackArgs, Opts).
diff --git a/apps/opentelemetry_api_experimental/src/otel_updown_counter.erl b/apps/opentelemetry_api_experimental/src/otel_updown_counter.erl
@@ -28,7 +28,7 @@
 -spec create(Meter, Name, Opts) -> otel_instrument:t() when
       Meter :: otel_meter:t(),
       Name :: otel_instrument:name(),
-      Opts :: otel_meter:opts().
+      Opts :: otel_instrument:opts().
 create(Meter, Name, Opts) ->
     otel_meter:create_updown_counter(Meter, Name, Opts).
 
diff --git a/apps/opentelemetry_experimental/include/otel_metrics.hrl b/apps/opentelemetry_experimental/include/otel_metrics.hrl
@@ -62,7 +62,7 @@
          start_time_unix_nano :: integer() | {const, eqwalizer:dynamic()} | '$9' | '$2' | undefined,
          %% instrument_temporality :: otel_aggregation:temporality(),
          %% default: [0.0, 5.0, 10.0, 25.0, 50.0, 75.0, 100.0, 250.0, 500.0, 1000.0]
-         boundaries :: [float()] | match_spec([float()]),
+         explicit_bucket_boundaries :: [float()] | match_spec([float()]),
          record_min_max :: boolean() | match_spec(boolean()),
          checkpoint :: #explicit_histogram_checkpoint{} | match_spec(#explicit_histogram_checkpoint{}) | {#explicit_histogram_checkpoint{}},
          bucket_counts :: counters:counters_ref() | match_spec(undefined),
diff --git a/apps/opentelemetry_experimental/src/otel_aggregation_histogram_explicit.erl b/apps/opentelemetry_experimental/src/otel_aggregation_histogram_explicit.erl
@@ -136,12 +136,12 @@ init(#view_aggregation{name=Name,
                        reader=ReaderId,
                        aggregation_options=Options}, Attributes) ->
     Key = {Name, Attributes, ReaderId},
-    Boundaries = maps:get(boundaries, Options, ?DEFAULT_BOUNDARIES),
+    ExplicitBucketBoundaries = maps:get(explicit_bucket_boundaries, Options, ?DEFAULT_BOUNDARIES),
     RecordMinMax = maps:get(record_min_max, Options, true),
     #explicit_histogram_aggregation{key=Key,
                                     start_time_unix_nano=erlang:system_time(nanosecond),
-                                    boundaries=Boundaries,
-                                    bucket_counts=new_bucket_counts(Boundaries),
+                                    explicit_bucket_boundaries=ExplicitBucketBoundaries,
+                                    bucket_counts=new_bucket_counts(ExplicitBucketBoundaries),
                                     checkpoint=undefined,
                                     record_min_max=RecordMinMax,
                                     min=infinity, %% works because any atom is > any integer
@@ -153,17 +153,17 @@ aggregate(Table, #view_aggregation{name=Name,
                                    reader=ReaderId,
                                    aggregation_options=Options}, Value, Attributes) ->
     Key = {Name, Attributes, ReaderId},
-    Boundaries = maps:get(boundaries, Options, ?DEFAULT_BOUNDARIES),
+    ExplicitBucketBoundaries = maps:get(explicit_bucket_boundaries, Options, ?DEFAULT_BOUNDARIES),
     try ets:lookup_element(Table, Key, #explicit_histogram_aggregation.bucket_counts) of
         BucketCounts0 ->
             BucketCounts = case BucketCounts0 of
                                undefined ->
-                                   new_bucket_counts(Boundaries);
+                                   new_bucket_counts(ExplicitBucketBoundaries);
                                _ ->
                                    BucketCounts0
                            end,
 
-            BucketIdx = find_bucket(Boundaries, Value),
+            BucketIdx = find_bucket(ExplicitBucketBoundaries, Value),
             counters:add(BucketCounts, BucketIdx, 1),
 
             MS = ?AGGREATE_MATCH_SPEC(Key, Value, BucketCounts),
@@ -181,7 +181,7 @@ checkpoint(Tab, #view_aggregation{name=Name,
                                   temporality=?TEMPORALITY_DELTA}, CollectionStartNano) ->
     MS = [{#explicit_histogram_aggregation{key='$1',
                                            start_time_unix_nano='$9',
-                                           boundaries='$2',
+                                           explicit_bucket_boundaries='$2',
                                            record_min_max='$3',
                                            checkpoint='_',
                                            bucket_counts='$5',
@@ -193,7 +193,7 @@ checkpoint(Tab, #view_aggregation{name=Name,
             {'=:=', {element, 3, '$1'}, {const, ReaderId}}],
            [{#explicit_histogram_aggregation{key='$1',
                                              start_time_unix_nano={const, CollectionStartNano},
-                                             boundaries='$2',
+                                             explicit_bucket_boundaries='$2',
                                              record_min_max='$3',
                                              checkpoint={#explicit_histogram_checkpoint{bucket_counts='$5',
                                                                                         min='$6',
@@ -229,7 +229,7 @@ collect(Tab, #view_aggregation{name=Name,
 
 datapoint(CollectionStartNano, #explicit_histogram_aggregation{
                                   key={_, Attributes, _},
-                                  boundaries=Boundaries,
+                                  explicit_bucket_boundaries=Boundaries,
                                   start_time_unix_nano=StartTimeUnixNano,
                                   checkpoint=undefined,
                                   bucket_counts=BucketCounts,
@@ -253,7 +253,7 @@ datapoint(CollectionStartNano, #explicit_histogram_aggregation{
       };
 datapoint(CollectionStartNano, #explicit_histogram_aggregation{
                                   key={_, Attributes, _},
-                                  boundaries=Boundaries,
+                                  explicit_bucket_boundaries=Boundaries,
                                   checkpoint=#explicit_histogram_checkpoint{bucket_counts=BucketCounts,
                                                                             min=Min,
                                                                             max=Max,
diff --git a/apps/opentelemetry_experimental/src/otel_meter_default.erl b/apps/opentelemetry_experimental/src/otel_meter_default.erl
diff --git a/apps/opentelemetry_experimental/src/otel_meter_server.erl b/apps/opentelemetry_experimental/src/otel_meter_server.erl
diff --git a/apps/opentelemetry_experimental/src/otel_view.erl b/apps/opentelemetry_experimental/src/otel_view.erl
diff --git a/apps/opentelemetry_experimental/test/otel_metrics_SUITE.erl b/apps/opentelemetry_experimental/test/otel_metrics_SUITE.erl
