opentelemetry-api 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48050ae87a672b7a5e9ee6b28cd7b78d5affc75ddc4fca38b5fce29be29c667a
-  data.tar.gz: b0227255a1f374fe2916110495cbe867dad595f1134f2a1ba536bb19493daa85
+  metadata.gz: c91a5540309be0f2dcc70066b25eab314bed537321a6d4b8360b72077cb9da22
+  data.tar.gz: 925121d6b30bf9cf3b1a17c30afbfdf5e328b0374b23a8daade2cf1d486e795f
 SHA512:
-  metadata.gz: 1a75c86cb6407d28a58e573d06b5faa7b3ea67d3a8dd3fdd6b45dc0d40d5122326bdb0de0d7be2e86aa1f0ec853589a28103e880fc22cf3882d2159064077832
-  data.tar.gz: 48aebdd8a8260daade30c068486eb2618e82e80807aa74f38398ad557f4735e7608629b44c59884b9794d306c5e1570b2a888f13df35dd1f1ee0635a7acc185f
+  metadata.gz: 93299563d90db1b05e873f431e151dc1d2e7e05f54d0b5311985be42d15a3f33f50e3e35fb24e0ef063a26a3cc06333bcb304ee418dd590ed124c08416735b80
+  data.tar.gz: e7edc0bde321596ec89fedc87c1209e35a6b306b22a87aa0e761a4a77cd3b4d9f0239a486f7444f280008c733e9a8378369cb0640fd60b58106bf256b9bd4e5c

data/.yardopts

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

data/OVERVIEW.md

@@ -0,0 +1,66 @@
+# opentelemetry-api
+
+The `opentelemetry-api` gem defines the core OpenTelemetry interfaces for Ruby applications. Using `opentelemetry-api`, a library or application can code against the OpenTelemetry interfaces to produce 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-api` gem defines the core OpenTelemetry interfaces in the form of abstract classes and no-op implementations. That is, it defines interfaces and data types sufficient for a library or application to code against to produce telemetry data, but does not actually collect, analyze, or export the data.
+
+To collect and analyze telemetry data, *applications* should also install a concrete implementation of the API, such as the `opentelemetry-sdk` gem. However, *libraries* that produce telemetry data should 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-api
+```
+
+Or, if you use [bundler][bundler-home], include `opentelemetry-api` in your `Gemfile`.
+
+Then, use the OpenTelemetry interfaces to produces traces and other telemetry data. Following is a basic example.
+
+```ruby
+require 'opentelemetry'
+
+# Obtain the current default tracer factory
+factory = OpenTelemetry.tracer_factory
+
+# Create a trace
+tracer = factory.tracer('my_app', '1.0')
+
+# Record spans
+tracer.in_span('my_task') do |task_span|
+  tracer.in_span('inner') do |inner_span|
+    # Do something here
+  end
+end
+```
+
+For additional examples, see the [examples on github][examples-github].
+
+## How can I get involved?
+
+The `opentelemetry-api` gem source is [on github][repo-github], along with related gems including `opentelemetry-sdk`.
+
+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-api` 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/distributed_context/manager.rb → opentelemetry-api.rb}

@@ -4,9 +4,4 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-module OpenTelemetry
-  module DistributedContext
-    class Manager
-    end
-  end
-end
+require 'opentelemetry'

data/lib/opentelemetry.rb

@@ -1,42 +1,60 @@
 # frozen_string_literal: true
 
-# Copyright 2019 OpenTelemetry Authors
+# Copyright 2020 OpenTelemetry Authors
 #
 # SPDX-License-Identifier: Apache-2.0
+
 require 'logger'
 
 require 'opentelemetry/error'
 require 'opentelemetry/context'
-require 'opentelemetry/distributed_context'
+require 'opentelemetry/correlation_context'
 require 'opentelemetry/internal'
+require 'opentelemetry/instrumentation'
 require 'opentelemetry/metrics'
 require 'opentelemetry/trace'
 require 'opentelemetry/version'
 
-# OpenTelemetry provides global accessors for telemetry objects
+# 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.
 module OpenTelemetry
   extend self
 
-  attr_writer :tracer_factory, :meter_factory, :distributed_context_manager
+  attr_writer :tracer_provider, :meter_provider, :correlations
 
   attr_accessor :logger
 
-  # @return [Object, Trace::TracerFactory] registered tracer factory or a
-  #   default no-op implementation of the tracer factory.
-  def tracer_factory
-    @tracer_factory ||= Trace::TracerFactory.new
+  # @return [Object, Trace::TracerProvider] registered tracer provider or a
+  #   default no-op implementation of the tracer provider.
+  def tracer_provider
+    @tracer_provider ||= Trace::TracerProvider.new
+  end
+
+  # @return [Object, Metrics::MeterProvider] registered meter provider or a
+  #   default no-op implementation of the meter provider.
+  def meter_provider
+    @meter_provider ||= Metrics::MeterProvider.new
+  end
+
+  # @return [Instrumentation::Registry] registry containing all known
+  #  instrumentation
+  def instrumentation_registry
+    @instrumentation_registry ||= Instrumentation::Registry.new
   end
 
-  # @return [Object, Metrics::MeterFactory] registered meter factory or a
-  #   default no-op implementation of the meter factory.
-  def meter_factory
-    @meter_factory ||= Metrics::MeterFactory.new
+  # @return [Object, CorrelationContext::Manager] registered
+  #   correlation context manager or a default no-op implementation of the
+  #   manager.
+  def correlations
+    @correlations ||= CorrelationContext::Manager.new
   end
 
-  # @return [Object, DistributedContext::Manager] registered distributed
-  #   context manager or a default no-op implementation of the manager
-  def distributed_context_manager
-    @distributed_context_manager ||= DistributedContext::Manager.new
+  # @return [Context::Propagation::Propagation] an instance of the propagation API
+  def propagation
+    @propagation ||= Context::Propagation::Propagation.new
   end
 
   self.logger = Logger.new(STDOUT)

data/lib/opentelemetry/context.rb

@@ -4,28 +4,151 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+require 'opentelemetry/context/key'
+require 'opentelemetry/context/propagation'
+
 module OpenTelemetry
-  # The Context module provides per-thread storage.
-  module Context
-    extend self
+  # Manages context on a per-fiber basis
+  class Context
+    KEY = :__opentelemetry_context__
+    EMPTY_ENTRIES = {}.freeze
+
+    class << self
+      # Returns a key used to index a value in a Context
+      #
+      # @param [String] name The key name
+      # @return [Context::Key]
+      def create_key(name)
+        Key.new(name)
+      end
+
+      # Returns current context, which is never nil
+      #
+      # @return [Context]
+      def current
+        Thread.current[KEY] ||= ROOT
+      end
+
+      # Sets the current context
+      #
+      # @param [Context] ctx The context to be made active
+      def current=(ctx)
+        Thread.current[KEY] = ctx
+      end
+
+      # Executes a block with ctx as the current context. It restores
+      # the previous context upon exiting.
+      #
+      # @param [Context] ctx The context to be made active
+      # @yield [context] Yields context to the block
+      def with_current(ctx)
+        prev = ctx.attach
+        yield ctx
+      ensure
+        ctx.detach(prev)
+      end
+
+      # Execute a block in a new context with key set to value. Restores the
+      # previous context after the block executes.
+
+      # @param [String] key The lookup key
+      # @param [Object] value The object stored under key
+      # @param [Callable] Block to execute in a new context
+      # @yield [context, value] Yields the newly created context and value to
+      #   the block
+      def with_value(key, value)
+        ctx = current.set_value(key, value)
+        prev = ctx.attach
+        yield ctx, value
+      ensure
+        ctx.detach(prev)
+      end
+
+      # Execute a block in a new context where its values are merged with the
+      # incoming values. Restores the previous context after the block executes.
+
+      # @param [String] key The lookup key
+      # @param [Hash] values Will be merged with values of the current context
+      #  and returned in a new context
+      # @param [Callable] Block to execute in a new context
+      # @yield [context, values] Yields the newly created context and values
+      #   to the block
+      def with_values(values)
+        ctx = current.set_values(values)
+        prev = ctx.attach
+        yield ctx, values
+      ensure
+        ctx.detach(prev)
+      end
+
+      # Returns the value associated with key in the current context
+      #
+      # @param [String] key The lookup key
+      def value(key)
+        current.value(key)
+      end
+
+      def clear
+        self.current = ROOT
+      end
 
-    def get(key)
-      storage[key]
+      def empty
+        new(nil, EMPTY_ENTRIES)
+      end
     end
 
-    def with(key, value)
-      store = storage
-      previous = store[key]
-      store[key] = value
-      yield value
-    ensure
-      store[key] = previous
+    def initialize(parent, entries)
+      @parent = parent
+      @entries = entries.freeze
     end
 
-    private
+    # Returns the corresponding value (or nil) for key
+    #
+    # @param [Key] key The lookup key
+    # @return [Object]
+    def value(key)
+      @entries[key]
+    end
+
+    alias [] value
+
+    # Returns a new Context where entries contains the newly added key and value
+    #
+    # @param [Key] key The key to store this value under
+    # @param [Object] value Object to be stored under key
+    # @return [Context]
+    def set_value(key, value)
+      new_entries = @entries.dup
+      new_entries[key] = value
+      Context.new(self, new_entries)
+    end
+
+    # Returns a new Context with the current context's entries merged with the
+    #   new entries
+    #
+    # @param [Hash] values The values to be merged with the current context's
+    #   entries.
+    # @param [Object] value Object to be stored under key
+    # @return [Context]
+    def set_values(values) # rubocop:disable Naming/AccessorMethodName:
+      Context.new(self, @entries.merge(values))
+    end
 
-    def storage
-      Thread.current[:__opentelemetry__] ||= {}
+    # @api private
+    def attach
+      prev = self.class.current
+      self.class.current = self
+      prev
     end
+
+    # @api private
+    def detach(ctx_to_attach = nil)
+      OpenTelemetry.logger.warn 'Calls to detach should match corresponding calls to attach' if self.class.current != self
+
+      ctx_to_attach ||= @parent || ROOT
+      ctx_to_attach.attach
+    end
+
+    ROOT = empty.freeze
   end
 end

data/lib/opentelemetry/context/key.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    # The Key class provides mechanisms to index and access values from a
+    # Context
+    class Key
+      attr_reader :name
+
+      # @api private
+      # Use Context.create_key to obtain a Key instance.
+      def initialize(name)
+        @name = name
+      end
+
+      # Returns the value indexed by this Key in the specified context
+      #
+      # @param [optional Context] context The Context to lookup the key from.
+      #   Defaults to +Context.current+.
+      def get(context = Context.current)
+        context[self]
+      end
+    end
+  end
+end

data/lib/opentelemetry/context/propagation.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/context/propagation/composite_propagator'
+require 'opentelemetry/context/propagation/default_getter'
+require 'opentelemetry/context/propagation/default_setter'
+require 'opentelemetry/context/propagation/noop_extractor'
+require 'opentelemetry/context/propagation/noop_injector'
+require 'opentelemetry/context/propagation/propagation'
+require 'opentelemetry/context/propagation/propagator'
+
+module OpenTelemetry
+  class Context
+    # The propagation module contains APIs and utilities to interact with context
+    # and propagate across process boundaries.
+    module Propagation
+    end
+  end
+end

data/lib/opentelemetry/context/propagation/composite_propagator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Copyright 2020 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  class Context
+    module Propagation
+      # A composite propagator composes a list of injectors and extractors into
+      # single interface exposing inject and extract methods. Injection and
+      # extraction will preserve the order of the injectors and extractors
+      # passed in during initialization.
+      class CompositePropagator
+        # Returns a Propagator that extracts using the provided extractors
+        # and injectors.
+        #
+        # @param [Array<#inject>] injectors
+        # @param [Array<#extract>] extractors
+        def initialize(injectors, extractors)
+          @injectors = injectors
+          @extractors = extractors
+        end
+
+        # Runs injectors in order and returns a carrier. If an injection fails
+        # a warning will be logged and remaining injectors will be executed.
+        # Always returns a valid carrier.
+        #
+        # @param [Object] carrier A carrier to inject context into
+        #   context into
+        # @param [optional Context] context Context to be injected into carrier.
+        #   Defaults to +Context.current+
+        # @param [optional Callable] setter An optional callable that takes a
+        #   carrier, a key and a value and assigns the key-value pair in the
+        #   carrier. If omitted the default setter will be used which expects
+        #   the carrier to respond to [] and []=.
+        #
+        # @return [Object] carrier
+        def inject(carrier, context = Context.current, &setter)
+          @injectors.inject(carrier) do |memo, injector|
+            begin
+              injector.inject(memo, context, &setter)
+            rescue => e # rubocop:disable Style/RescueStandardError
+              OpenTelemetry.logger.warn "Error in CompositePropagator#inject #{e.message}"
+              carrier
+            end
+          end
+        end
+
+        # Runs extractors in order and returns a Context updated with the
+        # results of each extraction. If an extraction fails, a warning will be
+        # logged and remaining extractors will continue to be executed. Always
+        # returns a valid context.
+        #
+        # @param [Object] carrier The carrier to extract context from
+        # @param [optional Context] context Context to be updated with the state
+        #   extracted from the carrier. Defaults to +Context.current+
+        # @param [optional Callable] getter An optional callable that takes a carrier and a key and
+        #   returns the value associated with the key. If omitted the default getter will be used
+        #   which expects the carrier to respond to [] and []=.
+        #
+        # @return [Context] a new context updated with state extracted from the
+        #   carrier
+        def extract(carrier, context = Context.current, &getter)
+          @extractors.inject(context) do |ctx, extractor|
+            begin
+              extractor.extract(carrier, ctx, &getter)
+            rescue => e # rubocop:disable Style/RescueStandardError
+              OpenTelemetry.logger.warn "Error in CompositePropagator#extract #{e.message}"
+              ctx
+            end
+          end
+        end
+      end
+    end
+  end
+end