skylight 3.1.4 → 5.3.4

data/lib/skylight/helpers.rb

@@ -6,16 +6,15 @@ module Skylight
   # into the class that you will be instrumenting. Then, annotate each method that
   # you wish to instrument with {Skylight::Helpers::ClassMethods#instrument_method instrument_method}.
   module Helpers
-
     # @see Skylight::Helpers
     module ClassMethods
       # @api private
       def method_added(name)
         super
 
-        if opts = @__sk_instrument_next_method
+        if (opts = @__sk_instrument_next_method)
           @__sk_instrument_next_method = nil
-          instrument_method(name, opts)
+          instrument_method(name, **opts)
         end
       end
 
@@ -23,9 +22,9 @@ module Skylight
       def singleton_method_added(name)
         super
 
-        if opts = @__sk_instrument_next_method
+        if (opts = @__sk_instrument_next_method)
           @__sk_instrument_next_method = nil
-          instrument_class_method(name, opts)
+          instrument_class_method(name, **opts)
         end
       end
 
@@ -78,14 +77,12 @@ module Skylight
       #         do_expensive_stuff
       #       end
       #     end
-      def instrument_method(*args)
-        opts = args.pop if Hash === args.last
-
-        if name = args.pop
-          title = "#{to_s}##{name}"
-          __sk_instrument_method_on(self, name, title, opts || {})
+      def instrument_method(*args, **opts)
+        if (name = args.pop)
+          title = "#{self}##{name}"
+          __sk_instrument_method_on(self, name, title, **opts)
         else
-          @__sk_instrument_next_method = opts || {}
+          @__sk_instrument_next_method = opts
         end
       end
 
@@ -124,45 +121,92 @@ module Skylight
       #
       #       instrument_class_method :my_method, title: 'Expensive work'
       #     end
-      def instrument_class_method(name, opts = {})
-        title = "#{to_s}.#{name}"
-        __sk_instrument_method_on(__sk_singleton_class, name, title, opts || {})
+      def instrument_class_method(name, **opts)
+        # NOTE: If the class is defined anonymously and then assigned to a variable this code
+        #   will not be aware of the updated name.
+        title = "#{self}.#{name}"
+        __sk_instrument_method_on(__sk_singleton_class, name, title, **opts)
       end
 
-    private
+      private
+
+      HAS_ARGUMENT_FORWARDING = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.7.0")
 
-      def __sk_instrument_method_on(klass, name, title, opts)
+      def __sk_instrument_method_on(klass, name, title, **opts)
         category = (opts[:category] || "app.method").to_s
-        title    = (opts[:title] || title).to_s
-        desc     = opts[:description].to_s if opts[:description]
+        title = (opts[:title] || title).to_s
+        desc = opts[:description].to_s if opts[:description]
 
-        klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          alias_method :"before_instrument_#{name}", :"#{name}"
+        # NOTE: The source location logic happens before we have have a config so we can'
+        # check if source locations are enabled. However, it only happens once so the potential impact
+        # should be minimal. This would more appropriately belong to Extensions::SourceLocation,
+        # but as that is a runtime concern, and this happens at compile time, there isn't currently
+        # a clean way to turn this on and off. The absence of the extension will cause the
+        # source_file and source_line to be removed from the trace span before it is submitted.
+        source_file, source_line = klass.instance_method(name).source_location
+
+        # We should strongly prefer using the new argument-forwarding syntax (...) where available.
+        # In Ruby 2.7, the following are known to be syntax errors:
+        #
+        # - mixing positional arguments with argument forwarding (e.g., send(:method_name, ...))
+        # - calling a setter method with multiple arguments, unless dispatched via send or public_send.
+        #
+        # So it is possible, though not recommended, to define setter methods that take multiple arguments,
+        # keywords, and/or blocks. Unfortunately, this means that for setters, we still need to explicitly
+        # forward the different argument types.
+        is_setter_method = name.to_s.end_with?("=")
 
-          def #{name}(*args, &blk)
-            span = Skylight.instrument(
-              category:  :"#{category}",
-              title:       #{title.inspect},
-              description: #{desc.inspect})
+        arg_string =
+          if HAS_ARGUMENT_FORWARDING
+            is_setter_method ? "*args, **kwargs, &blk" : "..."
+          else
+            "*args, &blk"
+          end
 
-            meta = {}
-            begin
-              send(:before_instrument_#{name}, *args, &blk)
-            rescue Exception => e
-              meta[:exception_object] = e
-              raise e
-            ensure
-              Skylight.done(span, meta) if span
-            end
+        original_method_dispatch =
+          if is_setter_method
+            "self.send(:before_instrument_#{name}, #{arg_string})"
+          else
+            "before_instrument_#{name}(#{arg_string})"
           end
-        RUBY
+
+        klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            alias_method :"before_instrument_#{name}", :"#{name}"       # alias_method :"before_instrument_process", :"process"
+            def #{name}(#{arg_string})                                  # def process(*args, **kwargs, &blk)
+              span = Skylight.instrument(                               #   span = Skylight.instrument(
+                category:    :"#{category}",                            #     category:    :"app.method",
+                title:       #{title.inspect},                          #     title:       "process",
+                description: #{desc.inspect},                           #     description: "Process data",
+                source_file: #{source_file.inspect},                    #     source_file: "myapp/lib/processor.rb",
+                source_line: #{source_line.inspect})                    #     source_line: 123)
+                                                                        #
+              meta = {}                                                 #   meta = {}
+                                                                        #
+              begin                                                     #   begin
+                #{original_method_dispatch}                             #     self.before_instrument_process(...)
+              rescue Exception => e                                     #   rescue Exception => e
+                meta[:exception_object] = e                             #     meta[:exception_object] = e
+                raise e                                                 #     raise e
+              ensure                                                    #   ensure
+                Skylight.done(span, meta) if span                       #     Skylight.done(span, meta) if span
+              end                                                       #   end
+            end                                                         # end
+                                                                        #
+            if protected_method_defined?(:"before_instrument_#{name}")  # if protected_method_defined?(:"before_instrument_process")
+              protected :"#{name}"                                      #   protected :"process"
+            elsif private_method_defined?(:"before_instrument_#{name}") # elsif private_method_defined?(:"before_instrument_process")
+              private :"#{name}"                                        #   private :"process"
+            end                                                         # end
+          RUBY
       end
 
       if respond_to?(:singleton_class)
-        alias :__sk_singleton_class :singleton_class
+        alias __sk_singleton_class singleton_class
       else
         def __sk_singleton_class
-          class << self; self; end
+          class << self
+            self
+          end
         end
       end
     end
@@ -174,6 +218,5 @@ module Skylight
         extend ClassMethods
       end
     end
-
   end
 end

data/lib/skylight/instrumenter.rb

@@ -1,24 +1,354 @@
+require "strscan"
+require "securerandom"
+require "skylight/util/logging"
+require "skylight/extensions"
+
 module Skylight
-  class Instrumenter < Core::Instrumenter
-    def self.trace_class
-      Trace
+  # @api private
+  class Instrumenter
+    KEY = :__skylight_current_trace
+
+    include Util::Logging
+
+    class TraceInfo
+      def initialize(key = KEY)
+        @key = key
+        @muted_key = "#{key}_muted"
+      end
+
+      def current
+        Thread.current[@key]
+      end
+
+      def current=(trace)
+        Thread.current[@key] = trace
+      end
+
+      # NOTE: This should only be set by the instrumenter, and only
+      # in the context of a `mute` block. Do not try to turn this
+      # flag on and off directly.
+      def muted=(val)
+        Thread.current[@muted_key] = val
+      end
+
+      def muted?
+        !!Thread.current[@muted_key]
+      end
+    end
+
+    attr_reader :uuid, :config, :gc, :extensions, :subscriber
+
+    def self.native_new(_uuid, _config_env)
+      raise "not implemented"
+    end
+
+    def self.new(config)
+      config.validate!
+
+      uuid = SecureRandom.uuid
+      inst = native_new(uuid, config.to_native_env)
+      inst.send(:initialize, uuid, config)
+      inst
+    end
+
+    def initialize(uuid, config)
+      @uuid = uuid
+      @gc = config.gc
+      @config = config
+      @subscriber = Skylight::Subscriber.new(config, self)
+
+      @trace_info = @config[:trace_info] || TraceInfo.new(KEY)
+      @mutex = Mutex.new
+      @extensions = Skylight::Extensions::Collection.new(@config)
+    end
+
+    def enable_extension!(name)
+      @mutex.synchronize { extensions.enable!(name) }
+    end
+
+    def disable_extension!(name)
+      @mutex.synchronize { extensions.disable!(name) }
+    end
+
+    def extension_enabled?(name)
+      extensions.enabled?(name)
+    end
+
+    def log_context
+      @log_context ||= { inst: uuid }
+    end
+
+    def native_start
+      raise "not implemented"
+    end
+
+    def native_stop
+      raise "not implemented"
+    end
+
+    def native_track_desc(_endpoint, _description)
+      raise "not implemented"
+    end
+
+    def native_submit_trace(_trace)
+      raise "not implemented"
+    end
+
+    def current_trace
+      @trace_info.current
+    end
+
+    def current_trace=(trace)
+      t { "setting current_trace=#{trace ? trace.uuid : "nil"}; thread=#{Thread.current.object_id}" }
+      @trace_info.current = trace
     end
 
-    def check_install!
+    def validate_installation
       # Warn if there was an error installing Skylight.
 
-      if defined?(Skylight.check_install_errors)
-        Skylight.check_install_errors(config)
-      end
+      Skylight.check_install_errors(config) if defined?(Skylight.check_install_errors)
 
       if !Skylight.native? && defined?(Skylight.warn_skylight_native_missing)
         Skylight.warn_skylight_native_missing(config)
+        return false
+      end
+
+      true
+    end
+
+    def muted=(val)
+      @trace_info.muted = val
+    end
+
+    def muted?
+      @trace_info.muted?
+    end
+
+    def mute
+      old_muted = muted?
+      self.muted = true
+      yield if block_given?
+    ensure
+      self.muted = old_muted
+    end
+
+    def unmute
+      old_muted = muted?
+      self.muted = false
+      yield if block_given?
+    ensure
+      self.muted = old_muted
+    end
+
+    def silence_warnings(context)
+      @warnings_silenced || @mutex.synchronize { @warnings_silenced ||= {} }
+
+      @warnings_silenced[context] = true
+    end
+
+    def warnings_silenced?(context)
+      @warnings_silenced && @warnings_silenced[context]
+    end
+
+    alias disable mute
+    alias disabled? muted?
+
+    def start!
+      # We do this here since we can't report these issues via Gem install without stopping install entirely.
+      return unless validate_installation
+
+      t { "starting instrumenter" }
+
+      unless config.validate_with_server
+        log_error "invalid config"
         return
       end
+
+      t { "starting native instrumenter" }
+      unless native_start
+        warn "failed to start instrumenter"
+        return
+      end
+
+      enable_extension!(:source_location) if @config.enable_source_locations?
+      config.gc.enable
+      @subscriber.register!
+
+      ActiveSupport::Notifications.instrument("started_instrumenter.skylight", instrumenter: self)
+
+      self
+    rescue Exception => e
+      log_error "failed to start instrumenter; msg=%s; config=%s", e.message, config.inspect
+      t { e.backtrace.join("\n") }
+      nil
+    end
+
+    def shutdown
+      @subscriber.unregister!
+      native_stop
+    end
+
+    def trace(endpoint, cat, title = nil, desc = nil, meta: nil, segment: nil, component: nil)
+      # If a trace is already in progress, continue with that one
+      if (trace = @trace_info.current)
+        return yield(trace) if block_given?
+
+        return trace
+      end
+
+      begin
+        meta ||= {}
+        extensions.process_trace_meta(meta)
+        trace =
+          Trace.new(
+            self,
+            endpoint,
+            Skylight::Util::Clock.nanos,
+            cat,
+            title,
+            desc,
+            meta: meta,
+            segment: segment,
+            component: component
+          )
+      rescue Exception => e
+        log_error e.message
+        t { e.backtrace.join("\n") }
+        return
+      end
+
+      @trace_info.current = trace
+      return trace unless block_given?
+
+      begin
+        yield trace
+      ensure
+        @trace_info.current = nil
+        t { "instrumenter submitting trace; trace=#{trace.uuid}" }
+        trace.submit
+      end
     end
 
-    def process_sql(sql)
-      Skylight.lex_sql(sql)
+    def instrument(cat, title = nil, desc = nil, meta = nil)
+      raise ArgumentError, "cat is required" unless cat
+
+      if muted?
+        return yield if block_given?
+
+        return
+      end
+
+      unless (trace = @trace_info.current)
+        return yield if block_given?
+
+        return
+      end
+
+      cat = cat.to_s
+
+      unless Skylight::CATEGORY_REGEX.match?(cat)
+        warn "invalid skylight instrumentation category; trace=%s; value=%s", trace.uuid, cat
+        return yield if block_given?
+
+        return
+      end
+
+      cat = "other.#{cat}" unless Skylight::TIER_REGEX.match?(cat)
+
+      unless (sp = trace.instrument(cat, title, desc, meta))
+        return yield if block_given?
+
+        return
+      end
+
+      return sp unless block_given?
+
+      begin
+        yield sp
+      rescue Exception => e
+        meta ||= {}
+        meta[:exception] = [e.class.name, e.message]
+        meta[:exception_object] = e
+        raise e
+      ensure
+        trace.done(sp, meta)
+      end
+    end
+
+    def broken!
+      return unless (trace = @trace_info.current)
+
+      trace.broken!
+    end
+
+    def poison!
+      @poisoned = true
+    end
+
+    def poisoned?
+      @poisoned
+    end
+
+    def done(span, meta = nil)
+      return unless (trace = @trace_info.current)
+
+      trace.done(span, meta)
+    end
+
+    def process(trace)
+      t { fmt "processing trace=#{trace.uuid}" }
+
+      if ignore?(trace)
+        t { fmt "ignoring trace=#{trace.uuid}" }
+        return false
+      end
+
+      begin
+        finalize_endpoint_segment(trace)
+        native_submit_trace(trace)
+        true
+      rescue StandardError => e
+        handle_instrumenter_error(trace, e)
+      end
+    end
+
+    def handle_instrumenter_error(trace, err)
+      poison! if err.is_a?(Skylight::InstrumenterUnrecoverableError)
+
+      warn "failed to submit trace to worker; trace=%s, err=%s", trace.uuid, err
+      t { "BACKTRACE:\n#{err.backtrace.join("\n")}" }
+
+      false
+    end
+
+    def ignore?(trace)
+      config.ignored_endpoints.include?(trace.endpoint)
+    end
+
+    # Because GraphQL can return multiple results, each of which
+    # may have their own success/error states, we need to set the
+    # skylight segment as follows:
+    #
+    # - when all queries have errors: "error"
+    # - when some queries have errors: "<rendered format>+error"
+    # - when no queries have errors: "<rendered format>"
+    #
+    # <rendered format> will be determined by the Rails controller as usual.
+    # See Instrumenter#finalize_endpoint_segment for the actual segment/error assignment.
+    def finalize_endpoint_segment(trace)
+      return unless (segment = trace.segment)
+
+      segment =
+        case trace.compound_response_error_status
+        when :all
+          "error"
+        when :partial
+          "#{segment}+error"
+        else
+          segment
+        end
+
+      trace.endpoint += "<sk-segment>#{segment}</sk-segment>"
     end
   end
 end

data/lib/skylight/middleware.rb

@@ -1,4 +1,150 @@
+require "securerandom"
+
 module Skylight
-  class Middleware < Core::Middleware
+  # @api private
+  class Middleware
+    SKYLIGHT_REQUEST_ID = "skylight.request_id".freeze
+
+    class BodyProxy
+      def initialize(body, &block)
+        @body = body
+        @block = block
+        @closed = false
+      end
+
+      def respond_to_missing?(name, include_all = false)
+        return false if name.to_s =~ /^to_ary$/
+
+        @body.respond_to?(name, include_all)
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        begin
+          @body.close if @body.respond_to? :close
+        ensure
+          @block.call
+        end
+      end
+
+      def closed?
+        @closed
+      end
+
+      # N.B. This method is a special case to address the bug described by
+      # https://github.com/rack/rack/issues/434.
+      # We are applying this special case for #each only. Future bugs of this
+      # class will be handled by requesting users to patch their ruby
+      # implementation, to save adding too many methods in this class.
+      def each(*args, &block)
+        @body.each(*args, &block)
+      end
+
+      def method_missing(*args, &block)
+        super if args.first.to_s =~ /^to_ary$/
+        @body.__send__(*args, &block)
+      end
+    end
+
+    def self.with_after_close(resp, debug_identifier: "unknown", &block)
+      unless resp.respond_to?(:to_ary)
+        if resp.respond_to?(:to_a)
+          Skylight.warn(
+            "Rack response from \"#{debug_identifier}\" cannot be implicitly converted to an array. " \
+              "This is in violation of the Rack SPEC and will raise an error in future versions."
+          )
+          resp = resp.to_a
+        else
+          Skylight.error(
+            "Rack response from \"#{debug_identifier}\" cannot be converted to an array. This is in " \
+              "violation of the Rack SPEC and may cause problems with Skylight operation."
+          )
+          return resp
+        end
+      end
+
+      status, headers, body = resp
+      [status, headers, BodyProxy.new(body, &block)]
+    end
+
+    include Skylight::Util::Logging
+
+    # For Util::Logging
+    attr_reader :config
+
+    def initialize(app, opts = {})
+      @app = app
+      @config = opts[:config]
+    end
+
+    def call(env)
+      set_request_id(env)
+
+      if Skylight.tracing?
+        debug "Already instrumenting. Make sure the Skylight Rack Middleware hasn't been added more than once."
+        return @app.call(env)
+      end
+
+      if env["REQUEST_METHOD"] == "HEAD"
+        t { "middleware skipping HEAD" }
+        @app.call(env)
+      else
+        begin
+          t { "middleware beginning trace" }
+          trace = Skylight.trace(endpoint_name(env), "app.rack.request", nil, meta: endpoint_meta(env), component: :web)
+          t { "middleware began trace=#{trace ? trace.uuid : nil}" }
+
+          resp = @app.call(env)
+
+          trace ? Middleware.with_after_close(resp, debug_identifier: "Rack App: #{@app.class}") { trace.submit } : resp
+        rescue Exception => e
+          t { "middleware exception: #{e}\n#{e.backtrace.join("\n")}" }
+          trace&.submit
+          raise
+        end
+      end
+    end
+
+    private
+
+    def log_context
+      # Don't cache this, it will change
+      { request_id: current_request_id, inst: Skylight.instrumenter&.uuid }
+    end
+
+    # Allow for overwriting
+    def endpoint_name(_env)
+      "Rack"
+    end
+
+    def endpoint_meta(_env)
+      { source_location: Trace::SYNTHETIC }
+    end
+
+    # Request ID code based on ActionDispatch::RequestId
+    def set_request_id(env)
+      return if env[SKYLIGHT_REQUEST_ID]
+
+      existing_request_id = env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"]
+      self.current_request_id = env[SKYLIGHT_REQUEST_ID] = make_request_id(existing_request_id)
+    end
+
+    def make_request_id(request_id)
+      request_id && !request_id.empty? ? request_id.gsub(/[^\w\-]/, "".freeze)[0...255] : internal_request_id
+    end
+
+    def internal_request_id
+      SecureRandom.uuid
+    end
+
+    def current_request_id
+      Thread.current[SKYLIGHT_REQUEST_ID]
+    end
+
+    def current_request_id=(request_id)
+      Thread.current[SKYLIGHT_REQUEST_ID] = request_id
+    end
   end
 end