opentracing 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1aa24a8243b5906145ca38a2a509066fa09024aa
-  data.tar.gz: 42cac5a5c026b285037f94d5e2f27c3d80512e58
+  metadata.gz: 61ca714ff9464163db6bb5a8a868c2047c107980
+  data.tar.gz: 8c796e19b4a5ce768e24e4479260a55de79c5c95
 SHA512:
-  metadata.gz: 5889805e61bec036ddde3905e451c263efd7648d3e0ff342e6a09d6e871301379e1e4e8f290fc4ce7cb06035de486059133af2a1ee8b8f48f97d074f4fe4b0ee
-  data.tar.gz: 9159f82bae1df53113dff8ff34d28f096bb43dc51b557f65beffa0b83ff660e832dcae5b9a3d7b4a23002201d1a4ab950605786b02fa385b5a98bd0886c374ea
+  metadata.gz: 79a42b7afe696afe3d476e778de5dc71889dea2b24e49206bd2201e7245b470fea039c3ce0510bcabc9dff46f90879fd5eeba237cb50b6a3beddc487848b78e0
+  data.tar.gz: 5ffb674ee8757cff0944129872bf8929f6987430adc2380a6b54e865482a41d93355d342a9bd3fea249f15d7217e657a1b3094a63594978b60b1294b51eb260d

data/.travis.yml

@@ -1,5 +1,8 @@
 sudo: false
 language: ruby
 rvm:
-- 2.3.1
+  - 2.3.4
+  - 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

data/README.md

@@ -75,16 +75,30 @@ span.finish
 
 ### Serializing to the wire
 
+Using `Net::HTTP`:
 ```ruby
 client = Net::HTTP.new("http://myservice")
 req = Net::HTTP::Post.new("/")
 
 span = OpenTracing.start_span("my_span")
-OpenTracing.inject(span.context, OpenTracing::FORMAT_RACK, env)
+OpenTracing.inject(span.context, OpenTracing::FORMAT_RACK, req)
 res = client.request(req)
 #...
 ```
 
+Using Faraday middleware:
+```ruby
+class TraceMiddleware < Faraday::Middleware
+  def call(env)
+    span = OpenTracing.start_span("my_span")
+    OpenTracing.inject(span.context, OpenTracing::FORMAT_RACK, env)
+    @app.call(env).on_complete do
+      span.finish
+    end
+  end
+end
+```
+
 ### Deserializing from the wire
 
 The OpenTracing Ruby gem provides a specific Rack header extraction format,

data/lib/opentracing.rb

@@ -2,6 +2,7 @@ require "forwardable"
 require "opentracing/version"
 require "opentracing/span_context"
 require "opentracing/span"
+require "opentracing/reference"
 require "opentracing/tracer"
 
 module OpenTracing
@@ -30,8 +31,8 @@ module OpenTracing
 
   class << self
     extend Forwardable
-    # Global tracer to be used when OpenTracing.start_span is called
+    # Global tracer to be used when OpenTracing.start_span, inject or extract is called
     attr_accessor :global_tracer
-    def_delegator :global_tracer, :start_span
+    def_delegators :global_tracer, :start_span, :inject, :extract
   end
 end

data/lib/opentracing/reference.rb

@@ -0,0 +1,88 @@
+module OpenTracing
+  class Reference
+    CHILD_OF = 'child_of'.freeze
+    FOLLOWS_FROM = 'follows_from'.freeze
+
+    # @param context [SpanContext, Span] child_of context refers to a
+    #   parent Span that caused *and* somehow depends upon the new child Span.
+    #   Often (but not always), the parent Span cannot finish until the child
+    #   Span does.
+    #
+    #   An timing diagram for a child Span that is blocked on the new Span:
+    #
+    #     [-Parent Span----------]
+    #          [-Child Span----]
+    #
+    #   See http://opentracing.io/documentation/pages/spec
+    #
+    # @return [Reference] a ChildOf reference
+    #
+    # @example
+    #   root_span = OpenTracing.start_span('root operation')
+    #   child_span = OpenTracing.start_span('child operation', references: [
+    #     OpenTracing::Reference.child_of(root_span)
+    #   ])
+    #
+    def self.child_of(context)
+      if context.is_a?(Span)
+        context = context.context
+      end
+
+      Reference.new(CHILD_OF, context)
+    end
+
+    # @param context [SpanContext, Span] follows_from context refers to a
+    #   parent Span that does not depend in any way on the result of the new
+    #   child Span. For instance, one might use FollowsFrom Span to describe
+    #   pipeline stages separated by queues, or a fire-and-forget cache insert
+    #   at the tail end of a web request.
+    #
+    #   A FollowsFrom Span is part of the same logical trace as the new Span:
+    #   i.e., the new Span is somehow caused by the work of its FollowsFrom
+    #   Span.
+    #
+    #   All of the following could be valid timing diagrams for children that
+    #   "FollowFrom" a parent:
+    #
+    #     [-Parent Span--]  [-Child Span-]
+    #
+    #     [-Parent Span--]
+    #      [-Child Span-]
+    #
+    #     [-Parent Span-]
+    #                [-Child Span-]
+    #
+    #   See http://opentracing.io/documentation/pages/spec
+    #
+    # @return [Reference] a FollowsFrom reference
+    #
+    # @example
+    #   context = OpenTracing.extract(OpenTracing::FORMAT_RACK, rack_env)
+    #   span = OpenTracing.start_span('following operation', references: [
+    #     OpenTracing::Reference.follows_from(context)
+    #   ])
+    #
+    def self.follows_from(context)
+      if context.is_a?(Span)
+        context = context.context
+      end
+
+      Reference.new(FOLLOWS_FROM, context)
+    end
+
+    def initialize(type, context)
+      @type = type
+      @context = context
+    end
+
+    # Return [String] reference type
+    def type
+      @type
+    end
+
+    # @return [SpanContext] the context of a span this reference is referencing
+    def context
+      @context
+    end
+  end
+end

data/lib/opentracing/span.rb

@@ -1,27 +1,23 @@
 module OpenTracing
-  # Span represents an OpenTracer Span
+  # Span represents an OpenTracing Span
   #
   # See http://www.opentracing.io for more information.
   class Span
     NOOP_INSTANCE = Span.new.freeze
 
     # Set the name of the operation
+    #
+    # @param [String] name
     def operation_name=(name)
     end
 
     # Span Context
+    #
+    # @return [SpanContext]
     def context
       SpanContext::NOOP_INSTANCE
     end
 
-    # Creates a new {Span}
-    #
-    # @param tracer [Tracer] the tracer that created this span
-    # @param context [SpanContext] the context of the span
-    # @return [Span] a new Span
-    def initialize(tracer:, context:)
-    end
-
     # Set a tag value on this span
     # @param key [String] the key of the tag
     # @param value [String, Numeric, Boolean] the value of the tag. If it's not
@@ -39,7 +35,7 @@ module OpenTracing
 
     # Get a baggage item
     # @param key [String] the key of the baggage item
-    # @return Value of the baggage item
+    # @return [String] value of the baggage item
     def get_baggage_item(key)
       nil
     end

data/lib/opentracing/tracer.rb

@@ -1,17 +1,25 @@
 module OpenTracing
   class Tracer
-    # TODO(bhs): Support FollowsFrom and multiple references
-
     # Starts a new span.
     #
     # @param operation_name [String] The operation name for the Span
-    # @param child_of [SpanContext] SpanContext that acts as a parent to
+    #
+    # @param child_of [SpanContext, Span] SpanContext that acts as a parent to
     #        the newly-started Span. If a Span instance is provided, its
-    #        .span_context is automatically substituted.
+    #        context is automatically substituted. See [Reference] for more
+    #        information.
+    #
+    #   If specified, the `references` paramater 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
+    #
     # @return [Span] The newly-started Span
-    def start_span(operation_name, child_of: nil, start_time: Time.now, tags: nil)
+    def start_span(operation_name, child_of: nil, references: nil, start_time: Time.now, tags: nil)
       Span::NOOP_INSTANCE
     end
 
@@ -33,7 +41,7 @@ module OpenTracing
     #
     # @param format [OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK]
     # @param carrier [Carrier] A carrier object of the type dictated by the specified `format`
-    # @return [SpanContext] the extracted SpanContext or nil if none could be found
+    # @return [SpanContext, nil] the extracted SpanContext or nil if none could be found
     def extract(format, carrier)
       case format
       when OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK

data/lib/opentracing/version.rb

@@ -1,3 +1,3 @@
 module OpenTracing
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentracing
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - ngauthier
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-02-16 00:00:00.000000000 Z
+date: 2017-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -101,6 +101,7 @@ files:
 - bin/setup
 - lib/opentracing.rb
 - lib/opentracing/carrier.rb
+- lib/opentracing/reference.rb
 - lib/opentracing/span.rb
 - lib/opentracing/span_context.rb
 - lib/opentracing/tracer.rb