opentelemetry-sdk 0.2.0 → 0.6.0

data/lib/opentelemetry/sdk/instrumentation_library.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    # InstrumentationLibrary is a struct containing library information for export.
+    InstrumentationLibrary = Struct.new(:name,
+                                        :version)
+  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.rb

@@ -13,3 +13,4 @@ module OpenTelemetry
 end
 
 require 'opentelemetry/sdk/resources/resource'
+require 'opentelemetry/sdk/resources/constants'

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# Copyright 2020 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Resources
+      module Constants
+        # Attributes describing a service instance.
+        SERVICE_RESOURCE = {
+          # Logical name of the service.
+          name: 'service.name',
+
+          # A namespace for `service.name`.
+          namespace: 'service.namespace',
+
+          # The string ID of the service instance.
+          instance_id: 'service.instance.id',
+
+          # The version string of the service API or implementation.
+          version: 'service.version'
+        }.freeze
+
+        # Attributes describing the telemetry library.
+        TELEMETRY_SDK_RESOURCE = {
+          # The name of the telemetry library.
+          name: 'telemetry.sdk.name',
+
+          # The language of the telemetry library and of the code instrumented with it.
+          language: 'telemetry.sdk.language',
+
+          # The version string of the telemetry library
+          version: 'telemetry.sdk.version'
+        }.freeze
+
+        # Attributes defining a compute unit (e.g. Container, Process, Lambda
+        # Function).
+        CONTAINER_RESOURCE = {
+          # The container name.
+          name: 'container.name',
+
+          # The name of the image the container was built on.
+          image_name: 'container.image.name',
+
+          # The container image tag.
+          image_tag: 'container.image.tag'
+        }.freeze
+
+        FAAS_RESOURCE = {
+          # The name of the function being executed.
+          name: 'faas.name',
+
+          # The unique name of the function being executed.
+          id: 'faas.id',
+
+          # The version string of the function being executed.
+          version: 'faas.version',
+
+          # The execution environment ID as a string.
+          instance: 'faas.instance'
+        }.freeze
+
+        # Attributes defining a deployment service (e.g. Kubernetes).
+        K8S_RESOURCE = {
+          # The name of the cluster that the pod is running in.
+          cluster_name: 'k8s.cluster.name',
+
+          # The name of the namespace that the pod is running in.
+          namespace_name: 'k8s.namespace.name',
+
+          # The name of the pod.
+          pod_name: 'k8s.pod.name',
+
+          # The name of the deployment.
+          deployment_name: 'k8s.deployment.name'
+        }.freeze
+
+        # Attributes defining a computing instance (e.g. host).
+        HOST_RESOURCE = {
+          # Hostname of the host. It contains what the hostname command returns on the
+          # host machine.
+          hostname: 'host.hostname',
+
+          # Unique host id. For Cloud this must be the instance_id assigned by the
+          # cloud provider
+          id: 'host.id',
+
+          # Name of the host. It may contain what hostname returns on Unix systems,
+          # the fully qualified, or a name specified by the user.
+          name: 'host.name',
+
+          # Type of host. For Cloud this must be the machine type.
+          type: 'host.type',
+
+          # Name of the VM image or OS install the host was instantiated from.
+          image_name: 'host.image.name',
+
+          # VM image id. For Cloud, this value is from the provider.
+          image_id: 'host.image.id',
+
+          # The version string of the VM image.
+          image_version: 'host.image.version'
+        }.freeze
+
+        # Attributes defining a running environment (e.g. Cloud, Data Center).
+        CLOUD_RESOURCE = {
+          # Name of the cloud provider. Example values are aws, azure, gcp.
+          provider: 'cloud.provider',
+
+          # The cloud account id used to identify different entities.
+          account_id: 'cloud.account.id',
+
+          # A specific geographical location where different entities can run.
+          region: 'cloud.region',
+
+          # Zones are a sub set of the region connected through low-latency links.
+          zone: 'cloud.zone'
+        }.freeze
+      end
+    end
+  end
+end

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

@@ -13,20 +13,40 @@ module OpenTelemetry
         class << self
           private :new # rubocop:disable Style/AccessModifierDeclarations
 
-          # Returns a newly created {Resource} with the specified labels
+          # Returns a newly created {Resource} with the specified attributes
           #
-          # @param [Hash<String, String>] labels Hash of key-value pairs to be used
-          #   as labels for this resource
-          # @raise [ArgumentError] If label keys and values are not strings
+          # @param [Hash{String => String, Numeric, Boolean} attributes Hash of key-value pairs to be used
+          #   as attributes for this resource
+          # @raise [ArgumentError] If attribute 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)
+          def create(attributes = {})
+            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 strings, integers, floats, or booleans' unless Internal.valid_value?(v)
 
-              memo[-k] = -v
+              memo[-k] = v.freeze
             end.freeze
 
-            new(frozen_labels)
+            new(frozen_attributes)
+          end
+
+          def telemetry_sdk
+            resource_attributes = {
+              Constants::TELEMETRY_SDK_RESOURCE[:name] => 'opentelemetry',
+              Constants::TELEMETRY_SDK_RESOURCE[:language] => 'ruby',
+              Constants::TELEMETRY_SDK_RESOURCE[:version] => OpenTelemetry::SDK::VERSION
+            }
+
+            resource_pairs = ENV['OTEL_RESOURCE_ATTRIBUTES']
+            return create(resource_attributes) unless resource_pairs.is_a?(String)
+
+            resource_pairs.split(',').each do |pair|
+              key, value = pair.split('=')
+              resource_attributes[key] = value
+            end
+
+            resource_attributes.delete_if { |_key, value| value.nil? || value.empty? }
+            create(resource_attributes)
           end
         end
 
@@ -35,18 +55,18 @@ module OpenTelemetry
         # Users should use the {create} factory method to obtain a {Resource}
         # instance.
         #
-        # @param [Hash<String, String>] frozen_labels Frozen-hash of frozen-string
-        #  key-value pairs to be used as labels for this resource
+        # @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_labels)
-          @labels = frozen_labels
+        def initialize(frozen_attributes)
+          @attributes = frozen_attributes
         end
 
-        # Returns an enumerator for labels of this {Resource}
+        # Returns an enumerator for attributes of this {Resource}
         #
         # @return [Enumerator]
-        def label_enumerator
-          @label_enumerator ||= labels.to_enum
+        def attribute_enumerator
+          @attribute_enumerator ||= attributes.to_enum
         end
 
         # Returns a new, merged {Resource} by merging the current {Resource} with
@@ -59,16 +79,16 @@ module OpenTelemetry
         def merge(other)
           return self unless other.is_a?(Resource)
 
-          merged_labels = labels.merge(other.labels) do |_, old_v, new_v|
+          merged_attributes = attributes.merge(other.attributes) do |_, old_v, new_v|
             old_v.empty? ? new_v : old_v
           end
 
-          self.class.send(:new, merged_labels.freeze)
+          self.class.send(:new, merged_attributes.freeze)
         end
 
         protected
 
-        attr_reader :labels
+        attr_reader :attributes
       end
     end
   end

data/lib/opentelemetry/sdk/trace.rb

@@ -15,10 +15,11 @@ end
 
 require 'opentelemetry/sdk/trace/samplers'
 require 'opentelemetry/sdk/trace/config'
+require 'opentelemetry/sdk/trace/event'
 require 'opentelemetry/sdk/trace/export'
 require 'opentelemetry/sdk/trace/multi_span_processor'
 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/config/trace_config.rb

@@ -10,7 +10,7 @@ module OpenTelemetry
       module Config
         # Class that holds global trace parameters.
         class TraceConfig
-          DEFAULT_SAMPLER = Samplers::ALWAYS_ON
+          DEFAULT_SAMPLER = Samplers.parent_based(root: Samplers::ALWAYS_ON)
           DEFAULT_MAX_ATTRIBUTES_COUNT = 32
           DEFAULT_MAX_EVENTS_COUNT = 128
           DEFAULT_MAX_LINKS_COUNT = 32
@@ -30,13 +30,13 @@ module OpenTelemetry
           # The global default max number of attributes per {Span}.
           attr_reader :max_attributes_count
 
-          # The global default max number of {OpenTelemetry::Trace::Event}s per {Span}.
+          # The global default max number of {OpenTelemetry::SDK::Trace::Event}s per {Span}.
           attr_reader :max_events_count
 
           # The global default max number of {OpenTelemetry::Trace::Link} entries per {Span}.
           attr_reader :max_links_count
 
-          # The global default max number of attributes per {OpenTelemetry::Trace::Event}.
+          # The global default max number of attributes per {OpenTelemetry::SDK::Trace::Event}.
           attr_reader :max_attributes_per_event
 
           # The global default max number of attributes per {OpenTelemetry::Trace::Link}.

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Trace
+      # A text annotation with a set of attributes and a timestamp.
+      class Event
+        EMPTY_ATTRIBUTES = {}.freeze
+
+        private_constant :EMPTY_ATTRIBUTES
+
+        # Returns the name of this event
+        #
+        # @return [String]
+        attr_reader :name
+
+        # Returns the frozen attributes for this event
+        #
+        # @return [Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+        attr_reader :attributes
+
+        # Returns the timestamp for this event
+        #
+        # @return [Time]
+        attr_reader :timestamp
+
+        # Returns a new immutable {Event}.
+        #
+        # @param [String] name The name of this event
+        # @param [optional Hash{String => String, Numeric, Boolean, Array<String, Numeric, Boolean>}]
+        #   attributes A hash of attributes for this event. Attributes will be
+        #   frozen during Event initialization.
+        # @param [optional Time] timestamp The timestamp for this event.
+        #   Defaults to Time.now.
+        # @return [Event]
+        def initialize(name:, attributes: nil, timestamp: nil)
+          @name = name
+          @attributes = attributes.freeze || EMPTY_ATTRIBUTES
+          @timestamp = timestamp || Time.now
+        end
+      end
+    end
+  end
+end

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

@@ -15,13 +15,8 @@ module OpenTelemetry
         # The export operation finished successfully.
         SUCCESS = 0
 
-        # The export operation finished with an error, but retrying may
-        # succeed.
-        FAILED_RETRYABLE = 1
-
-        # The export operation finished with an error, the caller should not
-        # try to export the same data again.
-        FAILED_NOT_RETRYABLE = 2
+        # The export operation finished with an error.
+        FAILURE = 1
       end
     end
   end

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

@@ -22,24 +22,29 @@ module OpenTelemetry
         # If the queue gets half full a preemptive notification is sent to the
         # worker thread that exports the spans to wake up and start a new
         # export cycle.
-        #
-        # max_export_attempts attempts are made to export each batch, while
-        # export fails with {FAILED_RETRYABLE}, backing off linearly in 100ms
-        # increments.
         class BatchSpanProcessor
-          EXPORTER_TIMEOUT_MILLIS = 30_000
-          SCHEDULE_DELAY_MILLIS = 5_000
-          MAX_QUEUE_SIZE = 2048
-          MAX_EXPORT_BATCH_SIZE = 512
-          MAX_EXPORT_ATTEMPTS = 5
-          private_constant(:SCHEDULE_DELAY_MILLIS, :MAX_QUEUE_SIZE, :MAX_EXPORT_BATCH_SIZE, :MAX_EXPORT_ATTEMPTS)
-
+          # Returns a new instance of the {BatchSpanProcessor}.
+          #
+          # @param [SpanExporter] exporter
+          # @param [Numeric] exporter_timeout_millis the delay interval between two
+          #   consecutive exports. Defaults to the value of the OTEL_BSP_EXPORT_TIMEOUT_MILLIS
+          #   environment variable, if set, or 30,000 (30 seconds).
+          # @param [Numeric] schedule_delay_millis the maximum allowed time to export data.
+          #   Defaults to the value of the OTEL_BSP_SCHEDULE_DELAY_MILLIS environment
+          #   variable, if set, or 5,000 (5 seconds).
+          # @param [Integer] max_queue_size the maximum queue size in spans.
+          #   Defaults to the value of the OTEL_BSP_MAX_QUEUE_SIZE environment
+          #   variable, if set, or 2048.
+          # @param [Integer] max_export_batch_size the maximum batch size in spans.
+          #   Defaults to the value of the OTEL_BSP_MAX_EXPORT_BATCH_SIZE environment
+          #   variable, if set, or 512.
+          #
+          # @return a new instance of the {BatchSpanProcessor}.
           def initialize(exporter:,
-                         exporter_timeout_millis: EXPORTER_TIMEOUT_MILLIS,
-                         schedule_delay_millis: SCHEDULE_DELAY_MILLIS,
-                         max_queue_size: MAX_QUEUE_SIZE,
-                         max_export_batch_size: MAX_EXPORT_BATCH_SIZE,
-                         max_export_attempts: MAX_EXPORT_ATTEMPTS)
+                         exporter_timeout_millis: Float(ENV.fetch('OTEL_BSP_EXPORT_TIMEOUT_MILLIS', 30_000)),
+                         schedule_delay_millis: Float(ENV.fetch('OTEL_BSP_SCHEDULE_DELAY_MILLIS', 5_000)),
+                         max_queue_size: Integer(ENV.fetch('OTEL_BSP_MAX_QUEUE_SIZE', 2048)),
+                         max_export_batch_size: Integer(ENV.fetch('OTEL_BSP_MAX_EXPORT_BATCH_SIZE', 512)))
             raise ArgumentError if max_export_batch_size > max_queue_size
 
             @exporter = exporter
@@ -50,7 +55,6 @@ module OpenTelemetry
             @delay_seconds = schedule_delay_millis / 1000.0
             @max_queue_size = max_queue_size
             @batch_size = max_export_batch_size
-            @export_attempts = max_export_attempts
             @spans = []
             @thread = Thread.new { work }
           end
@@ -72,6 +76,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 +102,7 @@ module OpenTelemetry
             end
 
             @thread.join
-            flush
+            force_flush
             @exporter.shutdown
           end
 
@@ -104,35 +125,20 @@ module OpenTelemetry
           end
 
           def export_batch(batch)
-            result_code = nil
-            @export_attempts.times do |attempts|
-              result_code = export_with_timeout(batch)
-              break unless result_code == FAILED_RETRYABLE
-
-              sleep(0.1 * attempts)
-            end
+            result_code = export_with_timeout(batch)
             report_result(result_code, batch)
           end
 
           def export_with_timeout(batch)
             Timeout.timeout(@exporter_timeout_seconds) { @exporter.export(batch) }
           rescue Timeout::Error
-            FAILED_NOT_RETRYABLE
+            FAILURE
           end
 
           def report_result(result_code, batch)
             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