feat: Add basic support for schema_url

This adds basic schema URL support in the API + SDK, specifically in and
around Resources, Tracers, Tracer Provider, and the OTLP exporter.

Some notes, in no particular order:

- I did not add schema URLs to any of our instrumentation, because that
  was a lot of work.
- The _API_ ProxyTracer tests around "asking for a tracer multiple times
  returns the same thing" don't actually work, because we don't do
  anything with the name+version(+schema url, after this change) that
  you pass in. I don't think that matters, but I'm not really sure.
- I didn't add the schema information to the jaeger/zipkin exporters,
  after surveying what Go and Python were doing. I don't see an easy
  place to add it in, either.

1. The behavior of merging two resources with different, non-empty
   schema URLs is implementation dependent. I chose to _drop_ the schema
   URL in that case and continue merging resources as before. *Is this
   what we want?* Other SDKs do things differently (Go returns an error,
   Python logs an error and returns the old resource, etc).
2. I did *not* add support to the Configurator for setting the
   schema_url on the default Resource that gets initialized. That seemed
   like the kind of thing folks would do incorrectly, but you can still
   do such a thing by creating and assigning an entire Resource if you
   wish. *Is this what we want?*

Author: ahayworth

api/lib/opentelemetry/internal/proxy_tracer_provider.rb

@@ -13,7 +13,7 @@ module Internal
     # It delegates to a "real" TracerProvider after the global tracer provider is registered.
     # It returns {ProxyTracer} instances until the delegate is installed.
     class ProxyTracerProvider < Trace::TracerProvider
-      Key = Struct.new(:name, :version)
+      Key = Struct.new(:name, :version, :schema_url)
       private_constant(:Key)
 
       # Returns a new {ProxyTracerProvider} instance.
@@ -37,21 +37,22 @@ def delegate=(provider)
 
         @mutex.synchronize do
           @delegate = provider
-          @registry.each { |key, tracer| tracer.delegate = provider.tracer(key.name, key.version) }
+          @registry.each { |key, tracer| tracer.delegate = provider.tracer(key.name, key.version, key.schema_url) }
         end
       end
 
       # Returns a {Tracer} instance.
       #
       # @param [optional String] name Instrumentation package name
       # @param [optional String] version Instrumentation package version
+      # @param [optional String] schema_url Schema URL to be recorded with traces
       #
       # @return [Tracer]
-      def tracer(name = nil, version = nil)
+      def tracer(name = nil, version = nil, schema_url = nil)
         @mutex.synchronize do
-          return @delegate.tracer(name, version) unless @delegate.nil?
+          return @delegate.tracer(name, version, schema_url) unless @delegate.nil?
 
-          @registry[Key.new(name, version)] ||= ProxyTracer.new
+          @registry[Key.new(name, version, schema_url)] ||= ProxyTracer.new
         end
       end
     end

api/lib/opentelemetry/trace/tracer_provider.rb

@@ -12,9 +12,10 @@ class TracerProvider
       #
       # @param [optional String] name Instrumentation package name
       # @param [optional String] version Instrumentation package version
+      # @param [optional String] schema_url Schema URL to be recorded with traces
       #
       # @return [Tracer]
-      def tracer(name = nil, version = nil)
+      def tracer(name = nil, version = nil, schema_url = nil)
         @tracer ||= Tracer.new
       end
     end

api/test/opentelemetry/trace/tracer_provider_test.rb

@@ -10,9 +10,10 @@
   let(:tracer_provider) { OpenTelemetry::Trace::TracerProvider.new }
 
   describe '.tracer' do
+    # TODO: This test doesn't really do anything for the API tracer
     it 'returns the same tracer for the same arguments' do
-      tracer1 = tracer_provider.tracer('component', '1.0')
-      tracer2 = tracer_provider.tracer('component', '1.0')
+      tracer1 = tracer_provider.tracer('component', '1.0', 'https://http.cat/404')
+      tracer2 = tracer_provider.tracer('component', '1.0', 'https://http.cat/404')
       _(tracer1).must_equal(tracer2)
     end
   end

api/test/opentelemetry_test.rb

@@ -18,7 +18,7 @@ def start_root_span(*)
   end
 
   class CustomTracerProvider < OpenTelemetry::Trace::TracerProvider
-    def tracer(name = nil, version = nil)
+    def tracer(name = nil, version = nil, schema_url = nil)
       CustomTracer.new
     end
   end

exporter/otlp/lib/opentelemetry/exporter/otlp/exporter.rb

@@ -292,6 +292,7 @@ def encode(span_data) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
                     resource: Opentelemetry::Proto::Resource::V1::Resource.new(
                       attributes: resource.attribute_enumerator.map { |key, value| as_otlp_key_value(key, value) }
                     ),
+                    schema_url: resource.schema_url,
                     instrumentation_library_spans: span_datas
                       .group_by(&:instrumentation_library)
                       .map do |il, sds|
@@ -300,7 +301,8 @@ def encode(span_data) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
                             name: il.name,
                             version: il.version
                           ),
-                          spans: sds.map { |sd| as_otlp_span(sd) }
+                          spans: sds.map { |sd| as_otlp_span(sd) },
+                          schema_url: il.schema_url
                         )
                       end
                   )

exporter/otlp/test/opentelemetry/exporter/otlp/exporter_test.rb

@@ -467,6 +467,35 @@
       _(etsr.resource_spans.length).must_equal(2)
     end
 
+    it 'can encode resource schema_urls' do
+      etsr = nil
+      stub_post = stub_request(:post, 'http://localhost:4318/v1/traces').to_return do |request|
+        proto = Zlib.gunzip(request.body)
+        etsr = Opentelemetry::Proto::Collector::Trace::V1::ExportTraceServiceRequest.decode(proto)
+        { status: 200 }
+      end
+
+      span_data1 = create_span_data(
+        resource: OpenTelemetry::SDK::Resources::Resource.create({'k1' => 'v1'}, 'https://http.cat/200'),
+        instrumentation_library: OpenTelemetry::SDK::InstrumentationLibrary.new('', 'v0.0.1', 'https://http.cat/429')
+      )
+      span_data2 = create_span_data(
+        resource: OpenTelemetry::SDK::Resources::Resource.create({'k2' => 'v2'}, 'https://http.cat/404'),
+        instrumentation_library: OpenTelemetry::SDK::InstrumentationLibrary.new('', 'v0.0.1', 'https://http.cat/451')
+      )
+      result = exporter.export([span_data1, span_data2])
+
+      _(result).must_equal(SUCCESS)
+      assert_requested(stub_post)
+
+      _(etsr.resource_spans.length).must_equal(2)
+      _(etsr.resource_spans[0].schema_url).must_equal('https://http.cat/200')
+      _(etsr.resource_spans[0].instrumentation_library_spans[0].schema_url).must_equal('https://http.cat/429')
+
+      _(etsr.resource_spans[1].schema_url).must_equal('https://http.cat/404')
+      _(etsr.resource_spans[1].instrumentation_library_spans[0].schema_url).must_equal('https://http.cat/451')
+    end
+
     it 'translates all the things' do
       stub_request(:post, 'http://localhost:4318/v1/traces').to_return(status: 200)
       processor = OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter)

sdk/lib/opentelemetry/sdk/instrumentation_library.rb

@@ -8,6 +8,7 @@ module OpenTelemetry
   module SDK
     # InstrumentationLibrary is a struct containing library information for export.
     InstrumentationLibrary = Struct.new(:name,
-                                        :version)
+                                        :version,
+                                        :schema_url)
   end
 end

sdk/lib/opentelemetry/sdk/resources/resource.rb

@@ -15,19 +15,22 @@ class << self
 
           # Returns a newly created {Resource} with the specified attributes
           #
-          # @param [Hash{String => String, Numeric, Boolean} attributes Hash of key-value pairs to be used
+          # @param [Hash{String => String, Numeric, Boolean}] attributes Hash of key-value pairs to be used
           #   as attributes for this resource
+          # @param [String] Specifies the Schema URL that should be recorded in the emitted resource.
           # @raise [ArgumentError] If attribute keys and values are not strings
           # @return [Resource]
-          def create(attributes = {})
+          def create(attributes = {}, schema_url = '')
+            raise ArgumentError, 'Schema url must be a string' unless schema_url.is_a?(String)
+
             frozen_attributes = attributes.each_with_object({}) do |(k, v), memo|
               raise ArgumentError, 'attribute keys must be strings' unless k.is_a?(String)
               raise ArgumentError, 'attribute values must be (array of) strings, integers, floats, or booleans' unless Internal.valid_value?(v)
 
               memo[-k] = v.freeze
             end.freeze
 
-            new(frozen_attributes)
+            new(frozen_attributes, schema_url)
           end
 
           def default
@@ -81,8 +84,9 @@ def service_name_from_env
         # @param [Hash<String, String>] frozen_attributes Frozen-hash of frozen-string
         #  key-value pairs to be used as attributes for this resource
         # @return [Resource]
-        def initialize(frozen_attributes)
+        def initialize(frozen_attributes, schema_url)
           @attributes = frozen_attributes
+          @schema_url = schema_url
         end
 
         # Returns an enumerator for attributes of this {Resource}
@@ -93,20 +97,34 @@ def attribute_enumerator
         end
 
         # Returns a new, merged {Resource} by merging the current {Resource} with
-        # the other {Resource}. In case of a collision, the current {Resource}
-        # takes precedence
+        # the other {Resource}. In case of an attributes collision, the other {Resource}
+        # takes precedence. If two incompatible schema urls are given, then the schema
+        # URL of the resulting resource will be unset.
         #
         # @param [Resource] other The other resource to merge
         # @return [Resource] A new resource formed by merging the current resource
         #   with other
         def merge(other)
           return self unless other.is_a?(Resource)
 
-          self.class.send(:new, attributes.merge(other.attributes).freeze)
+          # This is slightly verbose, but tries to follow the definition in the spec closely.
+          new_schema_url = if schema_url == ''
+            other.schema_url
+          elsif other.schema_url == '' || schema_url == other.schema_url
+            schema_url
+          elsif schema_url != other.schema_url
+            # According to the spec: The resulting resource is undefined, and its contents are implementation-specific.
+            # We choose to simply un-set the resource URL and log a warning about it, and allow the attributes to merge.
+            OpenTelemetry.logger.warn("Merging resources with schema version '#{schema_url}' and '#{other.schema_url}' is undefined.")
+            ''
+          end
+
+          self.class.send(:new, attributes.merge(other.attributes).freeze, new_schema_url)
         end
 
-        protected
+        attr_reader :schema_url
 
+        protected
         attr_reader :attributes
       end
     end

sdk/lib/opentelemetry/sdk/trace/tracer.rb

@@ -15,11 +15,12 @@ class Tracer < OpenTelemetry::Trace::Tracer
         #
         # @param [String] name Instrumentation package name
         # @param [String] version Instrumentation package version
+        # @param [String] schema_url Schema URL to be recorded with traces
         # @param [TracerProvider] tracer_provider TracerProvider that initialized the tracer
         #
         # @return [Tracer]
-        def initialize(name, version, tracer_provider)
-          @instrumentation_library = InstrumentationLibrary.new(name, version)
+        def initialize(name, version, schema_url, tracer_provider)
+          @instrumentation_library = InstrumentationLibrary.new(name, version, schema_url)
           @tracer_provider = tracer_provider
         end
 

sdk/lib/opentelemetry/sdk/trace/tracer_provider.rb

@@ -9,7 +9,7 @@ module SDK
     module Trace
       # {TracerProvider} is the SDK implementation of {OpenTelemetry::Trace::TracerProvider}.
       class TracerProvider < OpenTelemetry::Trace::TracerProvider # rubocop:disable Metrics/ClassLength
-        Key = Struct.new(:name, :version)
+        Key = Struct.new(:name, :version, :schema_url)
         private_constant(:Key)
 
         attr_accessor :span_limits, :id_generator, :sampler
@@ -46,13 +46,15 @@ def initialize(sampler: sampler_from_environment(Samplers.parent_based(root: Sam
         #
         # @param [optional String] name Instrumentation package name
         # @param [optional String] version Instrumentation package version
+        # @param [optional String] schema_url Schema URL to be recorded with traces
         #
         # @return [Tracer]
-        def tracer(name = nil, version = nil)
+        def tracer(name = nil, version = nil, schema_url = nil)
           name ||= ''
           version ||= ''
+          schema_url ||= ''
           OpenTelemetry.logger.warn 'calling TracerProvider#tracer without providing a tracer name.' if name.empty?
-          @registry_mutex.synchronize { @registry[Key.new(name, version)] ||= Tracer.new(name, version, self) }
+          @registry_mutex.synchronize { @registry[Key.new(name, version, schema_url)] ||= Tracer.new(name, version, schema_url, self) }
         end
 
         # Attempts to stop all the activity for this {TracerProvider}. Calls