opentracing 0.3.2 → 0.4.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f761a5b465cf95f65ce40a201dd8cd3714286c78
-  data.tar.gz: 1d1c484d531e165480dd7c16db268a9fd1d8b0db
+  metadata.gz: 7f48b115cca9cb06fe69b84c5810f07e5491a8f5
+  data.tar.gz: 27a4336744a7c48f18391d0fede2e52f747df80c
 SHA512:
-  metadata.gz: 20cd823a49e8f8782367b8f31f87c25e082e02d6995a0c1ee8a1a0132ed61dec4dd54f34335f5a99e33b9f09b12576fa445da605c39c14802e44a1fb0b683f68
-  data.tar.gz: c2cfafcde7cbe58ffeb9b2c436806bd545b7dc94e4e5ae834b5c1db64d9fe147f7dc84046fe03100d1dd7b929284e109bf290c33d2e0043b6930ec7b82d37c09
+  metadata.gz: e5f0868a95ecc7c91eb1f14eed99ab3adb5e00a5439896d7428d0480aaf6edbbd292abf6a2f266da54b4bd987ba7172973537780b09ca6eebb5258a024bbafb2
+  data.tar.gz: d6deb922e5d0be1d8c07c8afa77a131ad6c477e44023f97810b7c2cf2b6899ff9950ee585342210e0a773cd565888c57f652ff4e9f59eafc65905f1fb7c81c90

data/CHANGELOG.md

@@ -1,8 +1,13 @@
 # Changelog
 
+## 0.4.0
+
+* The tracer now implements the OpenTracing Scope API for in-process scope propagation([#21](https://github.com/opentracing/opentracing-ruby/pull/21))
+* Adds a `log_kv` method and deprecates `log` for consistency with other language implementations. See [#22](https://github.com/opentracing/opentracing-ruby/pull/23).
+
 ## 0.3.2
 
 * Addressing Ruby style issues ([#14](https://github.com/opentracing/opentracing-ruby/pull/14))
 * Default to the no-op tracer ([#17](https://github.com/opentracing/opentracing-ruby/pull/17))
 * Fixing serialization example in README ([#18](https://github.com/opentracing/opentracing-ruby/pull/18))
-* Removing bundler development version requirement
+* Removing bundler development version requirement

data/README.md

@@ -25,6 +25,8 @@ And then execute:
 Or install it yourself as:
 
     $ gem install opentracing
+    
+`opentracing` supports Ruby 2.0+.
 
 ## Usage
 

data/lib/opentracing.rb

@@ -4,6 +4,8 @@ require "opentracing/span_context"
 require "opentracing/span"
 require "opentracing/reference"
 require "opentracing/tracer"
+require "opentracing/scope"
+require "opentracing/scope_manager"
 
 module OpenTracing
   # Text format for Tracer#inject and Tracer#extract.

data/lib/opentracing/scope.rb

@@ -0,0 +1,23 @@
+module OpenTracing
+  # Scope represents an OpenTracing Scope
+  #
+  # See http://www.opentracing.io for more information.
+  class Scope
+    NOOP_INSTANCE = Scope.new.freeze
+
+    # Return the Span scoped by this Scope
+    #
+    # @return [Span]
+    def span
+      Span::NOOP_INSTANCE
+    end
+
+    # Mark the end of the active period for the current thread and Scope,
+    # updating the ScopeManager#active in the process.
+    #
+    # NOTE: Calling close more than once on a single Scope instance leads to
+    # undefined behavior.
+    def close
+    end
+  end
+end

data/lib/opentracing/scope_manager.rb

@@ -0,0 +1,35 @@
+module OpenTracing
+  # ScopeManager represents an OpenTracing ScopeManager
+  #
+  # See http://www.opentracing.io for more information.
+  #
+  # The ScopeManager interface abstracts both the activation of Span instances
+  # via ScopeManager#activate and access to an active Span/Scope via
+  # ScopeManager#active
+
+  class ScopeManager
+    NOOP_INSTANCE = ScopeManager.new.freeze
+
+    # Make a span instance active.
+    #
+    # @param span [Span] the Span that should become active
+    # @param finish_on_close [Boolean] whether the Span should automatically be
+    #   finished when Scope#close is called
+    # @return [Scope] instance to control the end of the active period for the
+    #  Span. It is a programming error to neglect to call Scope#close on the
+    #  returned instance.
+    def activate(span, finish_on_close: true)
+      Scope::NOOP_INSTANCE
+    end
+
+    # @return [Scope] the currently active Scope which can be used to access the
+    # currently active Span.
+    #
+    # If there is a non-null Scope, its wrapped Span becomes an implicit parent
+    # (as Reference#CHILD_OF) of any newly-created Span at Tracer#start_active_span
+    # or Tracer#start_span time.
+    def active
+      Scope::NOOP_INSTANCE
+    end
+  end
+end

data/lib/opentracing/span.rb

@@ -40,11 +40,23 @@ module OpenTracing
       nil
     end
 
+    # @deprecated Use {#log_kv} instead.
+    # Reason: event is an optional standard log field defined in spec and not required.  Also,
+    # method name {#log_kv} is more consistent with other language implementations such as Python and Go.
+    #
     # Add a log entry to this span
     # @param event [String] event name for the log
     # @param timestamp [Time] time of the log
     # @param fields [Hash] Additional information to log
     def log(event: nil, timestamp: Time.now, **fields)
+      warn "Span#log is deprecated.  Please use Span#log_kv instead."
+      nil
+    end
+
+    # Add a log entry to this span
+    # @param timestamp [Time] time of the log
+    # @param fields [Hash] Additional information to log
+    def log_kv(timestamp: Time.now, **fields)
       nil
     end
 

data/lib/opentracing/tracer.rb

@@ -1,25 +1,73 @@
 module OpenTracing
   class Tracer
-    # Starts a new span.
+    # @return [ScopeManager] the current ScopeManager, which may be a no-op but
+    #   may not be nil.
+    def scope_manager
+      ScopeManager::NOOP_INSTANCE
+    end
+
+    # Returns a newly started and activated Scope.
     #
-    # @param operation_name [String] The operation name for the Span
+    # If the Tracer's ScopeManager#active is not nil, no explicit references
+    # are provided, and `ignore_active_scope` is false, then an inferred
+    # References#CHILD_OF reference is created to the ScopeManager#active's
+    # SpanContext when start_active is invoked.
     #
+    # @param operation_name [String] The operation name for the Span
     # @param child_of [SpanContext, Span] SpanContext that acts as a parent to
     #        the newly-started Span. If a Span instance is provided, its
     #        context is automatically substituted. See [Reference] for more
     #        information.
     #
-    #   If specified, the `references` paramater must be omitted.
-    #
+    #   If specified, the `references` parameter must be omitted.
     # @param references [Array<Reference>] An array of reference
     #   objects that identify one or more parent SpanContexts.
-    #
     # @param start_time [Time] When the Span started, if not now
-    #
     # @param tags [Hash] Tags to assign to the Span at start time
+    # @param ignore_active_scope [Boolean] whether to create an implicit
+    #   References#CHILD_OF reference to the ScopeManager#active.
+    # @param finish_on_close [Boolean] whether span should automatically be
+    #   finished when Scope#close is called
+    # @yield [Scope] If an optional block is passed to start_active it will
+    #   yield the newly-started Scope. If `finish_on_close` is true then the
+    #   Span will be finished automatically after the block is executed.
+    # @return [Scope] The newly-started and activated Scope
+    def start_active_span(operation_name,
+                          child_of: nil,
+                          references: nil,
+                          start_time: Time.now,
+                          tags: nil,
+                          ignore_active_scope: false,
+                          finish_on_close: true)
+      Scope::NOOP_INSTANCE.tap do |scope|
+        yield scope if block_given?
+      end
+    end
+
+    # Like #start_active_span, but the returned Span has not been registered via the
+    # ScopeManager.
     #
-    # @return [Span] The newly-started Span
-    def start_span(operation_name, child_of: nil, references: nil, start_time: Time.now, tags: nil)
+    # @param operation_name [String] The operation name for the Span
+    # @param child_of [SpanContext, Span] SpanContext that acts as a parent to
+    #        the newly-started Span. If a Span instance is provided, its
+    #        context is automatically substituted. See [Reference] for more
+    #        information.
+    #
+    #   If specified, the `references` parameter must be omitted.
+    # @param references [Array<Reference>] An array of reference
+    #   objects that identify one or more parent SpanContexts.
+    # @param start_time [Time] When the Span started, if not now
+    # @param tags [Hash] Tags to assign to the Span at start time
+    # @param ignore_active_scope [Boolean] whether to create an implicit
+    #   References#CHILD_OF reference to the ScopeManager#active.
+    # @return [Span] the newly-started Span instance, which has not been
+    #   automatically registered via the ScopeManager
+    def start_span(operation_name,
+                   child_of: nil,
+                   references: nil,
+                   start_time: Time.now,
+                   tags: nil,
+                   ignore_active_scope: false)
       Span::NOOP_INSTANCE
     end
 

data/lib/opentracing/version.rb

@@ -1,3 +1,3 @@
 module OpenTracing
-  VERSION = "0.3.2"
+  VERSION = "0.4.0.rc1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentracing
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0.rc1
 platform: ruby
 authors:
 - ngauthier
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-18 00:00:00.000000000 Z
+date: 2018-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -103,6 +103,8 @@ files:
 - lib/opentracing.rb
 - lib/opentracing/carrier.rb
 - lib/opentracing/reference.rb
+- lib/opentracing/scope.rb
+- lib/opentracing/scope_manager.rb
 - lib/opentracing/span.rb
 - lib/opentracing/span_context.rb
 - lib/opentracing/tracer.rb
@@ -123,12 +125,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.4.6
 signing_key: 
 specification_version: 4
 summary: OpenTracing Ruby Platform API