opencensus 0.1.0

data/lib/opencensus/trace/integrations.rb

@@ -0,0 +1,24 @@
+# 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.
+
+module OpenCensus
+  module Trace
+    ##
+    # The Integrations module contains implementations of integrations with
+    # popular gems such as Rails and Faraday.
+    #
+    module Integrations
+    end
+  end
+end

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

@@ -0,0 +1,176 @@
+# 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 "faraday"
+
+module OpenCensus
+  module Trace
+    module Integrations
+      ##
+      # # Faraday integration
+      #
+      # This is a middleware for the Faraday HTTP client:
+      #
+      # * It wraps all outgoing requests in spans
+      # * It adds the trace context to outgoing requests.
+      #
+      # Example:
+      #
+      #     conn = Faraday.new(url: "http://www.example.com") do |c|
+      #       c.use OpenCensus::Trace::Integrations::FaradayMiddleware,
+      #             span_name: "http request"
+      #       c.adapter Faraday.default_adapter
+      #     end
+      #     conn.get "/"
+      #
+      # ## Configuring spans
+      #
+      # By default, spans are added to the thread-local span context, as if
+      # by calling `OpenCensus::Trace.start_span`. If there is no span context,
+      # then no span is added and this middleware effectively disables itself.
+      #
+      # You may also provide a span context, by passing it in the middleware
+      # options hash. For example:
+      #
+      #     conn = Faraday.new(url: "http://www.example.com") do |c|
+      #       c.use OpenCensus::Trace::Integrations::FaradayMiddleware,
+      #             span_context: my_span_context
+      #       c.adapter Faraday.default_adapter
+      #     end
+      #
+      # You may also override the span context for a particular request by
+      # including it in the options:
+      #
+      #     conn.get do |req|
+      #       req.url "/"
+      #       req.options.context = { span_context: my_span_context }
+      #     end
+      #
+      # By default, all spans are given a default name. You may also override
+      # this by passing a `:span_name` in the middleware options hash and/or
+      # the request options.
+      #
+      # ## Trace context
+      #
+      # This currently adds a header to each outgoing request, propagating the
+      # trace context for distributed tracing. By default, this uses the
+      # formatter in the current config.
+      #
+      # You may provide your own implementation of the formatter by configuring
+      # it in the middleware options hash. For example:
+      #
+      #     conn = Faraday.new(url: "http://www.example.com") do |c|
+      #       c.use OpenCensus::Trace::Integrations::FaradayMiddleware,
+      #             formatter: OpenCensus::Trace::Formatters::CloudTrace.new
+      #       c.adapter Faraday.default_adapter
+      #     end
+      #
+      # You many also override the formatter for a particular request by
+      # including it in the options:
+      #
+      #     conn.get do |req|
+      #       req.url "/"
+      #       req.options.context = {
+      #         formatter: OpenCensus::Trace::Formatters::CloudTrace.new
+      #       }
+      #     end
+      #
+      class FaradayMiddleware < Faraday::Middleware
+        ## The default name for Faraday spans
+        DEFAULT_SPAN_NAME = "faraday_request".freeze
+
+        ##
+        # Create a FaradayMiddleware.
+        #
+        # @param [#call] app Next item on the middleware stack.
+        # @param [SpanContext] span_context The span context within which
+        #     to create spans. Optional: If omitted, spans are created in the
+        #     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`
+        # @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
+        #     propagating span context. Optional: If omitted, use the formatter
+        #     in the current config.
+        #
+        def initialize app, span_context: nil, span_name: nil, sampler: nil,
+                       formatter: nil
+          @app = app
+          @span_context = span_context || OpenCensus::Trace
+          @span_name = span_name || DEFAULT_SPAN_NAME
+          @sampler = sampler
+          @formatter = formatter || OpenCensus::Trace.config.http_formatter
+        end
+
+        ##
+        # Wraps an HTTP call with a span with the request/response info.
+        # @private
+        #
+        def call request_env
+          span_context = request_env[:span_context] || @span_context
+          if span_context == OpenCensus::Trace && !span_context.span_context
+            return @app.call request_env
+          end
+
+          span_name = request_env[:span_name] || @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
+            span_context.end_span span
+          end
+        end
+
+        protected
+
+        ##
+        # @private Set span attributes from request object
+        #
+        def start_request span, env
+          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
+          body = env[:body]
+          body_size = body.bytesize if body.respond_to? :bytesize
+          span.put_attribute "/rpc/request/size", body_size if body_size
+
+          formatter = env[:formatter] || @formatter
+          trace_context = formatter.serialize span.context.trace_context
+          headers = env[:request_headers] ||= {}
+          headers[formatter.header_name] = trace_context
+        end
+
+        ##
+        # @private Set span attributes from response
+        #
+        def finish_request span, env
+          status = env[:status].to_i
+          if status > 0
+            span.set_status status
+            span.put_attribute "/rpc/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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+# 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.
+
+module OpenCensus
+  module Trace
+    module Integrations
+      ##
+      # # Rack integration
+      #
+      # This is a middleware for Rack applications:
+      #
+      # * It wraps all incoming requests in a root span
+      # * It exports the captured spans at the end of the request.
+      #
+      # Example:
+      #
+      #     require "opencensus/trace/integrations/rack_middleware"
+      #
+      #     use OpenCensus::Trace::Integrations::RackMiddleware
+      #
+      class RackMiddleware
+        ##
+        # List of trace context formatters we use to parse the parent span
+        # context.
+        #
+        # @private
+        #
+        AUTODETECTABLE_FORMATTERS = [
+          Formatters::CloudTrace.new,
+          Formatters::TraceContext.new
+        ].freeze
+
+        ##
+        # Create the Rack middleware.
+        #
+        # @param [#call] app Next item on the middleware stack
+        # @param [#export] exporter The exported used to export captured spans
+        #     at the end of the request. Optional: If omitted, uses the exporter
+        #     in the current config.
+        #
+        def initialize app, exporter: nil
+          @app = app
+          @exporter = exporter || OpenCensus::Trace.config.exporter
+        end
+
+        ##
+        # Run the Rack middleware.
+        #
+        # @param [Hash] env The rack environment
+        # @return [Array] The rack response. An array with 3 elements: the HTTP
+        #     response code, a Hash of the response headers, and the response
+        #     body which must respond to `each`.
+        #
+        def call env
+          formatter = AUTODETECTABLE_FORMATTERS.detect do |f|
+            env.key? f.rack_header_name
+          end
+          if formatter
+            context = formatter.deserialize env[formatter.rack_header_name]
+          end
+
+          Trace.start_request_trace trace_context: context do |span_context|
+            begin
+              span_context.in_span get_path(env) do |span|
+                start_request span, env
+                @app.call(env).tap do |response|
+                  finish_request span, response
+                end
+              end
+            ensure
+              @exporter.export span_context.build_contained_spans
+            end
+          end
+        end
+
+        private
+
+        def get_path env
+          path = "#{env['SCRIPT_NAME']}#{env['PATH_INFO']}"
+          path = "/#{path}" unless path.start_with? "/"
+          path
+        end
+
+        def get_host env
+          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.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
+        end
+
+        def finish_request span, response
+          if response.is_a?(::Array) && response.size == 3
+            span.set_status response[0]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# 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 "active_support"
+require "rails/railtie"
+require "opencensus/trace/integrations/rack_middleware"
+
+module OpenCensus
+  module Trace
+    module Integrations
+      ##
+      # # Rails Integration
+      #
+      # This Railtie automatically sets up OpenCensus for a Rails server:
+      #
+      # *   It wraps all requests in spans, using the `RackMiddleware`
+      #     integration.
+      # *   It wraps common events (ActiveRecord database calls, ActionView
+      #     renders, etc) in subspans.
+      #
+      # ## Configuration
+      #
+      # This Railtie exposes the OpenCensus configuration on the `opencensus`
+      # key of the Rails configuration. So you can, for example, set:
+      #
+      #     config.opencensus.trace.default_max_attributes = 64
+      #
+      # This Railtie also provides a `notifications` configuration that
+      # supports the following fields:
+      #
+      # * `events` An array of strings indicating the events that will
+      #   trigger the creation of spans. The default value is
+      #   {OpenCensus::Trace::Integrations::Rails::DEFAULT_NOTIFICATION_EVENTS}.
+      # * `attribute_namespace` A string that will be prepended to all
+      #   attributes copied from the event payload. Defaults to "`rails/`"
+      #
+      # You can access these in the `notifications` subconfiguration under
+      # the trace configuration. For example:
+      #
+      #     OpenCensus::Trace.config do |config|
+      #       config.notifications.attribute_namespace = "myapp/"
+      #     end
+      #
+      # Or, using Rails:
+      #
+      #     config.opencensus.trace.notifications.attribute_namespace = "myapp/"
+      #
+      class Rails < ::Rails::Railtie
+        ##
+        # The ActiveSupport notifications that will be reported as spans by
+        # default. To change this list, update the value of the
+        # `trace.notifications.events` configuration.
+        #
+        DEFAULT_NOTIFICATION_EVENTS = [
+          "sql.active_record",
+          "render_template.action_view",
+          "send_file.action_controller",
+          "send_data.action_controller",
+          "deliver.action_mailer"
+        ].freeze
+
+        OpenCensus::Trace.configure do |c|
+          c.add_config! :notifications do |rc|
+            rc.add_option! :events, DEFAULT_NOTIFICATION_EVENTS.dup
+            rc.add_option! :attribute_namespace, "rails/"
+          end
+        end
+
+        unless config.respond_to? :opencensus
+          config.opencensus = OpenCensus.configure
+        end
+
+        initializer "opencensus.trace" do |app|
+          app.middleware.insert_before ::Rack::Runtime, RackMiddleware
+          setup_notifications
+        end
+
+        ##
+        # Initialize notifications
+        # @private
+        #
+        def setup_notifications
+          OpenCensus::Trace.configure.notifications.events.each do |type|
+            ActiveSupport::Notifications.subscribe(type) do |*args|
+              event = ActiveSupport::Notifications::Event.new(*args)
+              handle_notification_event event
+            end
+          end
+        end
+
+        ##
+        # Add a span based on a notification event.
+        # @private
+        #
+        def handle_notification_event event
+          span_context = OpenCensus::Trace.span_context
+          if span_context
+            ns = OpenCensus::Trace.configure.notifications.attribute_namespace
+            span = span_context.start_span event.name, skip_frames: 2
+            span.start_time = event.time
+            span.end_time = event.end
+            event.payload.each do |k, v|
+              span.put_attribute "#{ns}#{k}", v.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end