opentracing 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 84c20bed4ece804815cff59b3e3e067eb73543d2
-  data.tar.gz: 8729f8d1f4e0fdbd49e2da64b83d35394b6f65c9
+  metadata.gz: 1aa24a8243b5906145ca38a2a509066fa09024aa
+  data.tar.gz: 42cac5a5c026b285037f94d5e2f27c3d80512e58
 SHA512:
-  metadata.gz: 0178247abf3ec2fb5f360a1e9470a2bacd49b62ba6d596bd17b608d179addf3c8b7645ac6b405bc9d46df7ca259be0104b818abe5dc323c48c05046b6d121c45
-  data.tar.gz: 13ec6bfa63a2dd8a41d75a6500f4f8b077c7cfb8e80bdcac5a3e536c535a1d455f255c095a46550ac26efe7c758190b95cfab38fc87d5825d43a29efa93e5430
+  metadata.gz: 5889805e61bec036ddde3905e451c263efd7648d3e0ff342e6a09d6e871301379e1e4e8f290fc4ce7cb06035de486059133af2a1ee8b8f48f97d074f4fe4b0ee
+  data.tar.gz: 9159f82bae1df53113dff8ff34d28f096bb43dc51b557f65beffa0b83ff660e832dcae5b9a3d7b4a23002201d1a4ab950605786b02fa385b5a98bd0886c374ea

data/README.md

@@ -80,7 +80,7 @@ client = Net::HTTP.new("http://myservice")
 req = Net::HTTP::Post.new("/")
 
 span = OpenTracing.start_span("my_span")
-OpenTracing.inject(span.context, OpenTracing::FORMAT_HTTP_HEADER, req)
+OpenTracing.inject(span.context, OpenTracing::FORMAT_RACK, env)
 res = client.request(req)
 #...
 ```
@@ -96,7 +96,8 @@ it will not be possible to discern once Rack has processed it.
 ```ruby
 class MyRackApp
   def call(env)
-    span = @tracer.extract("my_app", OpenTracing::FORMAT_RACK, env, OpenTracing.global_tracer)
+    extracted_ctx = @tracer.extract(OpenTracing::FORMAT_RACK, env)
+    span = @tracer.start_span("my_app", child_of: extracted_ctx)
     span.finish
     [200, {}, ["hello"]]
   end

data/lib/opentracing.rb

@@ -5,14 +5,27 @@ require "opentracing/span"
 require "opentracing/tracer"
 
 module OpenTracing
-  # Text format for #inject and #extract
+  # Text format for Tracer#inject and Tracer#extract.
+  #
+  # The carrier for FORMAT_TEXT_MAP should be a Hash with string values.
   FORMAT_TEXT_MAP = 1
 
   # Binary format for #inject and #extract
+  #
+  # The carrier for FORMAT_BINARY should be a string, treated as a raw sequence
+  # of bytes.
   FORMAT_BINARY = 2
 
-  # Ruby Specific format to handle how Rack changes environment variables.
-  # See Readme.md for more info.
+  # Due to Rack's popularity within the Ruby community, OpenTracing-Ruby
+  # provides a Rack-specific format for injection into and extraction from HTTP
+  # headers specifically, though there are some strings attached.
+  #
+  # The carrier for FORMAT_RACK should be `env` or equivalent. It behaves like
+  # FORMAT_TEXT_MAP, but with all keys transformed per Rack's treatment of HTTP
+  # headers. Keep in mind that Rack automatically uppercases all headers and
+  # replaces dashes with underscores. This means that if you use dashes and
+  # underscores and case-sensitive baggage keys, they may collide or become
+  # unrecognizable.
   FORMAT_RACK = 3
 
   class << self

data/lib/opentracing/tracer.rb

@@ -1,19 +1,25 @@
 module OpenTracing
   class Tracer
-    # Start a new span
-    # @param operation_name [String] The name of the operation represented by the span
-    # @param child_of [Span] A span to be used as the ChildOf reference
-    # @param start_time [Time] the start time of the span
-    # @param tags [Hash] Starting tags for the span
-    def start_span(operation_name, child_of: nil, start_time: nil, tags: nil)
+    # 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
+    #        the newly-started Span. If a Span instance is provided, its
+    #        .span_context is automatically substituted.
+    # @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)
       Span::NOOP_INSTANCE
     end
 
-
-    # Inject a span into the given carrier
+    # Inject a SpanContext into the given carrier
+    #
     # @param span_context [SpanContext]
     # @param format [OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK]
-    # @param carrier [Carrier]
+    # @param carrier [Carrier] A carrier object of the type dictated by the specified `format`
     def inject(span_context, format, carrier)
       case format
       when OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK
@@ -23,13 +29,12 @@ module OpenTracing
       end
     end
 
-    # Extract a span from a carrier
-    # @param operation_name [String]
+    # Extract a SpanContext in the given format from the given carrier.
+    #
     # @param format [OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK]
-    # @param carrier [Carrier]
-    # @param tracer [Tracer] the tracer the span will be attached to (for finish)
-    # @return [Span]
-    def extract(operation_name, format, carrier)
+    # @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
+    def extract(format, carrier)
       case format
       when OpenTracing::FORMAT_TEXT_MAP, OpenTracing::FORMAT_BINARY, OpenTracing::FORMAT_RACK
         return SpanContext::NOOP_INSTANCE

data/lib/opentracing/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentracing
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - ngauthier
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-01-05 00:00:00.000000000 Z
+date: 2017-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler