opentelemetry-sdk 0.2.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ec567bdc317284ee832998232c68645a334e361aa25525901d2054982fe1390
-  data.tar.gz: c82ce9e13256fd7e70937f806a11fae72798748e92bdb68b587a6aaa2274f00e
+  metadata.gz: 3a01fcf121db23108ffb47d196f9594993018bb1b945242710620bb87daa8320
+  data.tar.gz: ef3b3e9cd4e2853a22ffb149e7a18cbd021988412d24c40350192e222b3be58b
 SHA512:
-  metadata.gz: 1417b975acd7e5006b58c34341f464db4ba809b8664ff0282cc1c7b6caac54358c33691a04dadf78ae1df8323cbb8f8dc8b10bd33da4326fb57ee0c293279f6c
-  data.tar.gz: 1b2c01c8f77f936cdc9c144f8b1237f7ca46fa92a657bbc0d0824288bde5c3ba49914761f7181630c49c43d843b3c6e39bf33bda30147530f156c6f82e79f63e
+  metadata.gz: 5da08d0e902ece66efc7afa892f99f2b9fe3bcd5b89b51cd3da1a565a23ab0917eb1c39d6fb44ed6b82a71048624cb357539d9b6305b1a0c8debc594ef2467d3
+  data.tar.gz: 5fe47387c0d91e8d5436be4d4464839f08a9ae46964e8fe1679ab6ef7e7bf8b7a59ae086472d465e6f12c57b70c712a982064351f287a8ebbb6bbe173c37b45d

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/CHANGELOG.md

@@ -1 +1,24 @@
 # Release History: opentelemetry-sdk
+
+### v0.6.0 / 2020-09-10
+
+* BREAKING CHANGE: Rename Resource labels to attributes 
+* BREAKING CHANGE: Export resource from Span/SpanData instead of library_resource
+* BREAKING CHANGE: Rename CorrelationContext to Baggage
+* BREAKING CHANGE: Rename Text* to TextMap* (propagators, injectors, extractors)
+* BREAKING CHANGE: Rename span.record_error to span.record_exception
+* BREAKING CHANGE: Update samplers to match spec
+* BREAKING CHANGE: Remove support for lazy event creation
+
+* ADDED: Add OTLP exporter
+* ADDED: Add support for OTEL_LOG_LEVEL env var
+* FIXED: Rename Resource labels to attributes 
+* ADDED: Environment variable resource detection
+* ADDED: BatchSpanProcessor environment variable support
+* FIXED: Remove semver prefix
+* FIXED: Docs for array valued attributes
+* ADDED: Add hex_trace_id and hex_span_id helpers to SpanData
+* FIXED: Fix ProbabilitySampler
+* ADDED: Implement GetCorrelations
+* FIXED: Change default Sampler to ParentOrElse(AlwaysOn)
+* FIXED: Fix probability sampler

data/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2020 OpenTelemetry Authors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

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('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,13 +6,64 @@
 
 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::Instrumentation::Faraday', tracer_middleware: SomeMiddleware
+    #     end
+    #
+    #   Install all instrumentation with optional config
+    #
+    #     OpenTelemetry::SDK.configure do |c|
+    #       c.use_all 'OpenTelemetry::Instrumentation::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/baggage'
 require 'opentelemetry/sdk/internal'
+require 'opentelemetry/sdk/instrumentation_library'
 require 'opentelemetry/sdk/resources'
 require 'opentelemetry/sdk/trace'
 require 'opentelemetry/sdk/version'

data/lib/opentelemetry/sdk/baggage.rb

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

data/lib/opentelemetry/sdk/baggage/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 Baggage
+      # SDK implementation of Baggage::Builder
+      class Builder
+        attr_reader :entries
+
+        def initialize(entries)
+          @entries = entries
+        end
+
+        # Set key-value in the to-be-created baggage
+        #
+        # @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 baggage
+        #
+        # @param [String] key The key to remove
+        def remove_value(key)
+          @entries.delete(key)
+        end
+
+        # Clears all baggage from the to-be-created baggage
+        def clear
+          @entries.clear
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Baggage
+      # Manages baggage
+      class Manager
+        BAGGAGE_KEY = OpenTelemetry::Baggage::Propagation::ContextKeys.baggage_key
+        EMPTY_BAGGAGE = {}.freeze
+        private_constant(:BAGGAGE_KEY, :EMPTY_BAGGAGE)
+
+        # Used to chain modifications to baggage. The result is a
+        # context with an updated baggage. If only a single
+        # modification is being made to baggage, 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 baggage. Defaults to +Context.current+
+        # @return [Context]
+        def build_context(context: Context.current)
+          builder = Builder.new(baggage_for(context).dup)
+          yield builder
+          context.set_value(BAGGAGE_KEY, builder.entries)
+        end
+
+        # Returns a new context with empty baggage
+        #
+        # @param [optional Context] context Context to clear baggage from. Defaults
+        #   to +Context.current+
+        # @return [Context]
+        def clear(context: Context.current)
+          context.set_value(BAGGAGE_KEY, EMPTY_BAGGAGE)
+        end
+
+        # Returns the corresponding baggage 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)
+          baggage_for(context)[key]
+        end
+
+        # Returns the baggage
+        #
+        # @param [optional Context] context The context from which to retrieve
+        #   the baggage.
+        #   Defaults to +Context.current+
+        # @return [Hash]
+        def values(context: Context.current)
+          baggage_for(context).dup.freeze
+        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_baggage = baggage_for(context).dup
+          new_baggage[key] = value
+          context.set_value(BAGGAGE_KEY, new_baggage)
+        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 baggage
+        #   from. Defaults to +Context.current+
+        # @return [Context]
+        def remove_value(key, context: Context.current)
+          baggage = baggage_for(context)
+          return context unless baggage.key?(key)
+
+          new_baggage = baggage.dup
+          new_baggage.delete(key)
+          context.set_value(BAGGAGE_KEY, new_baggage)
+        end
+
+        private
+
+        def baggage_for(context)
+          context.value(BAGGAGE_KEY) || EMPTY_BAGGAGE
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/sdk/configurator.rb

@@ -0,0 +1,172 @@
+# 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 # rubocop:disable Metrics/ClassLength
+      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_map_extractors,
+                  :text_map_injectors
+
+      def initialize
+        @instrumentation_names = []
+        @instrumentation_config_map = {}
+        @http_extractors = nil
+        @http_injectors = nil
+        @text_map_extractors = nil
+        @text_map_injectors = nil
+        @span_processors = []
+        @use_mode = USE_MODE_UNSPECIFIED
+        @resource = Resources::Resource.telemetry_sdk
+      end
+
+      def logger
+        @logger ||= OpenTelemetry.logger
+      end
+
+      # Accepts a resource object that is merged with the default telemetry sdk
+      # resource. The use of this method is optional, and is provided as means
+      # to include additional resource information.
+      # If a resource key collision occurs the passed in resource takes priority.
+      #
+      # @param [Resource] new_resource The resource to be merged
+      def resource=(new_resource)
+        @resource = new_resource.merge(@resource)
+      end
+
+      # Install an instrumentation with specificied optional +config+.
+      # Use can be called multiple times to install multiple instrumentation.
+      # 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] instrumentation_name The name of the instrumentation
+      # @param [optional Hash] config The config for this instrumentation
+      def use(instrumentation_name, config = nil)
+        check_use_mode!(USE_MODE_ONE)
+        @instrumentation_names << instrumentation_name
+        @instrumentation_config_map[instrumentation_name] = config if config
+      end
+
+      # Install all registered instrumentation. Configuration for specific
+      # instrumentation can be provided with the optional +instrumentation_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>] instrumentation_config_map A map with string keys
+      #   representing the instrumentation name and values specifying the instrumentation config
+      def use_all(instrumentation_config_map = {})
+        check_use_mode!(USE_MODE_ALL)
+        @instrumentation_config_map = instrumentation_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.baggage = Baggage::Manager.new
+        configure_propagation
+        configure_span_processors
+        OpenTelemetry.tracer_provider = tracer_provider
+        install_instrumentation
+      end
+
+      private
+
+      def tracer_provider
+        @tracer_provider ||= Trace::TracerProvider.new(@resource)
+      end
+
+      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(@instrumentation_names, @instrumentation_config_map)
+        when USE_MODE_ALL
+          OpenTelemetry.instrumentation_registry.install_all(@instrumentation_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_map_injectors || default_text_map_injectors,
+                                                           @text_map_extractors || default_text_map_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_map_injectors
+      end
+
+      def default_http_extractors
+        [
+          OpenTelemetry::Trace::Propagation::TraceContext.rack_extractor,
+          OpenTelemetry::Baggage::Propagation.rack_extractor
+        ]
+      end
+
+      def default_text_map_injectors
+        [
+          OpenTelemetry::Trace::Propagation::TraceContext.text_map_injector,
+          OpenTelemetry::Baggage::Propagation.text_map_injector
+        ]
+      end
+
+      def default_text_map_extractors
+        [
+          OpenTelemetry::Trace::Propagation::TraceContext.text_map_extractor,
+          OpenTelemetry::Baggage::Propagation.text_map_extractor
+        ]
+      end
+    end
+  end
+end