opencensus 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b61331cb69913aa2a85bed2353045cf10b97d99
-  data.tar.gz: 6fed28a666fa2741fd7de32a3608c0089b8f7b8c
+  metadata.gz: 42681c2940ade96a318ba521ab0c6d28064a5084
+  data.tar.gz: 06b1d23140c3bb582ba11b0d05c918585c4d073e
 SHA512:
-  metadata.gz: 1afcf27bef5d796b2b08f31bebaccd78ed03ff93e463c24ecaae4a4ff98dd20cc6ccbf9c953cbbfe477018a2ae4091589fdca4584c78a17154961592d0a41e0f
-  data.tar.gz: 4daea1fabb7dff90fbccbb9e043489c6c9f9a5c16714058d9cb87783d025aa5a8adaef175aed3953127ae0a6c653078a8c9c95bd8439c5b9ce75b3d11d42fc07
+  metadata.gz: 132b2e15377b4a6eddb3ca5688fde6dc709bad8189175acd0fb3226840c7bdd5ca01014fc520b18212c808ece97fd21a88860884fbdb016245d841d8f897d413
+  data.tar.gz: 3bed182ab9c3d94f8043e7ce98bcde78da6ce7fefdef8356b320845dffdf0383e2ad5b090e148261244dbc95e188f96c3740df67129432b51f7a24dce480307a

data/.gitignore

@@ -11,3 +11,5 @@
 /docs/_site
 /docs/Gemfile.lock
 /docs/api/
+
+/examples/*/Gemfile.lock

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 0.3.0 / 2018-03-26
+
+* SpanContext#build_contained_spans honors sampling bit.
+* Use AlwaysSample as the default sampler.
+* Support the Span.kind field.
+
 ### 0.2.2 / 2018-03-09
 
 * Railtie now adds the middleware at the end of the stack by default, and provides a config that can customize the position

data/README.md

@@ -77,10 +77,11 @@ into the request so you can potentially connect your request trace with that of
 the remote service. Here is an example:
 
 ```ruby
+require "opencensus/trace/integrations/rack_middleware"
 conn = Faraday.new(url: "http://www.example.com") do |c|
   c.use OpenCensus::Trace::Integrations::FaradayMiddleware
   c.adapter Faraday.default_adapter
-  end
+end
 conn.get "/"
 ```
 

data/examples/hello-world/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gem "faraday", "~> 0.14"
+gem "opencensus", "~> 0.3"
+gem "sinatra", "~> 2.0"

data/examples/hello-world/README.md

@@ -0,0 +1,33 @@
+# Hello World example
+
+This example application demonstrates how to use OpenCensus to record traces for a Sinatra-based web application.
+
+## Prerequisites
+
+Ruby 2.2 or later is required. Make sure you have Bundler installed as well.
+
+    gem install bundler
+
+## Installation
+
+Get the example from the OpenCensus Ruby repository on Github, and cd into the example application directory.
+
+    git clone https://github.com/census-instrumentation/opencensus-ruby.git
+    cd opencensus-ruby/examples/hello-world
+
+Install the dependencies using Bundler.
+
+    bundle install
+
+## Running the example
+
+Run the application locally on your workstation with:
+
+    bundle exec ruby hello.rb
+
+This will run on port 4567 by default, and display application logs on the terminal. From a separate shell, you can send requests using a tool such as curl:
+
+    curl http://localhost:4567/
+    curl http://localhost:4567/lengthy
+
+The running application will log the captured traces.

data/examples/hello-world/hello.rb

@@ -0,0 +1,59 @@
+# Copyright 2018 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.
+
+
+# This is a simple Sinatra application demonstrating how to record traces
+# using OpenCensus.
+#
+# It uses the OpenCensus Rack middleware to trace all incoming requests. It
+# also demonstrates how to use the Faraday middleware to trace outgoing HTTP
+# requests, as well as how to instrument your code to capture custom spans.
+#
+# By default, the resulting trace data is logged in JSON format. You can also
+# configure OpenCensus to report traces to a backend such as Stackdriver or
+# Zipkin using an exporter plugin library.
+
+require "sinatra"
+
+# Install the Rack middleware to trace incoming requests.
+require "opencensus/trace/integrations/rack_middleware"
+use OpenCensus::Trace::Integrations::RackMiddleware
+
+# Access the Faraday middleware which will be used to trace outgoing HTTP
+# requests.
+require "opencensus/trace/integrations/faraday_middleware"
+
+# Each request will be traced automatically by the middleware.
+get "/" do
+  "Hello world!"
+end
+
+# Traces for this request will also include sub-spans as indicated below.
+get "/lengthy" do
+  # Configure this Faraday connection with a middleware to trace outgoing
+  # requests.
+  conn = Faraday.new(url: "http://www.google.com") do |c|
+    c.use OpenCensus::Trace::Integrations::FaradayMiddleware
+    c.adapter Faraday.default_adapter
+  end
+  conn.get "/"
+
+  # You may instrument your code to create custom spans for long-running
+  # operations.
+  OpenCensus::Trace.in_span "long task" do
+    sleep rand
+  end
+
+  "Done!"
+end

data/lib/opencensus/trace.rb

@@ -124,16 +124,18 @@ module OpenCensus
       # Will throw an exception if there is no current SpanContext.
       #
       # @param [String] name Name of the span
+      # @param [Symbol] kind Kind of span. Defaults to unspecified.
       # @param [Sampler] sampler Span-scoped sampler. If not provided,
       #     defaults to the trace configuration's default sampler.
       #
       # @return [SpanBuilder] A SpanBuilder object that you can use to
       #     set span attributes and create children.
       #
-      def start_span name, skip_frames: 0, sampler: nil
+      def start_span name, kind: nil, skip_frames: 0, sampler: nil
         context = span_context
         raise "No currently active span context" unless context
-        span = context.start_span name, skip_frames: skip_frames + 1,
+        span = context.start_span name, kind: kind,
+                                        skip_frames: skip_frames + 1,
                                         sampler: sampler
         self.span_context = span.context
         span
@@ -151,11 +153,13 @@ module OpenCensus
       # will create subspans.
       #
       # @param [String] name Name of the span
+      # @param [Symbol] kind Kind of span. Defaults to unspecified.
       # @param [Sampler] sampler Span-scoped sampler. If not provided,
       #     defaults to the trace configuration's default sampler.
       #
-      def in_span name, skip_frames: 0, sampler: nil
-        span = start_span name, skip_frames: skip_frames + 1, sampler: sampler
+      def in_span name, kind: nil, skip_frames: 0, sampler: nil
+        span = start_span name, kind: kind, skip_frames: skip_frames + 1,
+                                sampler: sampler
         begin
           yield span
         ensure

data/lib/opencensus/trace/config.rb

@@ -20,8 +20,7 @@ module OpenCensus
   module Trace
     # Schema of the Trace configuration. See Trace#configure for more info.
     @config = Common::Config.new do |config|
-      default_sampler =
-        Samplers::Probability.new Samplers::Probability::DEFAULT_RATE
+      default_sampler = Samplers::AlwaysSample.new
       config.add_option! :default_sampler, default_sampler do |value|
         value.respond_to? :call
       end

data/lib/opencensus/trace/exporters/logger.rb

@@ -54,6 +54,7 @@ module OpenCensus
         def format_span span
           {
             name: format_value(span.name),
+            kind: span.kind,
             trace_id: span.trace_id,
             span_id: span.span_id,
             parent_span_id: span.parent_span_id,

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

@@ -145,6 +145,7 @@ module OpenCensus
         # @private Set span attributes from request object
         #
         def start_request span, env
+          span.kind = SpanBuilder::CLIENT
           req_method = env[:method]
           span.put_attribute "/http/method", req_method if req_method
           url = env[:url]

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

@@ -111,6 +111,7 @@ module OpenCensus
         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"]

data/lib/opencensus/trace/span.rb

@@ -20,6 +20,21 @@ module OpenCensus
     # or have a parent span, and may have zero or more children.
     #
     class Span
+      ## The span kind is unspecified
+      SPAN_KIND_UNSPECIFIED = :SPAN_KIND_UNSPECIFIED
+
+      ##
+      # Indicates that the span covers server-side handling of an RPC or other
+      # remote network request.
+      #
+      SERVER = :SERVER
+
+      ##
+      # Indicates that the span covers the client-side wrapper around an RPC
+      # or other remote request.
+      #
+      CLIENT = :CLIENT
+
       ##
       # A unique identifier for a trace. All spans from the same trace share
       # the same `trace_id`. The ID is a 16-byte value represented as a
@@ -54,6 +69,15 @@ module OpenCensus
       #
       attr_reader :name
 
+      ##
+      # The kind of span. Can be used to specify additional relationships
+      # between spans in addition to a parent/child relationship.
+      # You should use the kind constants provided by this class.
+      #
+      # @return [Symbol]
+      #
+      attr_reader :kind
+
       ##
       # The starting timestamp of this span in UTC.
       #
@@ -177,6 +201,7 @@ module OpenCensus
       # @private
       #
       def initialize trace_id, span_id, name, start_time, end_time,
+                     kind: SPAN_KIND_UNSPECIFIED,
                      parent_span_id: "", attributes: {},
                      dropped_attributes_count: 0, stack_trace: [],
                      dropped_frames_count: 0, time_events: [],
@@ -186,6 +211,7 @@ module OpenCensus
                      same_process_as_parent_span: nil,
                      child_span_count: nil
         @name = name
+        @kind = kind
         @trace_id = trace_id
         @span_id = span_id
         @parent_span_id = parent_span_id
@@ -194,9 +220,8 @@ module OpenCensus
         @attributes = attributes
         @dropped_attributes_count = dropped_attributes_count
         @stack_trace = stack_trace
-        @stack_trace_hash_id = [stack_trace, dropped_frames_count].hash
-        @stack_trace_hash_id = -1 if @stack_trace_hash_id.zero?
         @dropped_frames_count = dropped_frames_count
+        @stack_trace_hash_id = init_stack_trace_hash_id
         @time_events = time_events
         @dropped_annotations_count = dropped_annotations_count
         @dropped_message_events_count = dropped_message_events_count
@@ -206,6 +231,13 @@ module OpenCensus
         @same_process_as_parent_span = same_process_as_parent_span
         @child_span_count = child_span_count
       end
+
+      private
+
+      def init_stack_trace_hash_id
+        hash_id = [@stack_trace, @dropped_frames_count].hash
+        hash_id.zero? ? -1 : hash_id
+      end
     end
   end
 end

data/lib/opencensus/trace/span_builder.rb

@@ -33,6 +33,21 @@ module OpenCensus
       ## The linked span is a parent of the current span.
       PARENT_LINKED_SPAN = :PARENT_LINKED_SPAN
 
+      ## The span kind is unspecified
+      SPAN_KIND_UNSPECIFIED = :SPAN_KIND_UNSPECIFIED
+
+      ##
+      # Indicates that the span covers server-side handling of an RPC or other
+      # remote network request.
+      #
+      SERVER = :SERVER
+
+      ##
+      # Indicates that the span covers the client-side wrapper around an RPC
+      # or other remote request.
+      #
+      CLIENT = :CLIENT
+
       ##
       # The context that can build children of this span.
       #
@@ -90,6 +105,18 @@ module OpenCensus
       #
       attr_accessor :name
 
+      ##
+      # 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`.
+      #
+      # This field is required.
+      #
+      # @return [Symbol]
+      #
+      attr_accessor :kind
+
       ##
       # The start time of the span. On the client side, this is the time kept
       # by the local machine where the span execution starts. On the server
@@ -330,6 +357,7 @@ module OpenCensus
         same_process_as_parent_span = context.parent.same_process_as_parent
 
         Span.new trace_id, span_id, built_name, @start_time, @end_time,
+                 kind: @kind,
                  parent_span_id: parent_span_id,
                  attributes: built_attributes,
                  dropped_attributes_count: dropped_attributes_count,
@@ -357,6 +385,7 @@ module OpenCensus
         @context = span_context
         @sampled = sampled
         @name = ""
+        @kind = SPAN_KIND_UNSPECIFIED
         @start_time = nil
         @end_time = nil
         @attributes = {}

data/lib/opencensus/trace/span_context.rb

@@ -167,19 +167,21 @@ module OpenCensus
       # However, you are responsible for finishing the span yourself.
       #
       # @param [String] name Name of the span
+      # @param [Symbol] kind Kind of span. Defaults to unspecified.
       # @param [Sampler] sampler Span-scoped sampler. If not provided,
       #     defaults to the trace configuration's default sampler.
       #
       # @return [SpanBuilder] A SpanBuilder object that you can use to
       #     set span attributes and create children.
       #
-      def start_span name, skip_frames: 0, sampler: nil
+      def start_span name, kind: nil, skip_frames: 0, sampler: nil
         child_context = create_child
         sampler ||= OpenCensus::Trace.config.default_sampler
         sampled = sampler.call span_context: self
         span = SpanBuilder.new child_context, sampled,
                                skip_frames: skip_frames + 1
         span.name = name
+        span.kind = kind if kind
         span.start!
         @trace_data.span_map[child_context.span_id] = span
       end
@@ -194,11 +196,13 @@ module OpenCensus
       # be finished automatically at the end of the block.
       #
       # @param [String] name Name of the span
+      # @param [Symbol] kind Kind of span. Defaults to unspecified.
       # @param [Sampler] sampler Span-scoped sampler. If not provided,
       #     defaults to the trace configuration's default sampler.
       #
-      def in_span name, skip_frames: 0, sampler: nil
-        span = start_span name, skip_frames: skip_frames + 1, sampler: sampler
+      def in_span name, kind: nil, skip_frames: 0, sampler: nil
+        span = start_span name, kind: kind, skip_frames: skip_frames + 1,
+                                sampler: sampler
         begin
           yield span
         ensure
@@ -232,9 +236,9 @@ module OpenCensus
       end
 
       ##
-      # Builds all finished spans under this context, and returns an array of
-      # built `Span` objects. Ignores any unfinished spans. The order of the
-      # generated spans is undefined.
+      # Builds spans under this context, and returns an array of built `Span`
+      # objects. Builds only spans that are both finished and sampled, and
+      # ignores others. The order of the generated spans is undefined.
       #
       # Does not build any ancestor spans. If you want the entire span tree
       # built, call this method on the `#root` context.
@@ -260,7 +264,10 @@ module OpenCensus
                                 max_message_events: nil,
                                 max_links: nil,
                                 max_string_length: nil
-        contained_span_builders.find_all(&:finished?).map do |sb|
+        sampled_span_builders = contained_span_builders.find_all do |sb|
+          sb.finished? && sb.sampled
+        end
+        sampled_span_builders.map do |sb|
           sb.to_span max_attributes: max_attributes,
                      max_stack_frames: max_stack_frames,
                      max_annotations: max_annotations,

data/lib/opencensus/version.rb

@@ -14,5 +14,5 @@
 
 module OpenCensus
   ## Current OpenCensus version
-  VERSION = "0.2.2".freeze
+  VERSION = "0.3.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opencensus
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Jeff Ching
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-09 00:00:00.000000000 Z
+date: 2018-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -164,6 +164,9 @@ files:
 - docs/_config.yml
 - docs/_layouts/default.html
 - docs/index.md
+- examples/hello-world/Gemfile
+- examples/hello-world/README.md
+- examples/hello-world/hello.rb
 - lib/opencensus.rb
 - lib/opencensus/common.rb
 - lib/opencensus/common/config.rb