opencensus 0.3.1 → 0.4.0

data/lib/opencensus/trace/integrations/rack_middleware.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "opencensus"
 
 module OpenCensus
@@ -76,7 +77,7 @@ module OpenCensus
             trace_context: context,
             same_process_as_parent: false do |span_context|
             begin
-              span_context.in_span get_path(env) do |span|
+              Trace.in_span get_path(env) do |span|
                 start_request span, env
                 @app.call(env).tap do |response|
                   finish_request span, response
@@ -100,30 +101,21 @@ module OpenCensus
           env["HTTP_HOST"] || env["SERVER_NAME"]
         end
 
-        def get_url env
-          path = get_path env
-          host = get_host env
-          scheme = env["SERVER_PROTOCOL"]
-          query_string = env["QUERY_STRING"].to_s
-          url = "#{scheme}://#{host}#{path}"
-          url = "#{url}?#{query_string}" unless query_string.empty?
-          url
-        end
-
         def start_request span, env
           span.kind = SpanBuilder::SERVER
-          span.put_attribute "/http/host", get_host(env)
-          span.put_attribute "/http/url", get_url(env)
-          span.put_attribute "/http/method", env["REQUEST_METHOD"]
-          span.put_attribute "/http/client_protocol", env["SERVER_PROTOCOL"]
-          span.put_attribute "/http/user_agent", env["HTTP_USER_AGENT"]
-          span.put_attribute "/pid", ::Process.pid.to_s
-          span.put_attribute "/tid", ::Thread.current.object_id.to_s
+          span.put_attribute "http.host", get_host(env)
+          span.put_attribute "http.path", get_path(env)
+          span.put_attribute "http.method", env["REQUEST_METHOD"].to_s.upcase
+          if env["HTTP_USER_AGENT"]
+            span.put_attribute "http.user_agent", env["HTTP_USER_AGENT"]
+          end
         end
 
         def finish_request span, response
           if response.is_a?(::Array) && response.size == 3
-            span.set_status response[0]
+            http_status = response[0]
+            span.set_http_status http_status
+            span.put_attribute "http.status_code", http_status
           end
         end
       end

data/lib/opencensus/trace/integrations/rails.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "active_support"
 require "rails/railtie"
 require "opencensus/trace/integrations/rack_middleware"

data/lib/opencensus/trace/link.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module OpenCensus
   module Trace
     ##
@@ -21,15 +22,24 @@ module OpenCensus
     # traces or when the handler receives a request from a different project.
     #
     class Link
-      # The relationship of the two spans is unknown, or known but other
-      # than parent-child.
-      TYPE_UNSPECIFIED    = :TYPE_UNSPECIFIED
+      ##
+      # A link type, indicating the relationship of the two spans is unknown,
+      # or is known but is other than parent-child.
+      # @return [Symbol]
+      #
+      TYPE_UNSPECIFIED = :TYPE_UNSPECIFIED
 
-      # The linked span is a child of the current span.
-      CHILD_LINKED_SPAN   = :CHILD_LINKED_SPAN
+      ##
+      # A link type, indicating the linked span is a child of the current span.
+      # @return [Symbol]
+      #
+      CHILD_LINKED_SPAN = :CHILD_LINKED_SPAN
 
-      # The linked span is a parent of the current span.
-      PARENT_LINKED_SPAN  = :PARENT_LINKED_SPAN
+      ##
+      # A link type, indicating the linked span is a parent of the current span.
+      # @return [Symbol]
+      #
+      PARENT_LINKED_SPAN = :PARENT_LINKED_SPAN
 
       ##
       # A unique identifier for a trace. All spans from the same trace share

data/lib/opencensus/trace/message_event.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "opencensus/trace/time_event"
 
 module OpenCensus
@@ -20,13 +21,22 @@ module OpenCensus
     # An event describing a message sent/received between Spans.
     #
     class MessageEvent < TimeEvent
-      # Unknown event type.
+      ##
+      # An event type, indicating the type is unknown.
+      # @return [Symbol]
+      #
       TYPE_UNSPECIFIED = :TYPE_UNSPECIFIED
 
-      # Indicates a sent message.
+      ##
+      # An event type, indicating a sent message.
+      # @return [Symbol]
+      #
       SENT = :SENT
 
-      # Indicates a received message.
+      ##
+      # An event type, indicating a received message.
+      # @return [Symbol]
+      #
       RECEIVED = :RECEIVED
 
       ##

data/lib/opencensus/trace/samplers.rb

@@ -12,10 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "opencensus/trace/samplers/always_sample"
 require "opencensus/trace/samplers/never_sample"
 require "opencensus/trace/samplers/probability"
-require "opencensus/trace/samplers/max_qps"
+require "opencensus/trace/samplers/rate_limiting"
 
 module OpenCensus
   module Trace
@@ -26,19 +27,22 @@ module OpenCensus
     # use a sampler to decide, for a given request, whether to report its
     # trace.
     #
-    # The OpenCensus specification defines three samplers: AlwaysSample,
-    # NeverSample, and Probability. The Ruby implementation also provides a
-    # fourth, MaxQPS, based on the Stackdriver library.
+    # The OpenCensus specification defines four samplers:
+    # {OpenCensus::Trace::Samplers::AlwaysSample},
+    # {OpenCensus::Trace::Samplers::NeverSample},
+    # {OpenCensus::Trace::Samplers::Probability}, and
+    # {OpenCensus::Trace::Samplers::RateLimiting}.
     #
-    # A sampler is a Proc that takes a hash of environment information and
+    # A sampler is a `Proc` that takes a hash of environment information and
     # returns a boolean indicating whether or not to sample the current
-    # request. Alternately, it could be an object that duck-types the Proc
+    # request. Alternately, it could be an object that duck-types the `Proc`
     # interface by implementing the `call` method. The hash passed to `call`
     # may contain the following keys, all of which are optional. Samplers must
     # adjust their behavior to account for the availability or absence of any
     # environment information:
     #
-    # *   `span_context` The SpanContext that created the span being sampled.
+    # *   `span_context` The {OpenCensus::Trace::SpanContext} that created the
+    #      span being sampled.
     # *   `rack_env` The hash of Rack environment information
     #
     # Applications may set a default sampler in the config. In addition, the

data/lib/opencensus/trace/samplers/always_sample.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module OpenCensus
   module Trace
     module Samplers

data/lib/opencensus/trace/samplers/never_sample.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module OpenCensus
   module Trace
     module Samplers

data/lib/opencensus/trace/samplers/probability.rb

@@ -12,6 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
+require "monitor"
+
 module OpenCensus
   module Trace
     module Samplers
@@ -21,9 +24,9 @@ module OpenCensus
       #
       class Probability
         ##
-        # The default sampling probability.
+        # The default sampling probability, equal to 1/10000.
         #
-        DEFAULT_RATE = 0.1
+        DEFAULT_RATE = 0.0001
 
         ##
         # Create a sampler for the given probability.
@@ -39,6 +42,7 @@ module OpenCensus
           end
           @rate = rate
           @rng = rng || Random.new
+          @lock = Monitor.new
         end
 
         ##
@@ -47,8 +51,10 @@ module OpenCensus
         #
         # @param [Hash] opts The options to sample with.
         # @option opts [SpanContext] :span_context If provided, the span context
-        #         will be used to generate a deterministic value in place of the
-        #         pseudo-random number generator.        #
+        #         will be checked and the parent's sampling decision will be
+        #         propagated if the parent was sampled. The span context will
+        #         also be used to generate a deterministic value in place of the
+        #         pseudo-random number generator.
         # @return [boolean] Whether to sample at this time.
         #
         def call opts = {}
@@ -59,7 +65,9 @@ module OpenCensus
               (span_context.trace_id.to_i(16) % 0x10000000000000000).to_f /
                 0x10000000000000000
             else
-              @rng.rand
+              @lock.synchronize do
+                @rng.rand
+              end
             end
           value <= @rate
         end

data/lib/opencensus/trace/samplers/rate_limiting.rb

@@ -0,0 +1,74 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "monitor"
+
+module OpenCensus
+  module Trace
+    module Samplers
+      ##
+      # The RateLimiting sampler delays a minimum amount of time between each
+      # sample, enforcing a maximum QPS across traces that use this sampler.
+      #
+      class RateLimiting
+        ##
+        # Default rate in samples per second.
+        #
+        DEFAULT_RATE = 0.1
+
+        ##
+        # Create a sampler for the given QPS.
+        #
+        # @param [Number] qps Samples per second. Default is {DEFAULT_RATE}.
+        # @param [#rand] rng The random number generator to use. Default is a
+        #     new `::Random` instance.
+        # @param [#now] time_class The time class to use. Default is `::Time`.
+        #     Generally used for testing.
+        #
+        def initialize qps = DEFAULT_RATE, rng: nil, time_class: nil
+          @qps = qps
+          @time_class = time_class || Time
+          @rng = rng || Random.new
+          @last_time = @time_class.now.to_f
+          @lock = Monitor.new
+        end
+
+        ##
+        # Implements the sampler contract. Checks to see whether a sample
+        # should be taken at this time.
+        #
+        # @param [Hash] opts The options to sample with.
+        # @option opts [SpanContext] :span_context If provided, the span context
+        #         will be checked and the parent's sampling decision will be
+        #         propagated if the parent was sampled.
+        # @return [boolean] Whether to sample at this time.
+        #
+        def call opts = {}
+          span_context = opts[:span_context]
+          return true if span_context && span_context.sampled?
+          @lock.synchronize do
+            time = @time_class.now.to_f
+            elapsed = time - @last_time
+            @last_time = time
+            @rng.rand <= elapsed * @qps
+          end
+        end
+      end
+
+      # MaxQPS is an older, deprecated name for the RateLimiting sampler.
+      MaxQPS = RateLimiting
+    end
+  end
+end

data/lib/opencensus/trace/span.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module OpenCensus
   module Trace
     ##
@@ -20,18 +21,23 @@ module OpenCensus
     # or have a parent span, and may have zero or more children.
     #
     class Span
-      ## The span kind is unspecified
+      ##
+      # A span kind, indicating the span kind is unspecified.
+      # @return [Symbol]
+      #
       SPAN_KIND_UNSPECIFIED = :SPAN_KIND_UNSPECIFIED
 
       ##
-      # Indicates that the span covers server-side handling of an RPC or other
-      # remote network request.
+      # A span kind, indicating that the span covers server-side handling of an
+      # RPC or other remote network request.
+      # @return [Symbol]
       #
       SERVER = :SERVER
 
       ##
-      # Indicates that the span covers the client-side wrapper around an RPC
-      # or other remote request.
+      # A span kind, indicating that the span covers the client-side wrapper
+      # around an RPC or other remote request.
+      # @return [Symbol]
       #
       CLIENT = :CLIENT
 

data/lib/opencensus/trace/span_builder.rb

@@ -12,39 +12,62 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module OpenCensus
   module Trace
     ##
     # Span represents a single span within a request trace.
     #
     class SpanBuilder
-      ## The type of a message event or link is unknown.
+      ##
+      # This value may be used as an event type or a link type, and indicates
+      # that the type is unknown.
+      # @return [Symbol]
+      #
       TYPE_UNSPECIFIED = :TYPE_UNSPECIFIED
 
-      ## Indicates a sent message.
+      ##
+      # An event type, indicating a sent message.
+      # @return [Symbol]
+      #
       SENT = :SENT
 
-      ## Indicates a received message.
+      ##
+      # An event type, indicating a received message.
+      # @return [Symbol]
+      #
       RECEIVED = :RECEIVED
 
-      ## The linked span is a child of the current span.
+      ##
+      # A link type, indicating the linked span is a child of the current span.
+      # @return [Symbol]
+      #
       CHILD_LINKED_SPAN = :CHILD_LINKED_SPAN
 
-      ## The linked span is a parent of the current span.
+      ##
+      # A link type, indicating the linked span is a parent of the current span.
+      # @return [Symbol]
+      #
       PARENT_LINKED_SPAN = :PARENT_LINKED_SPAN
 
-      ## The span kind is unspecified
+      ##
+      # A span kind, indicating that the span is either neither a server nor
+      # a client, or is unknown.
+      # @return [Symbol]
+      #
       SPAN_KIND_UNSPECIFIED = :SPAN_KIND_UNSPECIFIED
 
       ##
-      # Indicates that the span covers server-side handling of an RPC or other
-      # remote network request.
+      # A span kind, indicating that the span covers server-side handling of an
+      # RPC or other remote network request.
+      # @return [Symbol]
       #
       SERVER = :SERVER
 
       ##
-      # Indicates that the span covers the client-side wrapper around an RPC
-      # or other remote request.
+      # A span kind, indicating that the span covers the client-side wrapper
+      # around an RPC or other remote request.
+      # @return [Symbol]
       #
       CLIENT = :CLIENT
 
@@ -84,12 +107,14 @@ module OpenCensus
       end
 
       ##
-      # Sampling decision for this span. Generally this field is set when the
-      # span is first created. However, you can also change it after the fact.
+      # Sampling decision for this span.
       #
       # @return [boolean]
       #
-      attr_accessor :sampled
+      def sampled?
+        context.sampled?
+      end
+      alias sampled sampled?
 
       ##
       # A description of the span's operation.
@@ -108,8 +133,9 @@ module OpenCensus
       ##
       # The kind of span. Can be used to specify additional relationships
       # between spans in addition to a parent/child relationship.
-      # Valid values are `SpanBuilder::CLIENT`, `SpanBuilder::SERVER`, and
-      # `SpanBuilder::SPAN_KIND_UNSPECIFIED`.
+      # Valid values are {OpenCensus::Trace::SpanBuilder::CLIENT},
+      # {OpenCensus::Trace::SpanBuilder::SERVER}, and
+      # {OpenCensus::Trace::SpanBuilder::SPAN_KIND_UNSPECIFIED}.
       #
       # This field is required.
       #
@@ -135,7 +161,7 @@ module OpenCensus
       # the local machine where the span execution ends. On the server side,
       # this is the time when the server application handler stops running.
       #
-      # In Ruby, this is represented by a Time object in UTC, or `nil` if the
+      # In Ruby, this is represented by a `Time` object in UTC, or `nil` if the
       # starting timestamp has not yet been populated.
       #
       # @return [Time, nil]
@@ -214,12 +240,14 @@ module OpenCensus
       # Add an event describing a message sent/received between spans.
       #
       # @param [Symbol] type The type of MessageEvent. Indicates whether the
-      #     message was sent or received. Valid values are `SpanBuilder::SENT`
-      #     `SpanBuilder::RECEIVED`, and `SpanBuilder::TYPE_UNSPECIFIED`.
+      #     message was sent or received. Valid values are
+      #     {OpenCensus::Trace::SpanBuilder::SENT},
+      #     {OpenCensus::Trace::SpanBuilder::RECEIVED}, and
+      #     {OpenCensus::Trace::SpanBuilder::TYPE_UNSPECIFIED}.
       # @param [Integer] id An identifier for the MessageEvent's message that
       #     can be used to match SENT and RECEIVED events. For example, this
       #     field could represent a sequence ID for a streaming RPC. It is
-      #     recommended to be unique within a Span. The valid range is 64-bit
+      #     recommended to be unique within a span. The valid range is 64-bit
       #     unsigned `(0..2^64-1)`
       # @param [Integer] uncompressed_size The number of uncompressed bytes
       #     sent or received.
@@ -250,9 +278,10 @@ module OpenCensus
       # @param [String] span_id The unique identifier for a span within a trace.
       #     An 8-byte array expressed as 16 hex digits.
       # @param [Symbol] type The relationship of the current span relative to
-      #     the linked span. Valid values are `SpanBuilder::CHILD_LINKED_SPAN`,
-      #     `SpanBuilder::PARENT_LINKED_SPAN`, and
-      #     `SpanBuilder::TYPE_UNSPECIFIED`.
+      #     the linked span. Valid values are
+      #     {OpenCensus::Trace::SpanBuilder::CHILD_LINKED_SPAN},
+      #     {OpenCensus::Trace::SpanBuilder::PARENT_LINKED_SPAN}, and
+      #     {OpenCensus::Trace::SpanBuilder::TYPE_UNSPECIFIED}.
       # @param [String] attributes Key-value pairs providing additional
       #     properties of the link. Keys must be strings, and values are
       #     restricted to the same types as attributes (see #put_attribute).
@@ -269,21 +298,33 @@ module OpenCensus
       # @param [Integer] code Status code as a 32-bit signed integer
       # @param [String] message A developer-facing error message, which should
       #     be in English.
+      #
       def set_status code, message = ""
         @status_code = code
         @status_message = message
         self
       end
 
+      ##
+      # Set the optional final status for the span using an http status code.
+      #
+      # @param [Integer] code HTTP status code as a 32-bit signed integer
+      # @param [String] message A developer-facing error message, which should
+      #     be in English.
+      #
+      def set_http_status code, message = ""
+        set_status map_http_status(code), message
+      end
+
       ##
       # Set the stack trace for this span.
-      # You may call this in one of three ways:
       #
+      # You may call this in one of three ways:
       # *   Pass in no argument to use the caller's stack trace.
       # *   Pass in an integer to use the caller's stack trace, but skip
       #     additional stack frames.
-      # *   Pass in an explicit array of Thread::Backtrace::Location as
-      #     returned from Kernel#caller_locations
+      # *   Pass in an explicit array of `Thread::Backtrace::Location` as
+      #     returned from `Kernel#caller_locations`
       #
       # @param [Array<Thread::Backtrace::Location>, Integer] stack_trace
       #
@@ -381,9 +422,8 @@ module OpenCensus
       #
       # @private
       #
-      def initialize span_context, sampled, skip_frames: 0
+      def initialize span_context, skip_frames: 0
         @context = span_context
-        @sampled = sampled
         @name = ""
         @kind = SPAN_KIND_UNSPECIFIED
         @start_time = nil
@@ -601,6 +641,23 @@ module OpenCensus
           tstr
         end
       end
+
+      private
+
+      def map_http_status http_status
+        case http_status
+        when 200..399 then Status::OK
+        when 400 then Status::INVALID_ARGUMENT
+        when 401 then Status::UNAUTHENTICATED
+        when 403 then Status::PERMISSION_DENIED
+        when 404 then Status::NOT_FOUND
+        when 429 then Status::RESOURCE_EXHAUSTED
+        when 501 then Status::UNIMPLEMENTED
+        when 503 then Status::UNAVAILABLE
+        when 504 then Status::DEADLINE_EXCEEDED
+        else Status::UNKNOWN
+        end
+      end
     end
   end
 end