opentelemetry-api 0.2.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48050ae87a672b7a5e9ee6b28cd7b78d5affc75ddc4fca38b5fce29be29c667a
-  data.tar.gz: b0227255a1f374fe2916110495cbe867dad595f1134f2a1ba536bb19493daa85
+  metadata.gz: 538ed3a78ed2551d82e647c361b94afc77a083a1126093cb26674e324197d0a0
+  data.tar.gz: eb5a65a102585407772dcc8b57b375c83198cbddc432c97a71d9fdef97e3171a
 SHA512:
-  metadata.gz: 1a75c86cb6407d28a58e573d06b5faa7b3ea67d3a8dd3fdd6b45dc0d40d5122326bdb0de0d7be2e86aa1f0ec853589a28103e880fc22cf3882d2159064077832
-  data.tar.gz: 48aebdd8a8260daade30c068486eb2618e82e80807aa74f38398ad557f4735e7608629b44c59884b9794d306c5e1570b2a888f13df35dd1f1ee0635a7acc185f
+  metadata.gz: '097a3f2d32207a56ba207cc2918f24e4eee28483117c54ed0412e83e617922980f385bf5c1949a91b232c4fa4a5bfccf5c66947ee65fc4ebc26460a27a33f6b6'
+  data.tar.gz: 533897d0cea9a0f731e4d7badf100089fb2bb87e95cbe28060e222aea4137272a4e71f9dd65e12ef8a8558bf3635cc512e663de2d5364fea9a1086cab3a9cef1

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

@@ -1 +1,14 @@
 # Release History: opentelemetry-api
+
+### v0.6.0 / 2020-09-10
+
+* ADDED: Add support for OTEL_LOG_LEVEL env var
+* Documented array valued attributes [#343](https://github.com/open-telemetry/opentelemetry-ruby/pull/343)
+* Renamed CorrelationContext to Baggage [#338](https://github.com/open-telemetry/opentelemetry-ruby/pull/338)
+* Renamed Text* to TextMap* (propagators) [#335](https://github.com/open-telemetry/opentelemetry-ruby/pull/335)
+* Fixed exception semantic conventions (`span.record_error` -> `span.record_exception`) [#333](https://github.com/open-telemetry/opentelemetry-ruby/pull/333)
+* Removed support for lazy event creation [#329](https://github.com/open-telemetry/opentelemetry-ruby/pull/329)
+  * `name:` named parameter to `span.add_event` becomes first positional argument
+  * `Event` class removed from API
+* Added `hex_trace_id` and `hex_span_id` helpers to `SpanContext` [#332](https://github.com/open-telemetry/opentelemetry-ruby/pull/332)
+* Added `CorrelationContext::Manager.values` method to return correlations as a `Hash` [#323](https://github.com/open-telemetry/opentelemetry-ruby/pull/323)

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/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,43 +1,61 @@
 # 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/internal'
+require 'opentelemetry/baggage'
+require_relative './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, :baggage, :logger
+
+  # @return [Object, Logger] configured Logger or a default STDOUT Logger.
+  def logger
+    @logger ||= Logger.new(STDOUT, level: ENV['OTEL_LOG_LEVEL'] || Logger::INFO)
+  end
 
-  attr_accessor :logger
+  # @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, 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, 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 [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 [Instrumentation::Registry] registry containing all known
+  #  instrumentation
+  def instrumentation_registry
+    @instrumentation_registry ||= Instrumentation::Registry.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 [Object, Baggage::Manager] registered
+  #   baggage manager or a default no-op implementation of the
+  #   manager.
+  def baggage
+    @baggage ||= Baggage::Manager.new
   end
 
-  self.logger = Logger.new(STDOUT)
+  # @return [Context::Propagation::Propagation] an instance of the propagation API
+  def propagation
+    @propagation ||= Context::Propagation::Propagation.new
+  end
 end

data/lib/opentelemetry/baggage.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/baggage/builder'
+require 'opentelemetry/baggage/manager'
+require 'opentelemetry/baggage/propagation'
+
+module OpenTelemetry
+  # The Baggage module provides functionality to record and propagate
+  # baggage in a distributed trace
+  module Baggage
+  end
+end

data/lib/opentelemetry/baggage/builder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Baggage
+    # No op implementation of Baggage::Builder
+    class Builder
+      def set_value(key, value); end
+
+      def remove_value(key); end
+
+      def clear; end
+    end
+  end
+end

data/lib/opentelemetry/baggage/manager.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Baggage
+    # No op implementation of Baggage::Manager
+    class Manager
+      NOOP_BUILDER = Builder.new
+      EMPTY_VALUES = {}.freeze
+      private_constant(:NOOP_BUILDER, :EMPTY_VALUES)
+
+      def build(context: Context.current)
+        yield NOOP_BUILDER
+        context
+      end
+
+      def set_value(key, value, context: Context.current)
+        context
+      end
+
+      def value(key, context: Context.current)
+        nil
+      end
+
+      def values(context: Context.current)
+        EMPTY_VALUES
+      end
+
+      def remove_value(key, context: Context.current)
+        context
+      end
+
+      def clear(context: Context.current)
+        context
+      end
+    end
+  end
+end

data/lib/opentelemetry/baggage/propagation.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/baggage/propagation/context_keys'
+require 'opentelemetry/baggage/propagation/text_map_injector'
+require 'opentelemetry/baggage/propagation/text_map_extractor'
+
+module OpenTelemetry
+  module Baggage
+    # The Baggage::Propagation module contains injectors and
+    # extractors for sending and receiving baggage over the wire
+    module Propagation
+      extend self
+
+      TEXT_MAP_EXTRACTOR = TextMapExtractor.new
+      TEXT_MAP_INJECTOR = TextMapInjector.new
+      RACK_EXTRACTOR = TextMapExtractor.new(
+        baggage_key: 'HTTP_BAGGAGE'
+      )
+      RACK_INJECTOR = TextMapInjector.new(
+        baggage_key: 'HTTP_BAGGAGE'
+      )
+
+      private_constant :TEXT_MAP_INJECTOR, :TEXT_MAP_EXTRACTOR, :RACK_INJECTOR,
+                       :RACK_EXTRACTOR
+
+      # Returns an extractor that extracts context using the W3C Baggage
+      # format
+      def text_map_injector
+        TEXT_MAP_INJECTOR
+      end
+
+      # Returns an injector that injects context using the W3C Baggage
+      # format
+      def text_map_extractor
+        TEXT_MAP_EXTRACTOR
+      end
+
+      # Returns an extractor that extracts context using the W3C Baggage
+      # format with Rack normalized keys (upcased and prefixed with
+      # HTTP_)
+      def rack_injector
+        RACK_INJECTOR
+      end
+
+      # Returns an injector that injects context using the W3C Baggage
+      # format with Rack normalized keys (upcased and prefixed with
+      # HTTP_)
+      def rack_extractor
+        RACK_EXTRACTOR
+      end
+    end
+  end
+end

data/lib/opentelemetry/baggage/propagation/context_keys.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Baggage
+    module Propagation
+      # The ContextKeys module contains the keys used to index baggage
+      # in a {Context} instance
+      module ContextKeys
+        extend self
+
+        BAGGAGE_KEY = Context.create_key('baggage')
+        private_constant :BAGGAGE_KEY
+
+        # Returns the context key that baggage are indexed by
+        #
+        # @return [Context::Key]
+        def baggage_key
+          BAGGAGE_KEY
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/baggage/propagation/text_map_extractor.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'cgi'
+
+module OpenTelemetry
+  module Baggage
+    module Propagation
+      # Extracts baggage from carriers in the W3C Baggage format
+      class TextMapExtractor
+        include Context::Propagation::DefaultGetter
+
+        # Returns a new TextMapExtractor that extracts context using the specified
+        # header key
+        #
+        # @param [String] baggage_key The baggage header
+        #   key used in the carrier
+        # @return [TextMapExtractor]
+        def initialize(baggage_key: 'baggage')
+          @baggage_key = baggage_key
+        end
+
+        # Extract remote baggage from the supplied carrier.
+        # If extraction fails, the original context will be returned
+        #
+        # @param [Carrier] carrier The carrier to get the header from
+        # @param [Context] context The context to be updated with extracted baggage
+        # @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 []=.
+        # @yield [Carrier, String] if an optional getter is provided, extract will yield the carrier
+        #   and the header key to the getter.
+        # @return [Context] context updated with extracted baggage, or the original context
+        #   if extraction fails
+        def extract(carrier, context, &getter)
+          getter ||= default_getter
+          header = getter.call(carrier, @baggage_key)
+
+          entries = header.gsub(/\s/, '').split(',')
+
+          baggage = entries.each_with_object({}) do |entry, memo|
+            # The ignored variable below holds properties as per the W3C spec.
+            # OTel is not using them currently, but they might be used for
+            # metadata in the future
+            kv, = entry.split(';', 2)
+            k, v = kv.split('=').map!(&CGI.method(:unescape))
+            memo[k] = v
+          end
+
+          context.set_value(ContextKeys.baggage_key, baggage)
+        rescue StandardError
+          context
+        end
+      end
+    end
+  end
+end

data/lib/opentelemetry/baggage/propagation/text_map_injector.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Copyright 2019 OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'cgi'
+
+module OpenTelemetry
+  module Baggage
+    module Propagation
+      # Injects baggage using the W3C Baggage format
+      class TextMapInjector
+        include Context::Propagation::DefaultSetter
+
+        # Returns a new TextMapInjector that injects context using the specified
+        # header key
+        #
+        # @param [String] baggage_header_key The baggage header
+        #   key used in the carrier
+        # @return [TextMapInjector]
+        def initialize(baggage_key: 'baggage')
+          @baggage_key = baggage_key
+        end
+
+        # Inject in-process baggage into the supplied carrier.
+        #
+        # @param [Carrier] carrier The carrier to inject baggage into
+        # @param [Context] context The context to read baggage from
+        # @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 []=.
+        # @yield [Carrier, String] if an optional getter is provided, inject will yield the carrier
+        #   and the header key to the getter.
+        # @return [Object] carrier with injected baggage
+        def inject(carrier, context, &setter)
+          return carrier unless (baggage = context[ContextKeys.baggage_key]) && !baggage.empty?
+
+          setter ||= default_setter
+          setter.call(carrier, @baggage_key, encode(baggage))
+
+          carrier
+        end
+
+        private
+
+        def encode(baggage)
+          baggage.inject(+'') do |memo, (k, v)|
+            memo << CGI.escape(k.to_s) << '=' << CGI.escape(v.to_s) << ','
+          end.chop!
+        end
+      end
+    end
+  end
+end