opentelemetry-sdk 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ec567bdc317284ee832998232c68645a334e361aa25525901d2054982fe1390
-  data.tar.gz: c82ce9e13256fd7e70937f806a11fae72798748e92bdb68b587a6aaa2274f00e
+  metadata.gz: 4e4e07f01a74b3728fc3e3b7624bc4bc8e2b82ec2fdfcd8512544ba9fb28b202
+  data.tar.gz: a28f74743c88d4cb4b06917061c6995805550d3d048bddda10db850e83399259
 SHA512:
-  metadata.gz: 1417b975acd7e5006b58c34341f464db4ba809b8664ff0282cc1c7b6caac54358c33691a04dadf78ae1df8323cbb8f8dc8b10bd33da4326fb57ee0c293279f6c
-  data.tar.gz: 1b2c01c8f77f936cdc9c144f8b1237f7ca46fa92a657bbc0d0824288bde5c3ba49914761f7181630c49c43d843b3c6e39bf33bda30147530f156c6f82e79f63e
+  metadata.gz: 19e27ad4c599e28e9f9bd5156af4228b3fd0e043b793cff9f87e4ef84e82efc3e22053a8406ce2c24a47527194e398243ea137bc6e9b32ec15b0dafc490c456d
+  data.tar.gz: 2e82d76bca14d45cec4cacc92255c8779d4ccb272b72b8d854c93e9a455675e496a5c562ee4932cb2bc00c971e932be7494db36d78277486e91f7568da44e4f1

data/.yardopts

@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry SDK
+--markup=markdown
+--main=OVERVIEW.md
+./lib/opentelemetry/sdk/**/*.rb
+./lib/opentelemetry/sdk.rb
+-
+OVERVIEW.md
+CHANGELOG.md

data/README.md

@@ -0,0 +1,73 @@
+# opentelemetry-sdk
+
+The `opentelemetry-sdk` gem provides the reference implementation of the OpenTelemetry Ruby API. Using `opentelemetry-sdk`, an application can collect, analyze, and export telemetry data such as distributed traces and metrics.
+
+## What is OpenTelemetry?
+
+[OpenTelemetry][opentelemetry-home] is an open source observability framework, providing a general-purpose API, SDK, and related tools required for the instrumentation of cloud-native software, frameworks, and libraries.
+
+OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
+
+## How does this gem fit in?
+
+The `opentelemetry-sdk` gem provides the reference implementation of the OpenTelemetry Ruby interfaces defined in the `opentelemetry-api` gem. That is, it includes the *functionality* needed to collect, analyze, and export telemetry data produced using the API.
+
+Generally, Ruby *applications* should install `opentelemetry-sdk` (or other concrete implementation of the OpenTelemetry API). Using the SDK, an application can configure how it wants telemetry data to be handled, including which data should be persisted, how it should be formatted, and where it should be recorded or exported. However, *libraries* that produce telemetry data should generally depend only on `opentelemetry-api`, deferring the choise of concrete implementation to the application developer.
+
+## How do I get started?
+
+Install the gem using:
+
+```
+gem install opentelemetry-sdk
+```
+
+Or, if you use [bundler][bundler-home], include `opentelemetry-sdk` in your `Gemfile`.
+
+Then, configure the SDK according to your desired handling of telemetry data, and use the OpenTelemetry interfaces to produces traces and other information. Following is a basic example.
+
+```ruby
+require 'opentelemetry/sdk'
+
+# Configure the sdk with default export and context propagation formats
+# see SDK#configure for customizing the setup
+OpenTelemetry::SDK.configure
+
+# To start a trace you need to get a Tracer from the TracerProvider
+tracer = OpenTelemetry.tracer_provider.tracer('my_app_or_gem', '0.1.0')
+
+# create a span
+tracer.in_span('foo') do |span|
+  # set an attribute
+  span.set_attribute('platform', 'osx')
+  # add an event
+  span.add_event(name: 'event in bar')
+  # create bar as child of foo
+  tracer.in_span('bar') do |child_span|
+    # inspect the span
+    pp child_span
+  end
+end
+```
+
+For additional examples, see the [examples on github][examples-github].
+
+## How can I get involved?
+
+The `opentelemetry-sdk` gem source is [on github][repo-github], along with related gems including `opentelemetry-api`.
+
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [gitter channel][ruby-gitter] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+
+## License
+
+The `opentelemetry-sdk` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.
+
+
+[opentelemetry-home]: https://opentelemetry.io
+[bundler-home]: https://bundler.io
+[repo-github]: https://github.com/open-telemetry/opentelemetry-ruby
+[license-github]: https://github.com/open-telemetry/opentelemetry-ruby/blob/master/LICENSE
+[examples-github]: https://github.com/open-telemetry/opentelemetry-ruby/tree/master/examples
+[ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
+[community-meetings]: https://github.com/open-telemetry/community#community-meetings
+[ruby-gitter]: https://gitter.im/open-telemetry/opentelemetry-ruby

data/lib/opentelemetry-sdk.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/sdk'

data/lib/opentelemetry/sdk.rb

@@ -6,12 +6,62 @@
 
 require 'opentelemetry'
 
+# OpenTelemetry is an open source observability framework, providing a
+# general-purpose API, SDK, and related tools required for the instrumentation
+# of cloud-native software, frameworks, and libraries.
+#
+# The OpenTelemetry module provides global accessors for telemetry objects.
+# See the documentation for the `opentelemetry-api` gem for details.
 module OpenTelemetry
   # SDK provides the reference implementation of the OpenTelemetry API.
   module SDK
+    extend self
+
+    # Configures SDK and instrumentation
+    #
+    # @yieldparam [Configurator] configurator Yields a configurator to the
+    #   provided block
+    #
+    # Example usage:
+    #   Without a block defaults are installed without any instrumentation
+    #
+    #     OpenTelemetry::SDK.configure
+    #
+    #   Install instrumentation individually with optional config
+    #
+    #     OpenTelemetry::SDK.configure do |c|
+    #       c.use 'OpenTelemetry::Adapters::Faraday', tracer_middleware: SomeMiddleware
+    #     end
+    #
+    #   Install all instrumentation with optional config
+    #
+    #     OpenTelemetry::SDK.configure do |c|
+    #       c.use_all 'OpenTelemetry::Adapters::Faraday' => { tracer_middleware: SomeMiddleware }
+    #     end
+    #
+    #   Add a span processor
+    #
+    #     OpenTelemetry::SDK.configure do |c|
+    #       c.add_span_processor SpanProcessor.new(SomeExporter.new)
+    #     end
+    #
+    #   Configure everything
+    #
+    #     OpenTelemetry::SDK.configure do |c|
+    #       c.logger = Logger.new('/dev/null')
+    #       c.add_span_processor SpanProcessor.new(SomeExporter.new)
+    #       c.use_all
+    #     end
+    def configure
+      configurator = Configurator.new
+      yield configurator if block_given?
+      configurator.configure
+    end
   end
 end
 
+require 'opentelemetry/sdk/configurator'
+require 'opentelemetry/sdk/correlation_context'
 require 'opentelemetry/sdk/internal'
 require 'opentelemetry/sdk/resources'
 require 'opentelemetry/sdk/trace'

data/lib/opentelemetry/sdk/configurator.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    # The configurator provides defaults and facilitates configuring the
+    # SDK for use.
+    class Configurator
+      USE_MODE_UNSPECIFIED = 0
+      USE_MODE_ONE = 1
+      USE_MODE_ALL = 2
+
+      private_constant :USE_MODE_UNSPECIFIED, :USE_MODE_ONE, :USE_MODE_ALL
+
+      attr_writer :logger, :http_extractors, :http_injectors, :text_extractors,
+                  :text_injectors
+
+      def initialize
+        @adapter_names = []
+        @adapter_config_map = {}
+        @http_extractors = nil
+        @http_injectors = nil
+        @text_extractors = nil
+        @text_injectors = nil
+        @span_processors = []
+        @use_mode = USE_MODE_UNSPECIFIED
+        @tracer_provider = Trace::TracerProvider.new
+      end
+
+      def logger
+        @logger ||= Logger.new(STDOUT)
+      end
+
+      # Install an instrumentation adapter with specificied optional +config+.
+      # Use can be called multiple times to install multiple instrumentation
+      # adapters. Only +use+ or +use_all+, but not both when installing
+      # instrumentation. A call to +use_all+ after +use+ will result in an
+      # exception.
+      #
+      # @param [String] adapter_name The name of the instrumentation adapter
+      # @param [optional Hash] config The config for this adapter
+      def use(adapter_name, config = nil)
+        check_use_mode!(USE_MODE_ONE)
+        @adapter_names << adapter_name
+        @adapter_config_map[adapter_name] = config if config
+      end
+
+      # Install all registered instrumentation. Configuration for specific
+      # adapters can be provided with the optional +adapter_config_map+
+      # parameter. Only +use+ or +use_all+, but not both when installing
+      # instrumentation. A call to +use+ after +use_all+ will result in an
+      # exception.
+      #
+      # @param [optional Hash<String,Hash>] adapter_config_map A map with string keys
+      #   representing the adapter name and values specifying the adapter config
+      def use_all(adapter_config_map = {})
+        check_use_mode!(USE_MODE_ALL)
+        @adapter_config_map = adapter_config_map
+      end
+
+      # Add a span processor to the export pipeline
+      #
+      # @param [#on_start, #on_finish, #shutdown] span_processor A span_processor
+      #   that satisfies the duck type #on_start, #on_finish, #shutdown. See
+      #   {SimpleSpanProcessor} for an example.
+      def add_span_processor(span_processor)
+        @span_processors << span_processor
+      end
+
+      # @api private
+      # The configure method is where we define the setup process. This allows
+      # us to make certain guarantees about which systems and globals are setup
+      # at each stage. The setup process is:
+      #   - setup logging
+      #   - setup propagation
+      #   - setup tracer_provider and meter_provider
+      #   - install instrumentation
+      def configure
+        OpenTelemetry.logger = logger
+        OpenTelemetry.correlations = CorrelationContext::Manager.new
+        configure_propagation
+        configure_span_processors
+        OpenTelemetry.tracer_provider = @tracer_provider
+        install_instrumentation
+      end
+
+      private
+
+      def check_use_mode!(mode)
+        @use_mode = mode if @use_mode == USE_MODE_UNSPECIFIED
+        raise 'Use either `use_all` or `use`, but not both' unless @use_mode == mode
+      end
+
+      def install_instrumentation
+        case @use_mode
+        when USE_MODE_ONE
+          OpenTelemetry.instrumentation_registry.install(@adapter_names, @adapter_config_map)
+        when USE_MODE_ALL
+          OpenTelemetry.instrumentation_registry.install_all(@adapter_config_map)
+        end
+      end
+
+      def configure_span_processors
+        processors = @span_processors.empty? ? [default_span_processor] : @span_processors
+        processors.each { |p| @tracer_provider.add_span_processor(p) }
+      end
+
+      def default_span_processor
+        Trace::Export::SimpleSpanProcessor.new(
+          Trace::Export::ConsoleSpanExporter.new
+        )
+      end
+
+      def configure_propagation
+        OpenTelemetry.propagation.http = create_propagator(@http_injectors || default_http_injectors,
+                                                           @http_extractors || default_http_extractors)
+        OpenTelemetry.propagation.text = create_propagator(@text_injectors || default_text_injectors,
+                                                           @text_extractors || default_text_extractors)
+      end
+
+      def create_propagator(injectors, extractors)
+        if injectors.size > 1 || extractors.size > 1
+          Context::Propagation::CompositePropagator.new(injectors, extractors)
+        else
+          Context::Propagation::Propagator.new(injectors, extractors)
+        end
+      end
+
+      def default_http_injectors
+        default_text_injectors
+      end
+
+      def default_http_extractors
+        [
+          OpenTelemetry::Trace::Propagation::TraceContext.rack_extractor,
+          OpenTelemetry::CorrelationContext::Propagation.rack_extractor
+        ]
+      end
+
+      def default_text_injectors
+        [
+          OpenTelemetry::Trace::Propagation::TraceContext.text_injector,
+          OpenTelemetry::CorrelationContext::Propagation.text_injector
+        ]
+      end
+
+      def default_text_extractors
+        [
+          OpenTelemetry::Trace::Propagation::TraceContext.text_extractor,
+          OpenTelemetry::CorrelationContext::Propagation.text_extractor
+        ]
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/correlation_context.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/sdk/correlation_context/builder'
+require 'opentelemetry/sdk/correlation_context/manager'
+
+module OpenTelemetry
+  module SDK
+    # Contains operational implementataions of the CorrelationContext::Manager
+    module CorrelationContext
+    end
+  end
+end

data/lib/opentelemetry/sdk/correlation_context/builder.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module CorrelationContext
+      # SDK implementation of CorrelationContext::Builder
+      class Builder
+        attr_reader :entries
+
+        def initialize(entries)
+          @entries = entries
+        end
+
+        # Set key-value in the to-be-created correlation context
+        #
+        # @param [String] key The key to store this value under
+        # @param [String] value String value to be stored under key
+        def set_value(key, value)
+          @entries[key] = value.to_s
+        end
+
+        # Removes key from the to-be-created correlation context
+        #
+        # @param [String] key The key to remove
+        def remove_value(key)
+          @entries.delete(key)
+        end
+
+        # Clears all correlations from the to-be-created correlation context
+        def clear
+          @entries.clear
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/correlation_context/manager.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module CorrelationContext
+      # Manages correlation context
+      class Manager
+        CORRELATION_CONTEXT_KEY = OpenTelemetry::CorrelationContext::Propagation::ContextKeys.correlation_context_key
+        EMPTY_CORRELATION_CONTEXT = {}.freeze
+        private_constant(:CORRELATION_CONTEXT_KEY, :EMPTY_CORRELATION_CONTEXT)
+
+        # Used to chain modifications to correlation context. The result is a
+        # context with an updated correlation context. If only a single
+        # modification is being made to correlation context, use the other
+        # methods on +Manager+, if multiple modifications are being made, use
+        # this one.
+        #
+        # @param [optional Context] context The context to update with with new
+        #   modified correlation context. Defaults to +Context.current+
+        # @return [Context]
+        def build_context(context: Context.current)
+          builder = Builder.new(correlations_for(context).dup)
+          yield builder
+          context.set_value(CORRELATION_CONTEXT_KEY, builder.entries)
+        end
+
+        # Returns a new context with empty correlations
+        #
+        # @param [optional Context] context Context to clear correlations from. Defaults
+        #   to +Context.current+
+        # @return [Context]
+        def clear(context: Context.current)
+          context.set_value(CORRELATION_CONTEXT_KEY, EMPTY_CORRELATION_CONTEXT)
+        end
+
+        # Returns the corresponding correlation value (or nil) for key
+        #
+        # @param [String] key The lookup key
+        # @param [optional Context] context The context from which to retrieve
+        #   the key.
+        #   Defaults to +Context.current+
+        # @return [String]
+        def value(key, context: Context.current)
+          correlations_for(context)[key]
+        end
+
+        # Returns a new context with new key-value pair
+        #
+        # @param [String] key The key to store this value under
+        # @param [String] value String value to be stored under key
+        # @param [optional Context] context The context to update with new
+        #   value. Defaults to +Context.current+
+        # @return [Context]
+        def set_value(key, value, context: Context.current)
+          new_correlations = correlations_for(context).dup
+          new_correlations[key] = value
+          context.set_value(CORRELATION_CONTEXT_KEY, new_correlations)
+        end
+
+        # Returns a new context with value at key removed
+        #
+        # @param [String] key The key to remove
+        # @param [optional Context] context The context to remove correlation
+        #   from. Defaults to +Context.current+
+        # @return [Context]
+        def remove_value(key, context: Context.current)
+          correlations = correlations_for(context)
+          return context unless correlations.key?(key)
+
+          new_correlations = correlations.dup
+          new_correlations.delete(key)
+          context.set_value(CORRELATION_CONTEXT_KEY, new_correlations)
+        end
+
+        private
+
+        def correlations_for(context)
+          context.value(CORRELATION_CONTEXT_KEY) || EMPTY_CORRELATION_CONTEXT
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/internal.rb

@@ -20,10 +20,30 @@ module OpenTelemetry
         key.instance_of?(String)
       end
 
-      def valid_value?(value)
+      def valid_simple_value?(value)
         value.instance_of?(String) || value == false || value == true || value.is_a?(Numeric)
       end
 
+      def valid_array_value?(value)
+        return false unless value.is_a?(Array)
+        return true if value.empty?
+
+        case value.first
+        when String
+          value.all? { |v| v.instance_of?(String) }
+        when TrueClass, FalseClass
+          value.all? { |v| boolean?(v) }
+        when Numeric
+          value.all? { |v| v.is_a?(Numeric) }
+        else
+          false
+        end
+      end
+
+      def valid_value?(value)
+        valid_simple_value?(value) || valid_array_value?(value)
+      end
+
       def valid_attributes?(attrs)
         attrs.nil? || attrs.all? { |k, v| valid_key?(k) && valid_value?(v) }
       end

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

@@ -15,15 +15,16 @@ module OpenTelemetry
 
           # Returns a newly created {Resource} with the specified labels
           #
-          # @param [Hash<String, String>] labels Hash of key-value pairs to be used
+          # @param [Hash{String => String, Numeric, Boolean} labels Hash of key-value pairs to be used
           #   as labels for this resource
           # @raise [ArgumentError] If label keys and values are not strings
           # @return [Resource]
           def create(labels = {})
             frozen_labels = labels.each_with_object({}) do |(k, v), memo|
-              raise ArgumentError, 'label keys and values must be strings' unless k.is_a?(String) && v.is_a?(String)
+              raise ArgumentError, 'label keys must be strings' unless k.is_a?(String)
+              raise ArgumentError, 'label values must be strings, integers, floats, or booleans' unless Internal.valid_value?(v)
 
-              memo[-k] = -v
+              memo[-k] = v.freeze
             end.freeze
 
             new(frozen_labels)

data/lib/opentelemetry/sdk/trace.rb

@@ -21,4 +21,4 @@ require 'opentelemetry/sdk/trace/noop_span_processor'
 require 'opentelemetry/sdk/trace/span_data'
 require 'opentelemetry/sdk/trace/span'
 require 'opentelemetry/sdk/trace/tracer'
-require 'opentelemetry/sdk/trace/tracer_factory'
+require 'opentelemetry/sdk/trace/tracer_provider'

data/lib/opentelemetry/sdk/trace/export/batch_span_processor.rb

@@ -72,6 +72,23 @@ module OpenTelemetry
             end
           end
 
+          # TODO: test this explicitly.
+          # Export all ended spans to the configured `Exporter` that have not yet
+          # been exported.
+          #
+          # This method should only be called in cases where it is absolutely
+          # necessary, such as when using some FaaS providers that may suspend
+          # the process after an invocation, but before the `Processor` exports
+          # the completed spans.
+          def force_flush
+            snapshot = lock { spans.shift(spans.size) }
+            until snapshot.empty?
+              batch = snapshot.shift(@batch_size).map!(&:to_span_data)
+              result_code = @exporter.export(batch)
+              report_result(result_code, batch)
+            end
+          end
+
           # shuts the consumer thread down and flushes the current accumulated buffer
           # will block until the thread is finished
           def shutdown
@@ -81,7 +98,7 @@ module OpenTelemetry
             end
 
             @thread.join
-            flush
+            force_flush
             @exporter.shutdown
           end
 
@@ -124,15 +141,6 @@ module OpenTelemetry
             OpenTelemetry.logger.error("Unable to export #{batch.size} spans") unless result_code == SUCCESS
           end
 
-          def flush
-            snapshot = lock { spans.shift(spans.size) }
-            until snapshot.empty?
-              batch = snapshot.shift(@batch_size).map!(&:to_span_data)
-              result_code = @exporter.export(batch)
-              report_result(result_code, batch)
-            end
-          end
-
           def fetch_batch
             spans.shift(@batch_size).map!(&:to_span_data)
           end

data/lib/opentelemetry/sdk/trace/export/in_memory_span_exporter.rb

@@ -14,13 +14,13 @@ module OpenTelemetry
         #
         # class MyClassTest
         #   def setup
-        #     @tracer_factory = TracerFactory.new
+        #     @tracer_provider = TracerProvider.new
         #     @exporter = InMemorySpanExporter.new
-        #     @tracer_factory.add_span_processor(SimpleSampledSpansProcessor.new(@exporter))
+        #     @tracer_provider.add_span_processor(SimpleSampledSpansProcessor.new(@exporter))
         #   end
         #
         #   def test_finished_spans
-        #     @tracer_factory.tracer.in_span("span") {}
+        #     @tracer_provider.tracer.in_span("span") {}
         #
         #     spans = @exporter.finished_spans
         #     spans.wont_be_nil
@@ -71,8 +71,8 @@ module OpenTelemetry
             SUCCESS
           end
 
-          # Called when {TracerFactory#shutdown} is called, if this exporter is
-          # registered to a {TracerFactory} object.
+          # Called when {TracerProvider#shutdown} is called, if this exporter is
+          # registered to a {TracerProvider} object.
           def shutdown
             @mutex.synchronize do
               @finished_spans.clear

data/lib/opentelemetry/sdk/trace/export/multi_span_exporter.rb

@@ -35,8 +35,8 @@ module OpenTelemetry
             end
           end
 
-          # Called when {TracerFactory#shutdown} is called, if this exporter is
-          # registered to a {TracerFactory} object.
+          # Called when {TracerProvider#shutdown} is called, if this exporter is
+          # registered to a {TracerProvider} object.
           def shutdown
             @span_exporters.each(&:shutdown)
           end

data/lib/opentelemetry/sdk/trace/export/noop_span_exporter.rb

@@ -12,7 +12,7 @@ module OpenTelemetry
         # duck type. SpanExporter allows different tracing services to export
         # recorded data for sampled spans in their own format.
         #
-        # To export data an exporter MUST be registered to the {TracerFactory} using
+        # To export data an exporter MUST be registered to the {TracerProvider} using
         # a {SimpleSpanProcessor} or a {BatchSpanProcessor}.
         class NoopSpanExporter
           def initialize
@@ -30,8 +30,8 @@ module OpenTelemetry
             FAILED_NOT_RETRYABLE
           end
 
-          # Called when {TracerFactory#shutdown} is called, if this exporter is
-          # registered to a {TracerFactory} object.
+          # Called when {TracerProvider#shutdown} is called, if this exporter is
+          # registered to a {TracerProvider} object.
           def shutdown
             @stopped = true
           end

data/lib/opentelemetry/sdk/trace/export/simple_span_processor.rb

@@ -52,7 +52,16 @@ module OpenTelemetry
             OpenTelemetry.logger.error("unexpected error in span.on_finish - #{e}")
           end
 
-          # Called when {TracerFactory#shutdown} is called.
+          # Export all ended spans to the configured `Exporter` that have not yet
+          # been exported.
+          #
+          # This method should only be called in cases where it is absolutely
+          # necessary, such as when using some FaaS providers that may suspend
+          # the process after an invocation, but before the `Processor` exports
+          # the completed spans.
+          def force_flush; end
+
+          # Called when {TracerProvider#shutdown} is called.
           def shutdown
             @span_exporter&.shutdown
           end

data/lib/opentelemetry/sdk/trace/multi_span_processor.rb

@@ -41,7 +41,18 @@ module OpenTelemetry
           @span_processors.each { |processor| processor.on_finish(span) }
         end
 
-        # Called when {TracerFactory#shutdown} is called.
+        # Export all ended spans to the configured `Exporter` that have not yet
+        # been exported.
+        #
+        # This method should only be called in cases where it is absolutely
+        # necessary, such as when using some FaaS providers that may suspend
+        # the process after an invocation, but before the `Processor` exports
+        # the completed spans.
+        def force_flush
+          @span_processors.each(&:force_flush)
+        end
+
+        # Called when {TracerProvider#shutdown} is called.
         def shutdown
           @span_processors.each(&:shutdown)
         end

data/lib/opentelemetry/sdk/trace/noop_span_processor.rb

@@ -33,7 +33,16 @@ module OpenTelemetry
         # @param [Span] span the {Span} that just ended.
         def on_finish(span); end
 
-        # Called when {TracerFactory#shutdown} is called.
+        # Export all ended spans to the configured `Exporter` that have not yet
+        # been exported.
+        #
+        # This method should only be called in cases where it is absolutely
+        # necessary, such as when using some FaaS providers that may suspend
+        # the process after an invocation, but before the `Processor` exports
+        # the completed spans.
+        def force_flush; end
+
+        # Called when {TracerProvider#shutdown} is called.
         def shutdown; end
       end
     end

data/lib/opentelemetry/sdk/trace/samplers.rb

@@ -18,7 +18,7 @@ module OpenTelemetry
       # Custom samplers can be provided by SDK users. The required interface is
       # a callable with the signature:
       #
-      #   (trace_id:, span_id:, parent_context:, hint:, links:, name:, kind:, attributes:) -> Result
+      #   (trace_id:, span_id:, parent_context:, links:, name:, kind:, attributes:) -> Result
       #
       # Where:
       #
@@ -27,8 +27,6 @@ module OpenTelemetry
       # @param [OpenTelemetry::Trace::SpanContext] parent_context The
       #   {OpenTelemetry::Trace::SpanContext} of a parent span, typically
       #   extracted from the wire. Can be nil for a root span.
-      # @param [Symbol] hint A {OpenTelemetry::Trace::SamplingHint} about
-      #   whether the {Span} should be sampled and/or record events.
       # @param [Enumerable<Link>] links A collection of links to be associated
       #   with the {Span} to be created. Can be nil.
       # @param [String] name Name of the {Span} to be created.
@@ -48,19 +46,17 @@ module OpenTelemetry
 
         # rubocop:disable Lint/UnusedBlockArgument
 
-        # Ignores all values in hint and returns a {Result} with
-        # {Decision::RECORD_AND_SAMPLED}.
-        ALWAYS_ON = ->(trace_id:, span_id:, parent_context:, hint:, links:, name:, kind:, attributes:) { RECORD_AND_SAMPLED }
+        # Returns a {Result} with {Decision::RECORD_AND_SAMPLED}.
+        ALWAYS_ON = ->(trace_id:, span_id:, parent_context:, links:, name:, kind:, attributes:) { RECORD_AND_SAMPLED }
 
-        # Ignores all values in hint and returns a {Result} with
-        # {Decision::NOT_RECORD}.
-        ALWAYS_OFF = ->(trace_id:, span_id:, parent_context:, hint:, links:, name:, kind:, attributes:) { NOT_RECORD }
+        # Returns a {Result} with {Decision::NOT_RECORD}.
+        ALWAYS_OFF = ->(trace_id:, span_id:, parent_context:, links:, name:, kind:, attributes:) { NOT_RECORD }
 
-        # Ignores all values in hint and returns a {Result} with
-        # {Decision::RECORD_AND_SAMPLED} if the parent context is sampled or
-        # {Decision::NOT_RECORD} otherwise, or if there is no parent context.
+        # Returns a {Result} with {Decision::RECORD_AND_SAMPLED} if the parent
+        # context is sampled or {Decision::NOT_RECORD} otherwise, or if there
+        # is no parent context.
         # rubocop:disable Style/Lambda
-        ALWAYS_PARENT = ->(trace_id:, span_id:, parent_context:, hint:, links:, name:, kind:, attributes:) do
+        ALWAYS_PARENT = ->(trace_id:, span_id:, parent_context:, links:, name:, kind:, attributes:) do
           if parent_context&.trace_flags&.sampled?
             RECORD_AND_SAMPLED
           else
@@ -75,8 +71,6 @@ module OpenTelemetry
         #
         # @param [Numeric] probability The desired probability of sampling.
         #   Must be within [0.0, 1.0].
-        # @param [optional Enumerable<Symbol>] ignore_hints Sampling hints to
-        #   ignore. Defaults to ignore {OpenTelemetry::Trace::SamplingHint::RECORD}.
         # @param [optional Boolean] ignore_parent Whether to ignore parent
         #   sampling. Defaults to not ignore parent sampling.
         # @param [optional Symbol] apply_probability_to Whether to apply
@@ -84,18 +78,14 @@ module OpenTelemetry
         #   or all spans. Allowed values include :root_spans, :root_spans_and_remote_parent,
         #   and :all_spans. Defaults to :root_spans_and_remote_parent.
         # @raise [ArgumentError] if probability is out of range
-        # @raise [ArgumentError] if ignore_hints contains invalid hints
         # @raise [ArgumentError] if apply_probability_to is not one of the allowed symbols
         def self.probability(probability,
-                             ignore_hints: [OpenTelemetry::Trace::SamplingHint::RECORD],
                              ignore_parent: false,
                              apply_probability_to: :root_spans_and_remote_parent)
           raise ArgumentError, 'probability must be in range [0.0, 1.0]' unless (0.0..1.0).include?(probability)
-          raise ArgumentError, 'ignore_hints' unless (ignore_hints.to_a - SAMPLING_HINTS).empty?
           raise ArgumentError, 'apply_probability_to' unless APPLY_PROBABILITY_TO_SYMBOLS.include?(apply_probability_to)
 
           ProbabilitySampler.new(probability,
-                                 ignore_hints: ignore_hints.to_a,
                                  ignore_parent: ignore_parent,
                                  apply_to_remote_parent: apply_probability_to != :root_spans,
                                  apply_to_all_spans: apply_probability_to == :all_spans)

data/lib/opentelemetry/sdk/trace/samplers/decision.rb

@@ -12,13 +12,13 @@ module OpenTelemetry
         # decision part of a sampling {Result}.
         module Decision
           # Decision to not record events and not sample.
-          NOT_RECORD = OpenTelemetry::Trace::SamplingHint::NOT_RECORD
+          NOT_RECORD = :__not_record__
 
           # Decision to record events and not sample.
-          RECORD = OpenTelemetry::Trace::SamplingHint::RECORD
+          RECORD = :__record__
 
           # Decision to record events and sample.
-          RECORD_AND_SAMPLED = OpenTelemetry::Trace::SamplingHint::RECORD_AND_SAMPLED
+          RECORD_AND_SAMPLED = :__record_and_sampled__
         end
       end
     end

data/lib/opentelemetry/sdk/trace/samplers/probability_sampler.rb

@@ -12,15 +12,9 @@ module OpenTelemetry
         #
         # Implements sampling based on a probability.
         class ProbabilitySampler
-          HINT_RECORD_AND_SAMPLED = OpenTelemetry::Trace::SamplingHint::RECORD_AND_SAMPLED
-          HINT_RECORD = OpenTelemetry::Trace::SamplingHint::RECORD
-
-          private_constant(:HINT_RECORD_AND_SAMPLED, :HINT_RECORD)
-
-          def initialize(probability, ignore_hints:, ignore_parent:, apply_to_remote_parent:, apply_to_all_spans:)
+          def initialize(probability, ignore_parent:, apply_to_remote_parent:, apply_to_all_spans:)
             @probability = probability
             @id_upper_bound = format('%016x', (probability * (2**64 - 1)).ceil)
-            @ignored_hints = ignore_hints
             @use_parent_sampled_flag = !ignore_parent
             @apply_to_remote_parent = apply_to_remote_parent
             @apply_to_all_spans = apply_to_all_spans
@@ -29,18 +23,11 @@ module OpenTelemetry
           # @api private
           #
           # Callable interface for probability sampler. See {Samplers}.
-          def call(trace_id:, span_id:, parent_context:, hint:, links:, name:, kind:, attributes:)
+          def call(trace_id:, span_id:, parent_context:, links:, name:, kind:, attributes:)
             # Ignored for sampling decision: links, name, kind, attributes.
 
-            hint = nil if @ignored_hints.include?(hint)
-
-            sampled = sample?(hint, trace_id, parent_context)
-            recording = hint == HINT_RECORD || sampled
-
-            if sampled && recording
+            if sample?(trace_id, parent_context)
               RECORD_AND_SAMPLED
-            elsif recording
-              RECORD
             else
               NOT_RECORD
             end
@@ -48,11 +35,11 @@ module OpenTelemetry
 
           private
 
-          def sample?(hint, trace_id, parent_context)
+          def sample?(trace_id, parent_context)
             if parent_context.nil?
-              hint == HINT_RECORD_AND_SAMPLED || sample_trace_id?(trace_id)
+              sample_trace_id?(trace_id)
             else
-              parent_sampled?(parent_context) || hint == HINT_RECORD_AND_SAMPLED || sample_trace_id_for_child?(parent_context, trace_id)
+              parent_sampled?(parent_context) || sample_trace_id_for_child?(parent_context, trace_id)
             end
           end
 

data/lib/opentelemetry/sdk/trace/samplers/result.rb

@@ -19,7 +19,7 @@ module OpenTelemetry
 
           # Returns a frozen hash of attributes to be attached span.
           #
-          # @return [Hash<String, Object>]
+          # @return [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
           attr_reader :attributes
 
           # Returns a new sampling result with the specified decision and
@@ -27,8 +27,9 @@ module OpenTelemetry
           #
           # @param [Symbol] decision Whether or not a span should be sampled
           #   and/or record events.
-          # @param [optional Hash<String, Object>] attributes A frozen or freezable hash
-          #   containing attributes to be attached to the span.
+          # @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+          #   attributes A frozen or freezable hash containing attributes to be
+          #   attached to the span.
           def initialize(decision:, attributes: nil)
             @decision = decision
             @attributes = attributes.freeze || EMPTY_HASH

data/lib/opentelemetry/sdk/trace/span.rb

@@ -24,7 +24,7 @@ module OpenTelemetry
         # use of SpanProcesses and should not be considered part of the public
         # interface for instrumentation.
         #
-        # @return [Hash<String, Object>] may be nil.
+        # @return [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}] may be nil.
         def attributes
           # Don't bother synchronizing. Access by SpanProcessors is expected to
           # be serialized.
@@ -90,16 +90,16 @@ module OpenTelemetry
         #   span.add_event { OpenTelemetry::Trace::Event.new(name: 'event', attributes: {'eager' => false}) }
         #
         # Note that the OpenTelemetry project
-        # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/semantic-conventions.md
+        # {https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md
         # documents} certain "standard event names and keys" which have
         # prescribed semantic meanings.
         #
         # @param [optional String] name Optional name of the event. This is
         #   required if a block is not given.
-        # @param [optional Hash<String, Object>] attributes One or more key:value
-        #   pairs, where the keys must be strings and the values may be string,
-        #   boolean or numeric type. This argument should only be used when
-        #   passing in a name.
+        # @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}] attributes
+        #   One or more key:value pairs, where the keys must be strings and the
+        #   values may be string, boolean or numeric type. This argument should
+        #   only be used when passing in a name.
         # @param [optional Time] timestamp Optional timestamp for the event.
         #   This argument should only be used when passing in a name.
         #
@@ -107,6 +107,7 @@ module OpenTelemetry
         def add_event(name: nil, attributes: nil, timestamp: nil)
           super
           event = block_given? ? yield : OpenTelemetry::Trace::Event.new(name: name, attributes: attributes, timestamp: timestamp || Time.now)
+
           @mutex.synchronize do
             if @ended
               OpenTelemetry.logger.warn('Calling add_event on an ended Span.')
@@ -119,6 +120,21 @@ module OpenTelemetry
           self
         end
 
+        # Record an error during the execution of this span. Multiple errors
+        # can be recorded on a span.
+        #
+        # @param [Exception] error The error to be recorded
+        #
+        # @return [void]
+        def record_error(error)
+          add_event(name: 'error',
+                    attributes: {
+                      'error.type' => error.class.to_s,
+                      'error.message' => error.message,
+                      'error.stack' => error.backtrace.join("\n")
+                    })
+        end
+
         # Sets the Status to the Span
         #
         # If used, this will override the default Span status. Default is OK.

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

@@ -26,23 +26,22 @@ module OpenTelemetry
           @resource = Resources::Resource.create('name' => name, 'version' => version)
         end
 
-        def start_root_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil, sampling_hint: nil)
-          parent_span_context = OpenTelemetry::Trace::SpanContext::INVALID
-          start_span(name, with_parent_context: parent_span_context, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind, sampling_hint: sampling_hint)
+        def start_root_span(name, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
+          start_span(name, with_parent_context: Context.empty, attributes: attributes, links: links, start_timestamp: start_timestamp, kind: kind)
         end
 
-        def start_span(name, with_parent: nil, with_parent_context: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil, sampling_hint: nil) # rubocop:disable Metrics/AbcSize
+        def start_span(name, with_parent: nil, with_parent_context: nil, attributes: nil, links: nil, start_timestamp: nil, kind: nil)
           name ||= 'empty'
 
-          parent_span_context = with_parent&.context || with_parent_context || current_span.context
+          parent_span_context = with_parent&.context || active_span_context(with_parent_context)
           parent_span_context = nil unless parent_span_context.valid?
           parent_span_id = parent_span_context&.span_id
           tracestate = parent_span_context&.tracestate
           trace_id = parent_span_context&.trace_id
           trace_id ||= OpenTelemetry::Trace.generate_trace_id
           span_id = OpenTelemetry::Trace.generate_span_id
-          sampler = OpenTelemetry.tracer_factory.active_trace_config.sampler
-          result = sampler.call(trace_id: trace_id, span_id: span_id, parent_context: parent_span_context, hint: sampling_hint, links: links, name: name, kind: kind, attributes: attributes)
+          sampler = OpenTelemetry.tracer_provider.active_trace_config.sampler
+          result = sampler.call(trace_id: trace_id, span_id: span_id, parent_context: parent_span_context, links: links, name: name, kind: kind, attributes: attributes)
 
           internal_create_span(result, name, kind, trace_id, span_id, parent_span_id, attributes, links, start_timestamp, tracestate)
         end
@@ -50,12 +49,12 @@ module OpenTelemetry
         private
 
         def internal_create_span(result, name, kind, trace_id, span_id, parent_span_id, attributes, links, start_timestamp, tracestate) # rubocop:disable Metrics/AbcSize
-          if result.recording? && !OpenTelemetry.tracer_factory.stopped?
+          if result.recording? && !OpenTelemetry.tracer_provider.stopped?
             trace_flags = result.sampled? ? OpenTelemetry::Trace::TraceFlags::SAMPLED : OpenTelemetry::Trace::TraceFlags::DEFAULT
             context = OpenTelemetry::Trace::SpanContext.new(trace_id: trace_id, trace_flags: trace_flags, tracestate: tracestate)
             attributes = attributes&.merge(result.attributes) || result.attributes
-            active_trace_config = OpenTelemetry.tracer_factory.active_trace_config
-            active_span_processor = OpenTelemetry.tracer_factory.active_span_processor
+            active_trace_config = OpenTelemetry.tracer_provider.active_trace_config
+            active_span_processor = OpenTelemetry.tracer_provider.active_span_processor
             Span.new(context, name, kind, parent_span_id, active_trace_config, active_span_processor, attributes, links, start_timestamp || Time.now, @resource)
           else
             OpenTelemetry::Trace::Span.new(span_context: OpenTelemetry::Trace::SpanContext.new(trace_id: trace_id))

data/lib/opentelemetry/sdk/trace/{tracer_factory.rb → tracer_provider.rb}

@@ -7,8 +7,8 @@
 module OpenTelemetry
   module SDK
     module Trace
-      # {TracerFactory} is the SDK implementation of {OpenTelemetry::Trace::TracerFactory}.
-      class TracerFactory < OpenTelemetry::Trace::TracerFactory
+      # {TracerProvider} is the SDK implementation of {OpenTelemetry::Trace::TracerProvider}.
+      class TracerProvider < OpenTelemetry::Trace::TracerProvider
         Key = Struct.new(:name, :version)
         private_constant(:Key)
 
@@ -17,9 +17,9 @@ module OpenTelemetry
         attr_reader :stopped
         alias stopped? stopped
 
-        # Returns a new {TracerFactory} instance.
+        # Returns a new {TracerProvider} instance.
         #
-        # @return [TracerFactory]
+        # @return [TracerProvider]
         def initialize
           @mutex = Mutex.new
           @registry = {}
@@ -75,7 +75,7 @@ module OpenTelemetry
               return
             end
             @registered_span_processors << span_processor
-            @active_span_processor = MultiSpanProcessor.new(@registered_span_processors)
+            @active_span_processor = MultiSpanProcessor.new(@registered_span_processors.dup)
           end
         end
       end

data/lib/opentelemetry/sdk/version.rb

@@ -7,6 +7,6 @@
 module OpenTelemetry
   module SDK
     ## Current OpenTelemetry version
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-sdk
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-13 00:00:00.000000000 Z
+date: 2020-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.0'
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.0'
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -143,9 +143,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE
+- README.md
+- lib/opentelemetry-sdk.rb
 - lib/opentelemetry/sdk.rb
+- lib/opentelemetry/sdk/configurator.rb
+- lib/opentelemetry/sdk/correlation_context.rb
+- lib/opentelemetry/sdk/correlation_context/builder.rb
+- lib/opentelemetry/sdk/correlation_context/manager.rb
 - lib/opentelemetry/sdk/internal.rb
 - lib/opentelemetry/sdk/resources.rb
 - lib/opentelemetry/sdk/resources/resource.rb
@@ -168,7 +175,7 @@ files:
 - lib/opentelemetry/sdk/trace/span.rb
 - lib/opentelemetry/sdk/trace/span_data.rb
 - lib/opentelemetry/sdk/trace/tracer.rb
-- lib/opentelemetry/sdk/trace/tracer_factory.rb
+- lib/opentelemetry/sdk/trace/tracer_provider.rb
 - lib/opentelemetry/sdk/version.rb
 homepage: https://github.com/open-telemetry/opentelemetry-ruby
 licenses: