replace InstrumentationLibrary with InstrumentationScope

Spec change can be found in PR:
 open-telemetry/opentelemetry-specification#2276

CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### [API]
+
+#### Added
+
+- [Instrumentation Scope replaces Instrumentation Library]()
+
+### [SDK]
+
+#### Added
+
+- [Instrumentation Scope replaces Instrumentation Library]()
+
+### [Exporter]
+
+#### Added
+
+- [Instrumentation Scope replaces Instrumentation Library]()
+
 ## SDK 1.0.5 - 2022-05-20
 
 ### Fixed

apps/opentelemetry/include/otel_span.hrl

@@ -64,7 +64,7 @@
           %% trace flags lowest bit is 1 but simply not propagated.
           is_recording            :: boolean() | undefined,
 
-          instrumentation_library :: opentelemetry:instrumentation_library() | undefined
+          instrumentation_scope :: opentelemetry:instrumentation_scope() | undefined
          }).
 
 -record(span_limits, {

apps/opentelemetry/src/otel_batch_processor.erl

@@ -275,10 +275,10 @@ new_export_table(Name) ->
                     {write_concurrency, true},
                     duplicate_bag,
                     %% OpenTelemetry exporter protos group by the
-                    %% instrumentation_library. So using instrumentation_library
+                    %% instrumentation_scope. So using instrumentation_scope
                     %% as the key means we can easily lookup all spans for
-                    %% for each instrumentation_library and export together.
-                    {keypos, #span.instrumentation_library}]).
+                    %% for each instrumentation_scope and export together.
+                    {keypos, #span.instrumentation_scope}]).
 
 export_spans(#data{exporter=Exporter,
                    resource=Resource}) ->

apps/opentelemetry/src/otel_simple_processor.erl

@@ -164,10 +164,10 @@ new_export_table(Name) ->
                     {write_concurrency, true},
                     duplicate_bag,
                     %% OpenTelemetry exporter protos group by the
-                    %% instrumentation_library. So using instrumentation_library
+                    %% instrumentation_scope. So using instrumentation_scope
                     %% as the key means we can easily lookup all spans for
-                    %% for each instrumentation_library and export together.
-                    {keypos, #span.instrumentation_library}]).
+                    %% for each instrumentation_scope and export together.
+                    {keypos, #span.instrumentation_scope}]).
 
 export_span(Span, #data{exporter=Exporter,
                         resource=Resource}) ->

apps/opentelemetry/src/otel_span_ets.erl

@@ -48,12 +48,12 @@ start_link(Opts) ->
 
 %% @doc Start a span and insert into the active span ets table.
 -spec start_span(otel_ctx:t(), opentelemetry:span_name(), otel_sampler:t(), otel_id_generator:t(),
-                 otel_span:start_opts(), fun(), otel_tracer_server:instrumentation_library())
+                 otel_span:start_opts(), fun(), otel_tracer_server:instrumentation_scope())
                 -> opentelemetry:span_ctx().
-start_span(Ctx, Name, Sampler, IdGeneratorModule, Opts, Processors, InstrumentationLibrary) ->
+start_span(Ctx, Name, Sampler, IdGeneratorModule, Opts, Processors, InstrumentationScope) ->
     case otel_span_utils:start_span(Ctx, Name, Sampler, IdGeneratorModule, Opts) of
         {SpanCtx=#span_ctx{is_recording=true}, Span=#span{}} ->
-            Span1 = Span#span{instrumentation_library=InstrumentationLibrary},
+            Span1 = Span#span{instrumentation_scope=InstrumentationScope},
             Span2 = Processors(Ctx, Span1),
             _ = storage_insert(Span2),
             SpanCtx;

apps/opentelemetry/src/otel_tracer.hrl

@@ -10,7 +10,7 @@
          on_end_processors       :: fun((opentelemetry:span()) -> boolean() | {error, term()}),
          sampler                 :: otel_sampler:t(),
          id_generator            :: otel_id_generator:t(),
-         instrumentation_library :: otel_tracer_server:instrumentation_library() | undefined,
+         instrumentation_scope :: otel_tracer_server:instrumentation_scope() | undefined,
          telemetry_library       :: otel_tracer_server:telemetry_library() | undefined,
          resource                :: otel_resource:t() | undefined
         }).

apps/opentelemetry/src/otel_tracer_default.erl

@@ -33,8 +33,8 @@ start_span(Ctx, {_, #tracer{on_start_processors=Processors,
                             on_end_processors=OnEndProcessors,
                             sampler=Sampler,
                             id_generator=IdGeneratorModule,
-                            instrumentation_library=InstrumentationLibrary}}, Name, Opts) ->
-    SpanCtx = otel_span_ets:start_span(Ctx, Name, Sampler, IdGeneratorModule, Opts, Processors, InstrumentationLibrary),
+                            instrumentation_scope=InstrumentationScope}}, Name, Opts) ->
+    SpanCtx = otel_span_ets:start_span(Ctx, Name, Sampler, IdGeneratorModule, Opts, Processors, InstrumentationScope),
     SpanCtx#span_ctx{span_sdk={otel_span_ets, OnEndProcessors}}.
 
 -spec with_span(otel_ctx:t(), opentelemetry:tracer(), opentelemetry:span_name(),

apps/opentelemetry/src/otel_tracer_server.erl

@@ -35,9 +35,9 @@
 -include("otel_span.hrl").
 
 -type telemetry_library() :: #telemetry_library{}.
--type instrumentation_library() :: #instrumentation_library{}.
+-type instrumentation_scope() :: #instrumentation_scope{}.
 -export_type([telemetry_library/0,
-              instrumentation_library/0]).
+              instrumentation_scope/0]).
 
 -record(state,
         {
@@ -100,15 +100,15 @@ handle_call({get_tracer, Name, Vsn, SchemaUrl}, _From, State=#state{shared_trace
         true ->
             {reply, {otel_tracer_noop, []}, State};
         false ->
-            InstrumentationLibrary = opentelemetry:instrumentation_library(Name, Vsn, SchemaUrl),
+            InstrumentationScope = opentelemetry:instrumentation_scope(Name, Vsn, SchemaUrl),
             TracerTuple = {Tracer#tracer.module,
-                           Tracer#tracer{instrumentation_library=InstrumentationLibrary}},
+                           Tracer#tracer{instrumentation_scope=InstrumentationScope}},
             {reply, TracerTuple, State}
     end;
-handle_call({get_tracer, InstrumentationLibrary}, _From, State=#state{shared_tracer=Tracer,
+handle_call({get_tracer, InstrumentationScope}, _From, State=#state{shared_tracer=Tracer,
                                                                       deny_list=_DenyList}) ->
     {reply, {Tracer#tracer.module,
-             Tracer#tracer{instrumentation_library=InstrumentationLibrary}}, State};
+             Tracer#tracer{instrumentation_scope=InstrumentationScope}}, State};
 handle_call(force_flush, _From, State=#state{processors=Processors}) ->
     Reply = lists:foldl(fun(Processor, Result) ->
                                 case force_flush_(Processor) of

apps/opentelemetry/test/opentelemetry_SUITE.erl

@@ -28,7 +28,7 @@ all() ->
 
 all_cases() ->
     [with_span, macros, child_spans,
-     update_span_data, tracer_instrumentation_library, tracer_previous_ctx, stop_temporary_app,
+     update_span_data, tracer_instrumentation_scope, tracer_previous_ctx, stop_temporary_app,
      reset_after, attach_ctx, default_sampler, non_recording_ets_table,
      root_span_sampling_always_on, root_span_sampling_always_off,
      record_but_not_sample, record_exception_works, record_exception_with_message_works,
@@ -103,7 +103,7 @@ init_per_testcase(too_many_attributes, Config) ->
     Tid = ets:new(exported_spans, [public, bag]),
     otel_batch_processor:set_exporter(otel_exporter_tab, Tid),
     [{tid, Tid} | Config];
-init_per_testcase(tracer_instrumentation_library, Config) ->
+init_per_testcase(tracer_instrumentation_scope, Config) ->
     application:set_env(opentelemetry, processors, [{otel_batch_processor, #{scheduled_delay_ms => 1}}]),
     {ok, _} = application:ensure_all_started(opentelemetry),
     %% adds an exporter for a new table
@@ -139,34 +139,34 @@ end_per_testcase(_, _Config) ->
     ok.
 
 disable_auto_creation(_Config) ->
-    {_, #tracer{instrumentation_library=Library}} = opentelemetry:get_tracer(
+    {_, #tracer{instrumentation_scope=Library}} = opentelemetry:get_tracer(
                                                       opentelemetry:get_application(kernel)),
     ?assertEqual(undefined, Library),
     ok.
 
 old_disable_auto_creation(_Config) ->
-    {_, #tracer{instrumentation_library=Library}} = opentelemetry:get_tracer(
+    {_, #tracer{instrumentation_scope=Library}} = opentelemetry:get_tracer(
                                                       opentelemetry:get_application(kernel)),
     ?assertEqual(undefined, Library),
     ok.
 
 application_tracers(_Config) ->
-    {_, #tracer{instrumentation_library=Library}} = opentelemetry:get_tracer(
+    {_, #tracer{instrumentation_scope=Library}} = opentelemetry:get_tracer(
                                                       opentelemetry:get_application(kernel)),
-    ?assertEqual(<<"kernel">>, Library#instrumentation_library.name),
+    ?assertEqual(<<"kernel">>, Library#instrumentation_scope.name),
 
     %% tracers are unique by name/version/schema_url
     NewKernelTracer = opentelemetry:get_tracer(kernel, <<"fake-version">>, undefined),
-    {_, #tracer{instrumentation_library=NewLibrary}} = NewKernelTracer,
-    ?assertEqual(<<"kernel">>, NewLibrary#instrumentation_library.name),
-    ?assertEqual(<<"fake-version">>, NewLibrary#instrumentation_library.version),
-    ?assertEqual(undefined, NewLibrary#instrumentation_library.schema_url),
+    {_, #tracer{instrumentation_scope=NewLibrary}} = NewKernelTracer,
+    ?assertEqual(<<"kernel">>, NewLibrary#instrumentation_scope.name),
+    ?assertEqual(<<"fake-version">>, NewLibrary#instrumentation_scope.version),
+    ?assertEqual(undefined, NewLibrary#instrumentation_scope.schema_url),
 
     Tracer = opentelemetry:get_tracer(kernel, <<"fake-version">>, <<"http://schema.org/myschema">>),
-    {_, #tracer{instrumentation_library=NewLibrary1}} = Tracer,
-    ?assertEqual(<<"kernel">>, NewLibrary1#instrumentation_library.name),
-    ?assertEqual(<<"fake-version">>, NewLibrary1#instrumentation_library.version),
-    ?assertEqual(<<"http://schema.org/myschema">>, NewLibrary1#instrumentation_library.schema_url),
+    {_, #tracer{instrumentation_scope=NewLibrary1}} = Tracer,
+    ?assertEqual(<<"kernel">>, NewLibrary1#instrumentation_scope.name),
+    ?assertEqual(<<"fake-version">>, NewLibrary1#instrumentation_scope.version),
+    ?assertEqual(<<"http://schema.org/myschema">>, NewLibrary1#instrumentation_scope.schema_url),
 
     ok.
 
@@ -434,15 +434,15 @@ update_span_data(Config) ->
     ok.
 
 
-tracer_instrumentation_library(Config) ->
+tracer_instrumentation_scope(Config) ->
     Tid = ?config(tid, Config),
 
     TracerName = tracer1,
     TracerVsn = <<"1.0.0">>,
-    Tracer = {_, #tracer{instrumentation_library=IL}} =
+    Tracer = {_, #tracer{instrumentation_scope=IL}} =
         opentelemetry:get_tracer(TracerName, TracerVsn, "http://schema.org/myschema"),
 
-    ?assertMatch({instrumentation_library,<<"tracer1">>,<<"1.0.0">>,<<"http://schema.org/myschema">>},
+    ?assertMatch({instrumentation_scope,<<"tracer1">>,<<"1.0.0">>,<<"http://schema.org/myschema">>},
                  IL),
 
     SpanCtx1 = otel_tracer:start_span(Tracer, <<"span-1">>, #{}),
@@ -451,8 +451,8 @@ tracer_instrumentation_library(Config) ->
 
     [Span1] = assert_exported(Tid, SpanCtx1),
 
-    ?assertMatch({instrumentation_library,<<"tracer1">>,<<"1.0.0">>,<<"http://schema.org/myschema">>},
-                 Span1#span.instrumentation_library).
+    ?assertMatch({instrumentation_scope,<<"tracer1">>,<<"1.0.0">>,<<"http://schema.org/myschema">>},
+                 Span1#span.instrumentation_scope).
 
 %% check that ending a span results in the tracer setting the previous tracer context
 %% as the current active and not use the parent span ctx of the span being ended --

apps/opentelemetry_api/include/opentelemetry.hrl

@@ -36,7 +36,7 @@
 
 %% Holds information about the instrumentation library specified when
 %% getting a Tracer from the TracerProvider.
--record(instrumentation_library, {name       :: unicode:unicode_binary() | undefined,
+-record(instrumentation_scope, {name       :: unicode:unicode_binary() | undefined,
                                   version    :: unicode:unicode_binary() | undefined,
                                   schema_url :: uri_string:uri_string() | undefined}).
 

apps/opentelemetry_api/src/opentelemetry.erl

@@ -41,6 +41,7 @@
          get_text_map_extractor/0,
          set_text_map_injector/1,
          get_text_map_injector/0,
+         instrumentation_scope/3,
          instrumentation_library/3,
          timestamp/0,
          timestamp_to_nano/1,
@@ -60,7 +61,7 @@
 -include_lib("kernel/include/logger.hrl").
 
 -export_type([tracer/0,
-              instrumentation_library/0,
+              instrumentation_scope/0,
               trace_id/0,
               span_id/0,
               hex_trace_id/0,
@@ -86,7 +87,7 @@
 
 -type tracer()             :: {module(), term()}.
 
--type instrumentation_library() :: #instrumentation_library{}.
+-type instrumentation_scope() :: #instrumentation_scope{}.
 
 -type trace_id()           :: non_neg_integer().
 -type span_id()            :: non_neg_integer().
@@ -436,16 +437,21 @@ link_or_false(TraceId, SpanId, Attributes, TraceState) ->
             false
     end.
 
-instrumentation_library(Name, Vsn, SchemaUrl) ->
+instrumentation_scope(Name, Vsn, SchemaUrl) ->
     case name_to_binary(Name) of
         undefined ->
             undefined;
         BinaryName ->
-            #instrumentation_library{name=BinaryName,
-                                     version=vsn_to_binary(Vsn),
-                                     schema_url=schema_url_to_binary(SchemaUrl)}
+            #instrumentation_scope{name=BinaryName,
+                                   version=vsn_to_binary(Vsn),
+                                   schema_url=schema_url_to_binary(SchemaUrl)}
     end.
 
+%% this function remains solely to keep backwards compatibility
+%% but `instrumentation_scope' should be used instead
+instrumentation_library(Name, Vsn, SchemaUrl) ->
+    instrumentation_scope(Name, Vsn, SchemaUrl).
+
 %% schema_url is option, so set to undefined if its not a string
 schema_url_to_binary(SchemaUrl) when is_binary(SchemaUrl) ; is_list(SchemaUrl) ->
     unicode:characters_to_binary(SchemaUrl);

apps/opentelemetry_experimental/src/otel_meter.hrl

@@ -1,5 +1,5 @@
 -record(meter, {module                  :: module(),
-                instrumentation_library :: otel_tracer_server:instrumentation_library() | undefined,
+                instrumentation_scope :: otel_tracer_server:instrumentation_scope() | undefined,
                 telemetry_library       :: otel_tracer_server:telemetry_library() | undefined,
                 resource                :: otel_resource:t() | undefined}).
 -type meter() :: #meter{}.

apps/opentelemetry_experimental/src/otel_meter_server.erl

@@ -45,9 +45,9 @@ register_meter(Name, Vsn, #state{meter=Meter,
         true ->
             opentelemetry_experimental:set_meter(Name, {otel_meter_noop, []});
         false ->
-            InstrumentationLibrary = opentelemetry:instrumentation_library(Name, Vsn, undefined),
+            InstrumentationScope = opentelemetry:instrumentation_scope(Name, Vsn, undefined),
             opentelemetry_experimental:set_meter(Name, {Meter#meter.module,
-                                                        Meter#meter{instrumentation_library=InstrumentationLibrary}})
+                                                        Meter#meter{instrumentation_scope=InstrumentationScope}})
     end.
 
 %%

apps/opentelemetry_exporter/src/opentelemetry_exporter.erl

@@ -102,7 +102,7 @@
 
 %% for testing
 -ifdef(TEST).
--export([to_proto_by_instrumentation_library/1,
+-export([to_proto_by_instrumentation_scope/1,
          to_proto/1,
          endpoints/2,
          merge_with_environment/1]).
@@ -495,44 +495,44 @@ config_mapping() ->
     ].
 
 tab_to_proto(Tab, Resource) ->
-    InstrumentationLibrarySpans = to_proto_by_instrumentation_library(Tab),
+    InstrumentationScopeSpans = to_proto_by_instrumentation_scope(Tab),
     Attributes = otel_resource:attributes(Resource),
     ResourceSpans = #{resource => #{attributes => to_attributes(otel_attributes:map(Attributes)),
                                     dropped_attributes_count => otel_attributes:dropped(Attributes)},
-                      instrumentation_library_spans => InstrumentationLibrarySpans},
+                      scope_spans => InstrumentationScopeSpans},
     case otel_resource:schema_url(Resource) of
         undefined ->
             #{resource_spans => [ResourceSpans]};
         SchemaUrl ->
             #{resource_spans => [ResourceSpans#{schema_url => SchemaUrl}]}
     end.
 
-to_proto_by_instrumentation_library(Tab) ->
+to_proto_by_instrumentation_scope(Tab) ->
     Key = ets:first(Tab),
-    to_proto_by_instrumentation_library(Tab, Key).
+    to_proto_by_instrumentation_scope(Tab, Key).
 
-to_proto_by_instrumentation_library(_Tab, '$end_of_table') ->
+to_proto_by_instrumentation_scope(_Tab, '$end_of_table') ->
     [];
-to_proto_by_instrumentation_library(Tab, InstrumentationLibrary) ->
-    InstrumentationLibrarySpans = lists:foldl(fun(Span, Acc) ->
+to_proto_by_instrumentation_scope(Tab, InstrumentationScope) ->
+    InstrumentationScopeSpans = lists:foldl(fun(Span, Acc) ->
                                                       [to_proto(Span) | Acc]
-                                              end, [], ets:lookup(Tab, InstrumentationLibrary)),
-    InstrumentationLibrarySpansProto = to_instrumentation_library_proto(InstrumentationLibrary),
-    [InstrumentationLibrarySpansProto#{spans => InstrumentationLibrarySpans}
-    | to_proto_by_instrumentation_library(Tab, ets:next(Tab, InstrumentationLibrary))].
+                                              end, [], ets:lookup(Tab, InstrumentationScope)),
+    InstrumentationScopeSpansProto = to_instrumentation_scope_proto(InstrumentationScope),
+    [InstrumentationScopeSpansProto#{spans => InstrumentationScopeSpans}
+    | to_proto_by_instrumentation_scope(Tab, ets:next(Tab, InstrumentationScope))].
 
 
-to_instrumentation_library_proto(undefined) ->
+to_instrumentation_scope_proto(undefined) ->
     #{};
-to_instrumentation_library_proto(#instrumentation_library{name=Name,
+to_instrumentation_scope_proto(#instrumentation_scope{name=Name,
                                                           version=Version,
                                                           schema_url=undefined}) ->
-    #{instrumentation_library => #{name => Name,
+    #{instrumentation_scope => #{name => Name,
                                    version => Version}};
-to_instrumentation_library_proto(#instrumentation_library{name=Name,
+to_instrumentation_scope_proto(#instrumentation_scope{name=Name,
                                                           version=Version,
                                                           schema_url=SchemaUrl}) ->
-    #{instrumentation_library => #{name => Name,
+    #{instrumentation_scope => #{name => Name,
                                    version => Version},
       schema_url => SchemaUrl}.