opencensus 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: fcd6b186ce0092ad6cf63ec39de790c05ba2a8e5
-  data.tar.gz: d23b444fb33a05c2333d745e72a956217239a622
+SHA256:
+  metadata.gz: 536fa079d66a3bb4bef7a0e70439d5e9cc016f25e86e775a74d7426c4ef3a7e7
+  data.tar.gz: '00688752f3c40bd18f08d4b0f311b8bd16435798647b1c09b70ad3c9240fb233'
 SHA512:
-  metadata.gz: 59fdc1eaacc8e1f6616fc6948a78338756af8091d0be7ee5bd953270cdd2d48051048f72b56a7e9c030afea97d9f4dfe9356655586ef6dd4e672646715a495bc
-  data.tar.gz: a9879fbf66e97502c4c35ad4ea99365a17865138bfb4c05eb3701797b4c41990bc3bf48b7431ffb1ca01f4b3c55c824da7a2ec59c9b9bc4d8d66ec9bdc4eaf5e
+  metadata.gz: 50ef3104c577f850c1b4dc8b7bbe9da6030eab510f413c9cec5934da88f0b80232a97b77b7a50f5997925b53601f8796089ab7587c011bb28f2cf593171f37ea
+  data.tar.gz: 8f4735b8955070ea7cbec12fd9260fe0a6f0647c0702837e7e74691e05b8f8bebaf2e7be92b3065b89e865cc2d2b4f100cf8ff2b6a2a1e57dceafbd9e9746da4

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Release History
 
+### 0.4.0 / 2018-10-22
+
+This is an important update that includes a number of fixes and brings the
+library up to date with the latest OpenCensus specification.
+
+Backward-incompatible changes:
+
+* Local parent span's sampling decision is propagated to children by default, to match the current sampling spec.
+* It is no longer possible to change a sampling decision after a SpanBuilder has been created, to match the current sampling spec.
+* Renamed MaxQPS sampler to RateLimiting, and modified the implementation to match the current spec.
+* Probability sampler defaults to 1 in 10,000.
+* `true` or `false` may be passed as a sampler, as shortcuts for AlwaysSample or NeverSample.
+* Standard samplers are now thread-safe.
+* HTTP status codes are properly translated to OpenCensus status codes, in particular for spans generated by the Faraday and Rack middleware.
+* Faraday and Rack middleware produce attributes matching the OpenCensus HTTP spec instead of the Stackdriver Trace service spec. The Stackdriver exporter now translates these attributes accordingly.
+* Update standard trace context HTTP header to "traceparent" following updated spec.
+
+Other fixes:
+
+* Allow requiring "opencensus/trace" directly.
+* Return SpanContext objects when block not given.
+* FaradayMiddleware closes span if Faraday raises an exception.
+
 ### 0.3.1 / 2018-04-13
 
 * Clean unneeded files from the gem

data/README.md

@@ -98,7 +98,7 @@ additional custom spans to the request trace:
 ```ruby
 OpenCensus::Trace.in_span "my_task" do |span|
   # Do stuff...
-
+  
   OpenCensus::Trace.in_span "my_subtask" do |subspan|
     # Do other stuff
   end
@@ -112,8 +112,15 @@ 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. Plugins are
-currently being developed for Stackdriver, Zipkin, and other services.
+your favorite analytics backend, install an export plugin. 
+
+The provided exporters are:
+
+| Class | Description |
+| ----- | ----------- |
+| [LoggerExporter][logger-exporter] | Exporter JSON encoded spans to a standard Ruby Logger interface |
+| [StackdriverExporter][stackdriver-exporter] | Report traces to Google Cloud Stackdriver Trace |
+| [ZipkinExporter][zipkin-exporter] | Report collected spans to a Zipkin server |
 
 You may also create your own
 [Exporter](http://www.rubydoc.info/gems/opencensus/OpenCensus/Trace/Exporters)
@@ -193,3 +200,7 @@ This library is licensed under Apache 2.0. Full license text is available in
 ## Disclaimer
 
 This is not an official Google product.
+
+[logger-exporter]: https://www.rubydoc.info/gems/opencensus/OpenCensus/Trace/Exporters/Logger
+[stackdriver-exporter]: https://github.com/census-ecosystem/opencensus-ruby-exporter-stackdriver
+[zipkin-exporter]: https://github.com/census-ecosystem/opencensus-ruby-exporter-zipkin

data/lib/opencensus.rb

@@ -12,6 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
+##
+# OpenCensus is a vendor-agnostic single distribution of libraries to provide
+# metrics collection and tracing for your services. See https://opencensus.io/
+# for general information on OpenCensus.
+#
+# The OpenCensus module provides a namespace for the Ruby implementation of
+# OpenCensus, including the core libraries for OpenCensus metrics and tracing.
+#
+module OpenCensus
+end
+
 require "opencensus/common"
 require "opencensus/config"
 require "opencensus/context"

data/lib/opencensus/common.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "opencensus/common/config"
 
 module OpenCensus

data/lib/opencensus/common/config.rb

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

data/lib/opencensus/config.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "opencensus/common/config"
 
 module OpenCensus
@@ -20,8 +21,9 @@ module OpenCensus
 
   class << self
     ##
-    # Configure OpenCensus. Most configuration parameters are part of
-    # subconfigurations that live under this main configuration.
+    # Configure OpenCensus. Most configuration parameters are defined in
+    # subconfigurations that live under this main configuration. See, for
+    # example, {OpenCensus::Trace.configure}.
     #
     # If the OpenCensus Railtie is installed in a Rails application, the
     # toplevel configuration object is also exposed as `config.opencensus`.
@@ -33,7 +35,7 @@ module OpenCensus
     #
     #     OpenCensus.configure do |config|
     #       config.trace.default_sampler =
-    #         OpenCensus::Trace::Samplers::AlwaysSample.new
+    #         OpenCensus::Trace::Samplers::RateLimiting.new
     #       config.trace.default_max_attributes = 16
     #     end
     #

data/lib/opencensus/context.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module OpenCensus
   ##
   # The Context module provides per-thread storage.

data/lib/opencensus/stats.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module OpenCensus
   ##
   # The Stats module contains support for OpenCensus stats collection.

data/lib/opencensus/tags.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module OpenCensus
   ##
   # The Tags module contains support for OpenCensus tags. Tags are key-value

data/lib/opencensus/trace.rb

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
+require "opencensus/context"
 require "opencensus/trace/annotation"
 require "opencensus/trace/config"
 require "opencensus/trace/exporters"
@@ -77,7 +79,7 @@ module OpenCensus
       # Starts tracing a request in the current thread, by creating a new
       # SpanContext and setting it as the current thread-local context.
       # Generally you should call this when beginning the handling of a
-      # request. If there is a rack environment or a provided Trace-Context
+      # request. If there is a rack environment or a provided traceparent
       # header, pass it in so the SpanContext is constructed accordingly.
       #
       # If you pass a block, this method will yield the SpanContext to the
@@ -103,13 +105,15 @@ module OpenCensus
           ensure
             unset_span_context
           end
+        else
+          span_context
         end
       end
 
       ##
       # Create a new span in the current thread-local context.
       # You must pass a name for the span. All other span attributes should
-      # be set using the SpanBuilder methods.
+      # be set using {OpenCensus::Trace::SpanBuilder} methods.
       #
       # The span will be started automatically with the current timestamp.
       # However, you are responsible for finishing the span yourself.
@@ -123,10 +127,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.
+      # @param [String] name Name of the span. Required.
+      # @param [Symbol] kind Kind of span. Optional. Defaults to unspecified.
+      #     Other allowed values are {OpenCensus::Trace::SpanBuilder::SERVER}
+      #     and {OpenCensus::Trace::SpanBuilder::CLIENT}.
+      # @param [Sampler,Boolean,nil] sampler Span-scoped sampler. Optional.
+      #     If provided, the sampler may be a sampler object as defined in the
+      #     {OpenCensus::Trace::Samplers} module docs, or the values `true` or
+      #     `false` as shortcuts for {OpenCensus::Trace::Samplers::AlwaysSample}
+      #     or {OpenCensus::Trace::Samplers::NeverSample}, respectively. If no
+      #     span-scoped sampler is provided, the local parent span's sampling
+      #     decision is used. If there is no local parent span, the configured
+      #     default sampler is used to make a sampling decision.
       #
       # @return [SpanBuilder] A SpanBuilder object that you can use to
       #     set span attributes and create children.
@@ -144,7 +156,7 @@ module OpenCensus
       ##
       # Create a new span in this context.
       # You must pass a name for the span. All other span attributes should
-      # be set using the SpanBuilder methods.
+      # be set using {OpenCensus::Trace::SpanBuilder} methods.
       #
       # The span will be started automatically with the current timestamp. The
       # SpanBuilder will then be passed to the block you provide. The span will
@@ -152,10 +164,18 @@ module OpenCensus
       # the thread-local SpanContext will be updated so calls to `start_span`
       # 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.
+      # @param [String] name Name of the span. Required.
+      # @param [Symbol] kind Kind of span. Optional. Defaults to unspecified.
+      #     Other allowed values are {OpenCensus::Trace::SpanBuilder::SERVER}
+      #     and {OpenCensus::Trace::SpanBuilder::CLIENT}.
+      # @param [Sampler,Boolean,nil] sampler Span-scoped sampler. Optional.
+      #     If provided, the sampler may be a sampler object as defined in the
+      #     {OpenCensus::Trace::Samplers} module docs, or the values `true` or
+      #     `false` as shortcuts for {OpenCensus::Trace::Samplers::AlwaysSample}
+      #     or {OpenCensus::Trace::Samplers::NeverSample}, respectively. If no
+      #     span-scoped sampler is provided, the local parent span's sampling
+      #     decision is used. If there is no local parent span, the configured
+      #     default sampler is used to make a sampling decision.
       #
       def in_span name, kind: nil, skip_frames: 0, sampler: nil
         span = start_span name, kind: kind, skip_frames: skip_frames + 1,

data/lib/opencensus/trace/annotation.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

data/lib/opencensus/trace/config.rb

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
+require "opencensus/config"
 require "opencensus/trace/exporters"
 require "opencensus/trace/formatters"
 require "opencensus/trace/samplers"
@@ -21,16 +23,16 @@ module OpenCensus
     # Schema of the Trace configuration. See Trace#configure for more info.
     @config = Common::Config.new do |config|
       default_sampler = Samplers::AlwaysSample.new
+      exporter_logger = ::Logger.new STDOUT, ::Logger::INFO
+      default_exporter = Exporters::Logger.new exporter_logger
+      default_formatter = Formatters::TraceContext.new
+
       config.add_option! :default_sampler, default_sampler do |value|
         value.respond_to? :call
       end
-      default_exporter =
-        Exporters::Logger.new ::Logger.new(STDOUT, ::Logger::INFO)
       config.add_option! :exporter, default_exporter do |value|
         value.respond_to? :export
       end
-      default_formatter =
-        Formatters::TraceContext.new
       config.add_option! :http_formatter, default_formatter do |value|
         value.respond_to?(:serialize) &&
           value.respond_to?(:deserialize) &&
@@ -67,7 +69,7 @@ module OpenCensus
       #
       #     OpenCensus::Trace.configure do |config|
       #       config.default_sampler =
-      #         OpenCensus::Trace::Samplers::AlwaysSample.new
+      #         OpenCensus::Trace::Samplers::RateLimiting.new
       #       config.default_max_attributes = 16
       #     end
       #
@@ -75,17 +77,17 @@ module OpenCensus
       #
       # *   `default_sampler` The default sampler to use. Must be a sampler,
       #     an object with a `call` method that takes a single options hash.
-      #     See OpenCensus::Trace::Samplers. The initial value is a Probability
-      #     sampler with a default rate.
+      #     See {OpenCensus::Trace::Samplers}. The initial value is an instance
+      #     of {OpenCensus::Trace::Samplers::AlwaysSample}.
       # *   `exporter` The exporter to use. Must be an exporter, an object with
       #     an export method that takes an array of Span objects. See
-      #     OpenCensus::Trace::Exporters. The initial value is a Logger exporter
-      #     that logs to STDOUT.
+      #     {OpenCensus::Trace::Exporters}. The initial value is a
+      #     {OpenCensus::Trace::Exporters::Logger} that logs to STDOUT.
       # *   `http_formatter` The trace context propagation formatter to use.
       #     Must be a formatter, an object with `serialize`, `deserialize`,
       #     `header_name`, and `rack_header_name` methods. See
-      #     OpenCensus::Trace::Formatter. The initial value is a TraceContext
-      #     formatter.
+      #     {OpenCensus::Trace::Formatters}. The initial value is a
+      #     {OpenCensus::Trace::Formatters::TraceContext}.
       # *   `default_max_attributes` The maximum number of attributes to add to
       #     a span. Initial value is 32. Use 0 for no maximum.
       # *   `default_max_stack_frames` The maximum number of stack frames to

data/lib/opencensus/trace/exporters.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "opencensus/trace/exporters/logger"
 require "opencensus/trace/exporters/multi"
 

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

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "logger"
 require "json"
 
@@ -27,9 +28,9 @@ module OpenCensus
         # Create a new Logger exporter
         #
         # @param [#log] logger The logger to write to.
-        # @param [Symbol] level The log level. This should be a log level
-        #        defined by {https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html
-        #        Logger Standard Library}.
+        # @param [Integer] level The log level. This should be a log level
+        #        defined by the Logger standard library. Default is
+        #        `::Logger::INFO`.
         #
         def initialize logger, level: ::Logger::INFO
           @logger = logger

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

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

data/lib/opencensus/trace/formatters.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "opencensus/trace/formatters/binary"
 require "opencensus/trace/formatters/cloud_trace"
 require "opencensus/trace/formatters/trace_context"
@@ -20,8 +21,8 @@ module OpenCensus
   module Trace
     ##
     # The Formatters module contains several implementations of cross-service
-    # SpanContext propagation. Each formatter can serialize and deserialize a
-    # TraceContextData instance.
+    # context propagation. Each formatter can serialize and deserialize a
+    # {OpenCensus::Trace::TraceContextData} instance.
     #
     module Formatters
     end

data/lib/opencensus/trace/formatters/binary.rb

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

data/lib/opencensus/trace/formatters/cloud_trace.rb

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

data/lib/opencensus/trace/formatters/trace_context.rb

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 module OpenCensus
   module Trace
     module Formatters
@@ -41,7 +42,7 @@ module OpenCensus
         #
         # @private
         #
-        HEADER_NAME = "Trace-Context".freeze
+        HEADER_NAME = "traceparent".freeze
 
         ##
         # The rack environment header used for the TraceContext header
@@ -49,7 +50,7 @@ module OpenCensus
         #
         # @private
         #
-        RACK_HEADER_NAME = "HTTP_TRACE_CONTEXT".freeze
+        RACK_HEADER_NAME = "HTTP_TRACEPARENT".freeze
 
         ##
         # Returns the name of the header used for context propagation.

data/lib/opencensus/trace/integrations.rb

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

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

@@ -12,8 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "faraday"
 
+require "faraday"
+require "uri"
 require "opencensus"
 
 module OpenCensus
@@ -88,8 +89,11 @@ module OpenCensus
       #       }
       #     end
       #
-      class FaradayMiddleware < Faraday::Middleware
-        ## The default name for Faraday spans
+      class FaradayMiddleware < ::Faraday::Middleware
+        ##
+        # Fallback span name
+        # @return [String]
+        #
         DEFAULT_SPAN_NAME = "faraday_request".freeze
 
         ##
@@ -101,8 +105,8 @@ module OpenCensus
         #     current thread-local span context.
         # @param [String, #call] span_name The name of the span to create.
         #     Can be a string or a callable that takes a faraday request env
-        #     and returns a string. Optional: If omitted, uses
-        #     `DEFAULT_SPAN_NAME`
+        #     and returns a string. Optional: If omitted, uses the request path
+        #     as recommended in the OpenCensus spec.
         # @param [#call] sampler The sampler to use when creating spans.
         #     Optional: If omitted, uses the sampler in the current config.
         # @param [#serialize,#header_name] formatter The formatter to use when
@@ -113,7 +117,7 @@ module OpenCensus
                        formatter: nil
           @app = app
           @span_context = span_context || OpenCensus::Trace
-          @span_name = span_name || DEFAULT_SPAN_NAME
+          @default_span_name = span_name
           @sampler = sampler
           @formatter = formatter || OpenCensus::Trace.config.http_formatter
         end
@@ -128,36 +132,60 @@ module OpenCensus
             return @app.call request_env
           end
 
-          span_name = request_env[:span_name] || @span_name
+          span_name = extract_span_name(request_env) || @default_span_name ||
+                      DEFAULT_SPAN_NAME
           span_name = span_name.call request_env if span_name.respond_to? :call
 
           span = span_context.start_span span_name, sampler: @sampler
           start_request span, request_env
-          @app.call(request_env).on_complete do |response_env|
-            finish_request span, response_env
+          begin
+            @app.call(request_env).on_complete do |response_env|
+              finish_request span, response_env
+            end
+          rescue StandardError => e
+            span.set_status 2, e.message
+            raise
+          ensure
             span_context.end_span span
           end
         end
 
         protected
 
+        ##
+        # @private Get the span name from the request object
+        #
+        def extract_span_name env
+          name = env[:span_name]
+          return name if name
+          uri = build_uri env
+          return nil unless uri
+          path = uri.path.to_s
+          path.start_with?("/") ? path : "/#{path}"
+        end
+
         ##
         # @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]
-          span.put_attribute "/http/url", url if url
+          span.put_attribute "http.method", req_method.upcase if req_method
+          uri = build_uri env
+          if uri
+            span.put_attribute "http.host", uri.hostname.to_s
+            span.put_attribute "http.path", uri.path.to_s
+          end
           body = env[:body]
-          body_size = body.bytesize if body.respond_to? :bytesize
-          span.put_attribute "/rpc/request/size", body_size if body_size
+          body_size = body.respond_to?(:bytesize) ? body.bytesize : 0
+          span.put_message_event SpanBuilder::SENT, 1, body_size
 
           formatter = env[:formatter] || @formatter
-          trace_context = formatter.serialize span.context.trace_context
-          headers = env[:request_headers] ||= {}
-          headers[formatter.header_name] = trace_context
+          if formatter.respond_to? :header_name
+            headers = env[:request_headers] ||= {}
+            trace_context = formatter.serialize span.context.trace_context
+            headers[formatter.header_name] = trace_context
+          end
         end
 
         ##
@@ -166,12 +194,20 @@ module OpenCensus
         def finish_request span, env
           status = env[:status].to_i
           if status > 0
-            span.set_status status
-            span.put_attribute "/rpc/status_code", status
+            span.set_http_status status
+            span.put_attribute "http.status_code", status
           end
           body = env[:body]
-          body_size = body.bytesize if body.respond_to? :bytesize
-          span.put_attribute "/rpc/response/size", body_size if body_size
+          body_size = body.respond_to?(:bytesize) ? body.bytesize : 0
+          span.put_message_event SpanBuilder::RECEIVED, 1, body_size
+        end
+
+        private
+
+        def build_uri env
+          ::URI.parse env[:url]
+        rescue ::URI::InvalidURIError
+          nil
         end
       end
     end