opentracing 0.4.0 → 0.4.1

data/.travis.yml

@@ -5,4 +5,4 @@ rvm:
   - 2.4.1
   - jruby-9.1.8.0
 before_install: gem install bundler -v 1.13.6
-script: JRUBY_OPTS="--debug" bundle exec rake test
+script: JRUBY_OPTS="--debug" bundle exec rake

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## Master
+
+## 0.4.1
+
+* Add active_span convenience method to OpenTracing module ([#30](https://github.com/opentracing/opentracing-ruby/pull/30))
+* Fix global tracer delegators ([#28](https://github.com/opentracing/opentracing-ruby/pull/28))
+* Add Rubocop ([#29](https://github.com/opentracing/opentracing-ruby/pull/27))
+* Update license from MIT => Apache 2.0 ([#26](https://github.com/opentracing/opentracing-ruby/pull/26))
+
 ## 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))

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 The OpenTracing 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

@@ -25,15 +25,15 @@ And then execute:
 Or install it yourself as:
 
     $ gem install opentracing
-    
+
 `opentracing` supports Ruby 2.0+.
 
 ## Usage
 
 Everyday consumers of this `opentracing` gem really only need to worry
-about a couple of key abstractions: the `start_span` function, the `Span`
-interface, and binding a `Tracer` at runtime. Here are code snippets
-demonstrating some important use cases.
+about a couple of key abstractions: the `start_active_span` and `start_span`
+methods, the `Span` and `ScopeManager` interfaces, and binding a `Tracer`
+at runtime. Here are code snippets demonstrating some important use cases.
 
 ### Singleton initialization
 
@@ -41,38 +41,101 @@ As early as possible, call
 
 ```ruby
 require 'opentracing'
-OpenTracing.global_tracer = MyTracerImplementation.New(...)
+OpenTracing.global_tracer = MyTracerImplementation.new(...)
 ```
 
 Where `MyTracerImplementation` is your tracer. For testing, you can use
-the provided `OpenTracing::NilTracer`
+the provided `OpenTracing::Tracer`
 
 ### Non-Singleton initialization
 
 If you prefer direct control to singletons, manage ownership of the
 `Tracer` implementation explicitly.
 
-### Starting an empty trace by creating a "root span"
+### Scopes and within-process propagation
+
+For any thread, at most one `Span` may be "active". Of course there may be many
+other `Spans` involved with the thread which are (a) started, (b) not finished,
+and yet (c) not "active": perhaps they are waiting for I/O, blocked on a child
+`Span`, or otherwise off of the critical path.
+
+It's inconvenient to pass an active `Span` from function to function manually,
+so OpenTracing requires that every `Tracer` contains a `ScopeManager` that
+grants access to the active `Span` through a `Scope`. Any `Span` may be
+transferred to another callback or thread, but not `Scope`.
 
-It's always possible to create a "root" `Span` with no parent or other causal
-reference.
+#### Accessing the active Span through Scope
 
 ```ruby
-span = OpenTracing.start_span("operation_name")
-span.finish
+# Access to the active span is straightforward.
+
+span = OpenTracing.active_span
+if span
+  span.set_tag('...', '...')
+end
+
+# or
+
+scope = OpenTracing.scope_manager.active
+if scope
+  scope.span.set_tag('...', '...')
+end
 ```
 
-This example will start a span on the global tracer (initialized above). If
-you are managing your own tracer you'll need to call `start_span` on your
-tracer.
+### Starting a new Span
 
-### Creating a (child) Span given an existing (parent) Span
+The common case starts a `Scope` that's automatically registered for
+intra-process propagation via `ScopeManager`.
+
+Note that `start_active_span('...')` automatically finishes the span on
+`Scope#close` (`start_active_span('...', finish_on_close: false)` does not
+finish it, in contrast).
 
 ```ruby
-span = OpenTracing.start_span("parent")
-child = OpenTracing.start_span("child", child_of: span)
-child.finish
-span.finish
+# Automatic activation of the Span.
+# By default the active span will be finished when the returned scope is closed.
+# This can be controlled by passing finish_on_close parameter to
+# start_active_span
+scope = OpenTracing.start_active_span('operation_name')
+# Do things.
+
+# Block form of start_active_span
+# start_active_span optionally accepts a block. If a block is passed to
+# start_active_span it will yield the newly created scope. The scope will
+# be closed and its associated span will be finished unless
+# finish_on_close: false is passed to start_active_span.
+OpenTracing.start_active_span('operation_name') do |scope|
+# Do things.
+end
+
+# Manual activation of the Span.
+# Spans can be managed manually. This is equivalent to the more concise examples
+# above.
+span = OpenTracing.start_span('operation_name')
+OpenTracing.scope_manager.activate(span)
+scope = OpenTracing.scope_manager.active
+# Do things.
+
+# If there is an active Scope, it will act as the parent to any newly started
+# Span unless ignore_active_scope: true is passed to start_span or
+# start_active_span.
+
+# create a root span, ignoring the currently active scope (if it's set)
+scope = OpenTracing.start_active_span('operation_name', ignore_active_scope: true)
+
+# or
+span = OpenTracing.start_span('operation_name', ignore_active_scope: true)
+
+# It's possible to create a child Span given an existing parent Span by
+# using the child_of option.
+
+parent_scope = OpenTracing.start_active_span('parent_operation, ignore_active_scope: true)
+child_scope = OpenTracing.start_active_span('child_operation', child_of: parent_scope.span)
+
+# or
+parent_span = OpenTracing.start_span('parent_operation', ignore_active_scope: true)
+child_span = OpenTracing.start_span('child_operation', child_of: parent_span)
+
 ```
 
 ### Serializing to the wire
@@ -130,7 +193,6 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/opentracing/opentracing-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
+## Licensing
 
-## License
-
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+[Apache 2.0 License](./LICENSE).

data/Rakefile

@@ -1,10 +1,17 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rubocop/rake_task'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
+  t.libs << 'test'
+  t.libs << 'lib'
   t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+RuboCop::RakeTask.new(:rubocop)
+
+if RUBY_PLATFORM == 'java'
+  task default: :test
+else
+  task default: %i[rubocop test]
+end

data/bin/console

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "opentracing"
-require "irb"
+require 'bundler/setup'
+require 'opentracing'
+require 'irb'
 IRB.start

data/lib/opentracing.rb

@@ -1,12 +1,13 @@
-require "forwardable"
-require "opentracing/version"
-require "opentracing/span_context"
-require "opentracing/span"
-require "opentracing/reference"
-require "opentracing/tracer"
-require "opentracing/scope"
-require "opentracing/scope_manager"
+require 'forwardable'
+require 'opentracing/version'
+require 'opentracing/span_context'
+require 'opentracing/span'
+require 'opentracing/reference'
+require 'opentracing/tracer'
+require 'opentracing/scope'
+require 'opentracing/scope_manager'
 
+#:nodoc:
 module OpenTracing
   # Text format for Tracer#inject and Tracer#extract.
   #
@@ -35,7 +36,17 @@ module OpenTracing
     extend Forwardable
     # Global tracer to be used when OpenTracing.start_span, inject or extract is called
     attr_accessor :global_tracer
-    def_delegators :global_tracer, :start_span, :inject, :extract
+    def_delegators :global_tracer, :scope_manager, :start_active_span,
+                   :start_span, :inject, :extract
+
+    # Convenience method to access the currently active span. This is equivalent
+    # to calling `OpenTracing.scope_manager.active.span`
+    #
+    # @return [Span, nil] the currently active span or nil
+    def active_span
+      scope = scope_manager.active
+      scope.span if scope
+    end
   end
 end
 

data/lib/opentracing/carrier.rb

@@ -6,20 +6,17 @@ module OpenTracing
     # [] retrieves a value by the given key
     # @param key [String] key to retrieve the value
     # @return [String] the desired value
-    def [](key)
-    end
+    def [](key); end
 
     # []= sets the value for the given key
     # @param key [String] key to set
     # @param value [String] value to set
-    def []=(key, value)
-    end
+    def []=(key, value); end
 
     # each iterates over every key-value pair in the carrier
     # @yield [key, value]
     # @yieldparam key [String] the key of the tuple
     # @yieldparam value [String] the value of the tuple
-    def each(&block)
-    end
+    def each(&block); end
   end
 end

data/lib/opentracing/reference.rb

@@ -1,4 +1,5 @@
 module OpenTracing
+  #:nodoc:
   class Reference
     CHILD_OF = 'child_of'.freeze
     FOLLOWS_FROM = 'follows_from'.freeze

data/lib/opentracing/scope.rb

@@ -17,7 +17,6 @@ module OpenTracing
     #
     # NOTE: Calling close more than once on a single Scope instance leads to
     # undefined behavior.
-    def close
-    end
+    def close; end
   end
 end

data/lib/opentracing/scope_manager.rb

@@ -6,7 +6,7 @@ module OpenTracing
   # 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
 

data/lib/opentracing/span.rb

@@ -8,8 +8,7 @@ module OpenTracing
     # Set the name of the operation
     #
     # @param [String] name
-    def operation_name=(name)
-    end
+    def operation_name=(name); end
 
     # Span Context
     #
@@ -49,7 +48,7 @@ module OpenTracing
     # @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."
+      warn 'Span#log is deprecated.  Please use Span#log_kv instead.'
       nil
     end
 

data/lib/opentracing/span_context.rb

@@ -9,7 +9,6 @@ module OpenTracing
     # @param id the ID of the Context
     # @param trace_id the ID of the current trace
     # @param baggage baggage
-    def initialize(baggage: {})
-    end
+    def initialize(baggage: {}); end
   end
 end

data/lib/opentracing/tracer.rb

@@ -1,4 +1,10 @@
 module OpenTracing
+  # Tracer is the entry point API between instrumentation code and the tracing
+  # implementation.
+  #
+  # This implementation both defines the public Tracer API, and provides a
+  # default no-op behavior.
+  #
   class Tracer
     # @return [ScopeManager] the current ScopeManager, which may be a no-op but
     #   may not be nil.

data/lib/opentracing/version.rb

@@ -1,3 +1,3 @@
 module OpenTracing
-  VERSION = "0.4.0"
+  VERSION = '0.4.1'.freeze
 end

data/opentracing.gemspec

@@ -1,28 +1,29 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'opentracing/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "opentracing"
+  spec.name          = 'opentracing'
   spec.version       = OpenTracing::VERSION
-  spec.authors       = ["ngauthier", "bcronin", "bensigelman"]
-  spec.email         = ["info@opentracing.io"]
+  spec.authors       = %w[ngauthier bcronin bensigelman]
+  spec.email         = ['info@opentracing.io']
 
-  spec.summary       = %q{OpenTracing Ruby Platform API}
-  spec.homepage      = "https://github.com/opentracing/opentracing-ruby"
-  spec.license       = "MIT"
+  spec.summary       = 'OpenTracing Ruby Platform API'
+  spec.homepage      = 'https://github.com/opentracing/opentracing-ruby'
+  spec.license       = 'Apache 2.0'
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "simplecov"
-  spec.add_development_dependency "simplecov-console"
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rubocop', '~> 0.54.0'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'simplecov-console'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentracing
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - ngauthier
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-29 00:00:00.000000000 Z
+date: 2018-04-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -26,6 +26,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -41,19 +55,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '10.0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: 0.54.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: 0.54.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -112,7 +126,7 @@ files:
 - opentracing.gemspec
 homepage: https://github.com/opentracing/opentracing-ruby
 licenses:
-- MIT
+- Apache 2.0
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -130,7 +144,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: OpenTracing Ruby Platform API