opencensus 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 56ee4a54946052aaf5fe421b263e80644b2f98b2
-  data.tar.gz: 7e4f749225fd17d54e35ccdf2951735147591b9e
+  metadata.gz: 5b61331cb69913aa2a85bed2353045cf10b97d99
+  data.tar.gz: 6fed28a666fa2741fd7de32a3608c0089b8f7b8c
 SHA512:
-  metadata.gz: 7f40a4d9820bff2cb495b2a560b4aea142d4b88e6acb98219eeaa31aa909ed6199c18877bea1be0f51255bec50beeca7597fb50f8207fa68087c7bffbbae892b
-  data.tar.gz: 07d4b90fa431b3860d2a4d02736d0699a0f55e1ff798faa8f541bcf165d2b97c074ede40fc51d61d8a2441b330e5759f1d1a9669dced29fbe2ad2e6a19e6222e
+  metadata.gz: 1afcf27bef5d796b2b08f31bebaccd78ed03ff93e463c24ecaae4a4ff98dd20cc6ccbf9c953cbbfe477018a2ae4091589fdca4584c78a17154961592d0a41e0f
+  data.tar.gz: 4daea1fabb7dff90fbccbb9e043489c6c9f9a5c16714058d9cb87783d025aa5a8adaef175aed3953127ae0a6c653078a8c9c95bd8439c5b9ce75b3d11d42fc07

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Release History
 
+### 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
+* Provided a multi exporter
+* Document exporter interface
+* Fix some broken links in the documentation
+
 ### 0.2.1 / 2018-03-05
 
 * Clarify Ruby version requirement (2.2+)

data/README.md

@@ -48,6 +48,10 @@ To enable Rails integration, require this file during application startup:
 require "opencensus/trace/integrations/rails"
 ```
 
+See the documentation for the
+[Rails integration class](http://www.rubydoc.info/gems/opencensus/OpenCensus/Trace/Integrations/Rails)
+for more information.
+
 ### Getting started with other Rack-based frameworks
 
 Other Rack-based frameworks, such as Sinatra, can use the Rack Middleware
@@ -81,7 +85,7 @@ conn.get "/"
 ```
 
 See the documentation for the
-[FaradayMiddleware](http://opencensus.io/opencensus-ruby/api/OpenCensus/Trace/Integrations/FaradayMiddleware.html)
+[FaradayMiddleware](http://www.rubydoc.info/gems/opencensus/OpenCensus/Trace/Integrations/FaradayMiddleware)
 class for more info.
 
 ### Adding Custom Trace Spans
@@ -101,15 +105,18 @@ end
 ```
 
 See the documentation for the
-[OpenCensus::Trace](http://opencensus.io/opencensus-ruby/api/OpenCensus/Trace.html)
+[OpenCensus::Trace](http://www.rubydoc.info/gems/opencensus/OpenCensus/Trace)
 module for more info.
 
 ### Exporting traces
 
 By default, OpenCensus will log request trace data as JSON. To export traces to
-your favorite analytics backend, install an export plugin. There are plugins
+your favorite analytics backend, install an export plugin. Plugins are
 currently being developed for Stackdriver, Zipkin, and other services.
 
+You may also create your own
+[Exporter](http://www.rubydoc.info/gems/opencensus/OpenCensus/Trace/Exporters)
+
 ### Configuring the library
 
 OpenCensus allows configuration of a number of aspects via the configuration
@@ -142,9 +149,9 @@ Additionally, integrations and other plugins might have their own
 configurations.
 
 For more information, consult the documentation for
-[OpenCensus.configure](http://opencensus.io/opencensus-ruby/api/OpenCensus.html#configure-class_method)
+[OpenCensus.configure](http://www.rubydoc.info/gems/opencensus/OpenCensus#configure-class_method)
 and
-[OpenCensus::Trace.configure](http://opencensus.io/opencensus-ruby/api/OpenCensus/Trace.html#configure-class_method).
+[OpenCensus::Trace.configure](http://www.rubydoc.info/gems/opencensus/OpenCensus/Trace#configure-class_method).
 
 ## About the library
 
@@ -152,6 +159,13 @@ and
 
 This library is supported on Ruby 2.2+.
 
+However, Ruby 2.3 or later is strongly recommended, as earlier releases have
+reached or are nearing end-of-life. After June 1, 2018, OpenCensus will provide
+official support only for Ruby versions that are considered current and
+supported by Ruby Core (that is, Ruby versions that are either in normal
+maintenance or in security maintenance).
+See https://www.ruby-lang.org/en/downloads/branches/ for further details.
+
 ### Versioning
 
 This library follows [Semantic Versioning](http://semver.org/).

data/lib/opencensus/common/config.rb

@@ -217,7 +217,7 @@ module OpenCensus
       #
       def reset! key = nil
         if key.nil?
-          @fields.keys.each { |k| reset! k }
+          @fields.each_key { |k| reset! k }
         else
           key = key.to_sym
           unless @fields.key? key

data/lib/opencensus/trace/exporters.rb

@@ -13,12 +13,31 @@
 # limitations under the License.
 
 require "opencensus/trace/exporters/logger"
+require "opencensus/trace/exporters/multi"
 
 module OpenCensus
   module Trace
     ##
     # The Exporters module provides integrations for exporting collected trace
-    # spans to an external or local service.
+    # spans to an external or local service. Exporter classes may be put inside
+    # this module, but are not required to be located here.
+    #
+    # An exporter is an object that must respond to the following method:
+    #
+    #     def export(spans)
+    #
+    # Where `spans` is an array of {OpenCensus::Trace::Span} objects to export.
+    # The method _must_ tolerate any number of spans in the `spans` array,
+    # including an empty array.
+    #
+    # The method return value is not defined.
+    #
+    # The exporter object may interpret the `export` message in whatever way it
+    # deems appropriate. For example, it may write the data to a log file, it
+    # may transmit it to a monitoring service, or it may do nothing at all.
+    # An exporter may also queue the request for later asynchronous processing,
+    # and indeed this is recommended if the export involves time consuming
+    # operations such as remote API calls.
     #
     module Exporters
     end

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

@@ -40,10 +40,10 @@ module OpenCensus
         # Export the captured spans to the configured logger.
         #
         # @param [Array<Span>] spans The captured spans.
-        # @return [Boolean]
         #
         def export spans
           @logger.log @level, spans.map { |span| format_span(span) }.to_json
+          nil
         end
 
         private

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

@@ -0,0 +1,56 @@
+# 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.
+
+require "delegate"
+
+module OpenCensus
+  module Trace
+    module Exporters
+      ##
+      # The Multi exporter multiplexes captured spans to a set of delegate
+      # exporters. It is useful if you need to export to more than one
+      # destination. You may also use it as a "null" exporter by providing
+      # no delegates.
+      #
+      # Multi delegates to an array of the exporter objects. You can manage
+      # the list of exporters using any method of Array. For example:
+      #
+      #     multi = OpenCensus::Trace::Exporters::Multi.new
+      #     multi.export(spans)  # Does nothing
+      #     multi << OpenCensus::Trace::Exporters::Logger.new
+      #     multi.export(spans)  # Exports to the logger
+      #
+      class Multi < SimpleDelegator
+        ##
+        # Create a new Multi exporter
+        #
+        # @param [Array<#export>] delegates An array of exporters
+        #
+        def initialize *delegates
+          super(delegates.flatten)
+        end
+
+        ##
+        # Pass the captured spans to the delegates.
+        #
+        # @param [Array<Span>] spans The captured spans.
+        #
+        def export spans
+          each { |delegate| delegate.export spans }
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -36,6 +36,8 @@ module OpenCensus
       #
       #     config.opencensus.trace.default_max_attributes = 64
       #
+      # ### Configuring ActiveSupport Notifications
+      #
       # This Railtie also provides a `notifications` configuration that
       # supports the following fields:
       #
@@ -56,6 +58,37 @@ module OpenCensus
       #
       #     config.opencensus.trace.notifications.attribute_namespace = "myapp/"
       #
+      # ### Configuring Middleware Placement
+      #
+      # By default, the Railtie places the OpenCensus middleware at the end of
+      # the middleware stack. This means it will measure your application code
+      # but not the effect of other middleware, including middlware that is
+      # part of the Rails stack or any custom middleware you have installed.
+      # If you would rather place the middleware at the beginning of the stack
+      # where it surrounds all other middleware, set the this configuration:
+      #
+      #     OpenCensus::Trace.config do |config|
+      #       config.middleware_placement = :begin
+      #     end
+      #
+      # Or, using Rails:
+      #
+      #     config.opencensus.trace.middleware_placement = :begin
+      #
+      # This effectively causes the Railtie to use `unshift` rather than `use`
+      # to add the OpenCensus middleware to the middleware stack.
+      # You may also set this configuration to an existing middleware class to
+      # cause the OpenCensus middleware to be inserted before that middleware
+      # in the stack. For example:
+      #
+      #     OpenCensus::Trace.config do |config|
+      #       config.middleware_placement = ::Rails::Rack::Logger
+      #     end
+      #
+      # Or, using Rails:
+      #
+      #     config.opencensus.trace.middleware_placement = ::Rails::Rack::Logger
+      #
       class Rails < ::Rails::Railtie
         ##
         # The ActiveSupport notifications that will be reported as spans by
@@ -75,6 +108,8 @@ module OpenCensus
             rc.add_option! :events, DEFAULT_NOTIFICATION_EVENTS.dup
             rc.add_option! :attribute_namespace, "rails/"
           end
+          c.add_option! :middleware_placement, :end,
+                        match: [:begin, :end, Class]
         end
 
         unless config.respond_to? :opencensus
@@ -82,10 +117,26 @@ module OpenCensus
         end
 
         initializer "opencensus.trace" do |app|
-          app.middleware.insert_before ::Rack::Runtime, RackMiddleware
+          setup_middleware app.middleware
           setup_notifications
         end
 
+        ##
+        # Insert middleware into the middleware stack
+        # @private
+        #
+        def setup_middleware middleware_stack
+          where = OpenCensus::Trace.configure.middleware_placement
+          case where
+          when Class
+            middleware_stack.insert_before where, RackMiddleware
+          when :begin
+            middleware_stack.unshift RackMiddleware
+          else
+            middleware_stack.use RackMiddleware
+          end
+        end
+
         ##
         # Initialize notifications
         # @private

data/lib/opencensus/version.rb

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

data/opencensus.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.16"
   spec.add_development_dependency "rake", "~> 12.0"
   spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "minitest-focus", "~> 1.1"
   spec.add_development_dependency "faraday", "~> 0.13"
   spec.add_development_dependency "rails", "~> 5.1.4"
   spec.add_development_dependency "rubocop", "~> 0.52"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opencensus
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Jeff Ching
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-05 00:00:00.000000000 Z
+date: 2018-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,6 +53,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-focus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -162,6 +176,7 @@ files:
 - lib/opencensus/trace/config.rb
 - lib/opencensus/trace/exporters.rb
 - lib/opencensus/trace/exporters/logger.rb
+- lib/opencensus/trace/exporters/multi.rb
 - lib/opencensus/trace/formatters.rb
 - lib/opencensus/trace/formatters/binary.rb
 - lib/opencensus/trace/formatters/cloud_trace.rb