goodsorcery 0.1.1 → 0.2.0

data/lib/goodsorcery/performance/recorder.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Performance
+    # Measures one unit of work (a request or a job) on the current fiber:
+    # the total duration, the time per layer and, when traces are on, a raw
+    # span list. Spans are small arrays appended as events finish; nothing
+    # is copied or normalised until a trace is built (DESIGN.md 8.3).
+    #
+    #   [:sql, start, finish, sql, name, row_count, dialect]
+    #   [:http, start, finish, method, host, path, status]
+    #   [:view, start, finish, identifier]
+    #   [:enqueue, start, finish, job_class, queue]
+    #
+    # Times are monotonic seconds. A trace reads at most the first
+    # SqlNormalizer::INPUT_LIMIT characters of a statement, so only those
+    # (and one more, which tells the normaliser the text was cut) are kept,
+    # and at most MAX_SQL_BYTES of SQL text per unit of work; past either
+    # bound a span is only counted (spans_dropped).
+    class Recorder
+      MAX_RAW_SPANS = 2_000
+      MAX_SQL_CHARS = SqlNormalizer::INPUT_LIMIT + 1
+      MAX_SQL_BYTES = 4 * 1_024 * 1_024
+      MAX_RENDER_DEPTH = 100
+
+      attr_reader :kind, :started, :started_wall, :spans, :db_ms, :http_ms, :sql_count, :http_count,
+                  :spans_dropped, :duration_ms, :finished_wall, :gc
+      attr_accessor :name, :http_method, :route, :source, :adapter, :queue, :queue_wait_ms, :status,
+                    :error_event_id, :env, :job_details
+
+      def initialize(kind, traces:)
+        @kind = kind
+        @started = Performance.monotonic
+        @started_wall = Process.clock_gettime(Process::CLOCK_REALTIME)
+        @db_ms = @http_ms = @render_view_ms = 0.0
+        @sql_count = @http_count = @spans_dropped = @sql_bytes = 0
+        @render_stack = []
+        @failed = @broken = false
+        start_trace if traces
+      end
+
+      def traces? = !@spans.nil?
+      def failed? = @failed
+      def broken? = @broken
+      def failed! = (@failed = true)
+      def broken! = (@broken = true)
+
+      # An exception escaped the unit of work. A request fails only when the
+      # exception becomes a 5xx (+status+ is what Rails answers it with; 500
+      # when unknown): a RecordNotFound is a 404, not a failure.
+      def raised!(status = nil)
+        return @failed = true unless @kind == :web
+
+        @status = status || 500
+        @failed = @status >= 500
+      end
+
+      def response_status=(status)
+        @status = status
+        @failed = true if status && status >= 500
+      end
+
+      # Yields once, the second time SQL of the same shape runs (8.5), for
+      # the call site.
+      def add_sql(start, finish, sql, name, rows, dialect: nil, &)
+        @db_ms += (finish - start) * 1000.0
+        @sql_count += 1
+        return unless @spans
+
+        sql = kept_sql(sql)
+        return @spans_dropped += 1 unless sql
+
+        @repeats.note(sql, &)
+        push([:sql, start, finish, sql, name, rows, dialect])
+      end
+
+      # +times+ is [start, finish].
+      def add_http(times, method, host, path, status)
+        start, finish = times
+        @http_ms += (finish - start) * 1000.0
+        @http_count += 1
+        push([:http, start, finish, method, host, path, status]) if @spans
+      end
+
+      def add_enqueue(start, finish, job_class, queue)
+        push([:enqueue, start, finish, job_class, queue]) if @spans
+      end
+
+      def render_started(now)
+        @render_stack.push([now, @db_ms + @http_ms]) if @render_stack.size < MAX_RENDER_DEPTH
+      end
+
+      # Only the outermost render counts toward view time, minus the queries
+      # and HTTP calls made while it was open, so nested renders and the
+      # other layers are never counted twice. Every render of the unit of
+      # work adds up (render_to_string, then render).
+      def render_finished(now, identifier)
+        start, others_at_start = @render_stack.pop
+        return unless start
+
+        push([:view, start, now, identifier]) if @spans
+        return unless @render_stack.empty?
+
+        others = @db_ms + @http_ms - others_at_start
+        @render_view_ms += [((now - start) * 1000.0) - others, 0.0].max
+      end
+
+      def call_site_for(sql)
+        @repeats&.call_site(sql)
+      end
+
+      def stop(now = Performance.monotonic)
+        @duration_ms = (now - @started) * 1000.0
+        @finished_wall = @started_wall + (now - @started)
+        @gc = @gc_start&.delta
+      end
+
+      # Web requests too: the controller's view_runtime includes queries run
+      # from templates whenever Active Record's logger is above info, keeps
+      # only the last render and includes HTTP calls made while rendering.
+      def view_ms = @render_view_ms
+
+      def ruby_ms
+        [@duration_ms - @db_ms - @http_ms - view_ms, 0.0].max
+      end
+
+      private
+
+      def start_trace
+        @spans = []
+        @repeats = RepeatedQueries.new
+        @gc_start = GcSnapshot.take
+      end
+
+      # The statement as the trace will read it, or nil when no more SQL text
+      # fits (or the span list is full).
+      def kept_sql(sql)
+        sql = sql.to_s
+        sql = sql[0, MAX_SQL_CHARS] if sql.bytesize > MAX_SQL_CHARS
+        return nil if @spans.size >= MAX_RAW_SPANS || @sql_bytes + sql.bytesize > MAX_SQL_BYTES
+
+        @sql_bytes += sql.bytesize
+        sql
+      end
+
+      def push(span)
+        if @spans.size < MAX_RAW_SPANS
+          @spans << span
+        else
+          @spans_dropped += 1
+        end
+      end
+    end
+
+    # Remembers which shapes of SQL ran in one unit of work, and the call
+    # site of each shape that ran at least twice (captured once). The shape
+    # is the text without its digits, as an Integer hash: the same for
+    # "WHERE id = 7" and "WHERE id = 8", so adapters that write literal ids
+    # into the SQL still get a call site, and no copy of the text is kept.
+    class RepeatedQueries
+      MAX_TEXTS = 2_000
+      SEEN_ONCE = true
+
+      def self.shape(sql)
+        (sql.valid_encoding? ? sql : sql.b).delete("0-9").hash
+      end
+
+      def initialize
+        @shapes = {}
+      end
+
+      def note(sql)
+        key = self.class.shape(sql)
+        seen = @shapes[key]
+        if seen.nil?
+          @shapes[key] = SEEN_ONCE if @shapes.size < MAX_TEXTS
+        elsif seen == SEEN_ONCE
+          @shapes[key] = (block_given? && yield) || false
+        end
+      end
+
+      def call_site(sql)
+        site = @shapes[self.class.shape(sql)]
+        site.is_a?(CallSite) ? site : nil
+      end
+    end
+
+    # Process-wide GC figures at the start of a unit of work, and their
+    # change since.
+    GcSnapshot = Struct.new(:time_ms, :gc_count, :allocations) do
+      def self.take
+        new(GC.stat(:time), GC.count, GC.stat(:total_allocated_objects))
+      end
+
+      def delta
+        now = self.class.take
+        { "time_ms" => (now.time_ms - time_ms).to_f, "count" => now.gc_count - gc_count,
+          "allocations" => now.allocations - allocations }
+      end
+    end
+  end
+end

data/lib/goodsorcery/performance/span_list.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Performance
+    # Turns a recorder's raw spans into the trace payload's "spans"
+    # (DESIGN.md 8.5): SQL normalised, repeated identical SQL (and repeated
+    # renders of one template) grouped into one span with its count, total
+    # and call site, at most MAX_SPANS spans (the longest), in start order.
+    class SpanList
+      MAX_SPANS = 300
+      MAX_NAME_LENGTH = 255
+      MAX_PATH_LENGTH = 1_024
+      VIEWS_DIR = "/app/views/"
+      # A path given as an absolute URL ("https://user:pass@host/v1") or a
+      # network-path reference ("//host/v1"): its scheme and authority.
+      URL_PREFIX = %r{\A(?:[a-z][a-z0-9+.-]*:)?//[^/?#]*}i
+
+      attr_reader :dropped
+
+      def initialize(recorder, context)
+        @recorder = recorder
+        @context = context
+        @normalized = {}
+        @dropped = 0
+      end
+
+      def to_a
+        groups = group(@recorder.spans).sort_by(&:first_start)
+        groups = cap(groups) if groups.size > MAX_SPANS
+        groups.map { |span_group| span_group.to_h(@recorder.started, @context) }
+      end
+
+      private
+
+      def group(raw_spans)
+        groups = {}
+        raw_spans.each_with_index do |raw, index|
+          slot = group_key(raw) || index
+          existing = groups[slot]
+          existing ? existing.add(raw) : groups[slot] = SpanGroup.new(raw, fields(raw))
+          groups[slot].find_call_site(@recorder, raw)
+        end
+        groups.values
+      end
+
+      def cap(groups)
+        kept = groups.max_by(MAX_SPANS, &:total_ms)
+        @dropped += (groups - kept).sum(&:count)
+        kept.sort_by(&:first_start)
+      end
+
+      # SQL groups by its normalised text and views by template; HTTP calls
+      # and enqueues are never grouped.
+      def group_key(raw)
+        case raw[0]
+        when :sql then [:sql, normalized(raw)]
+        when :view then [:view, template_name(raw[3])]
+        end
+      end
+
+      def fields(raw)
+        case raw[0]
+        when :sql then { "name" => Text.limit(raw[4] || "SQL", MAX_NAME_LENGTH), "sql" => normalized(raw) }
+        when :view then { "template" => template_name(raw[3]) }
+        when :http then http_fields(raw)
+        else enqueue_fields(raw)
+        end
+      end
+
+      def normalized(raw)
+        (@normalized[raw[6]] ||= {})[raw[3]] ||= @context.normalizer.normalize(raw[3], raw[6])
+      end
+
+      # Method, host and path only: never a query string, fragment or
+      # userinfo, even when the app passed a whole URL as the path.
+      def http_fields(raw)
+        path = raw[5].to_s.sub(URL_PREFIX, "").split(/[?#]/, 2).first.to_s
+        { "method" => Text.limit(raw[3], 16), "host" => Text.limit(raw[4], MAX_NAME_LENGTH),
+          "path" => Text.limit(path.empty? ? "/" : path, MAX_PATH_LENGTH), "status" => raw[6] }.compact
+      end
+
+      def enqueue_fields(raw)
+        { "job" => Text.limit(raw[3], MAX_NAME_LENGTH), "queue" => raw[4] && Text.limit(raw[4], 128) }.compact
+      end
+
+      # Relative to app/views; a template outside the app keeps the part
+      # after its last "views/" directory, else its file name.
+      def template_name(identifier)
+        @templates ||= {}
+        @templates[identifier] ||= relative_template(identifier.to_s)
+      end
+
+      def relative_template(path)
+        index = path.rindex(VIEWS_DIR)
+        name = if index then path[(index + VIEWS_DIR.size)..]
+               elsif (views = path.rindex("/views/")) then path[(views + 7)..]
+               else File.basename(path)
+               end
+        Text.limit(name, MAX_NAME_LENGTH)
+      end
+    end
+
+    # One span of the payload: a single call, or a group of identical ones.
+    class SpanGroup
+      DECIMALS = 3
+
+      attr_reader :first_start, :last_finish, :total_ms, :count, :rows, :call_site
+
+      def initialize(raw, fields)
+        @type = raw[0]
+        @fields = fields
+        @first_start = raw[1]
+        @last_finish = raw[2]
+        @total_ms = (raw[2] - raw[1]) * 1000.0
+        @count = 1
+        @rows = sql_rows(raw)
+      end
+
+      def add(raw)
+        @count += 1
+        @total_ms += (raw[2] - raw[1]) * 1000.0
+        @last_finish = raw[2] if raw[2] > @last_finish
+        rows = sql_rows(raw)
+        @rows = (@rows || 0) + rows if rows
+      end
+
+      # A SQL group takes the call site captured for any of its raw texts.
+      def find_call_site(recorder, raw)
+        return @call_site if @call_site || @type != :sql
+
+        @call_site = recorder.call_site_for(raw[3])
+      end
+
+      def to_h(origin, context)
+        hash = { "type" => @type.to_s, "offset_ms" => ms(@first_start - origin),
+                 "duration_ms" => @total_ms.round(DECIMALS) }.merge!(@fields)
+        hash["rows"] = @rows if @rows
+        return hash if @count < 2
+
+        hash.merge!("count" => @count, "span_ms" => ms(@last_finish - @first_start))
+        hash["call_site"] = context.call_site_hash(@call_site) if @call_site
+        hash
+      end
+
+      private
+
+      def sql_rows(raw)
+        raw[0] == :sql && raw[5].is_a?(Integer) ? raw[5] : nil
+      end
+
+      def ms(seconds)
+        [(seconds * 1000.0).round(DECIMALS), 0.0].max
+      end
+    end
+  end
+end

data/lib/goodsorcery/performance/sql_normalizer.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Performance
+    # Turns raw SQL into the text a trace may carry (DESIGN.md 8.6): no
+    # comments, no literal values, IN lists and VALUES rows collapsed,
+    # whitespace collapsed. Bind placeholders ($1), identifiers and the
+    # keywords TRUE, FALSE and NULL stay readable.
+    #
+    # One left-to-right pass decides what each piece is, so a quote inside a
+    # comment, "--" inside a string or a digit inside a quoted identifier is
+    # read correctly. How quotes work depends on the database (SqlDialect):
+    # a backslash escapes only in MySQL and in Postgres E'…' strings, and
+    # "…" is a string in MySQL (and may be one in SQLite). The two ways of
+    # reading a backslash first disagree at a string that contains one, so
+    # when the dialect is unknown, or a string runs on to the end of a
+    # statement that was not cut off (the quotes were misread), everything
+    # from that string on becomes one placeholder: a misread never leaves a
+    # literal value in the text.
+    class SqlNormalizer
+      INPUT_LIMIT = 4_000
+      OUTPUT_LIMIT = 2_000
+      PLACEHOLDER = "?"
+      ELLIPSIS = "…"
+
+      COMMENT = %r{/\*.*?(?:\*/|\z)|--[^\n]*}m
+      BACKTICK = /`[^`]*(?:`|\z)/
+      DOLLAR_QUOTED = /\$(?<tag>(?:[a-z_]\w*)?)\$.*?(?:(?<close>\$\k<tag>\$)|\z)/mi
+      STANDARD_STRING = /'(?:[^']|'')*(?:(?<close>')|\z)/
+      BACKSLASH_STRING = /'(?:[^'\\]|\\.|'')*(?:(?<close>')|\z)/m
+      ESCAPE_STRING = /(?<![\w$])[eE]'(?:[^'\\]|\\.|'')*(?:(?<close>')|\z)/m
+      STANDARD_DOUBLE = /"(?:[^"]|"")*(?:(?<close>")|\z)/
+      BACKSLASH_DOUBLE = /"(?:[^"\\]|\\.|"")*(?:(?<close>")|\z)/m
+      NUMBER = /(?<![\w$])(?:0x[0-9a-f]+|\d+(?:\.\d+)?(?:e[+-]?\d+)?)/i
+      # What an unquoted identifier may contain; other "…" text is a value.
+      IDENTIFIER = /\A[[:alnum:]_$]*\z/
+
+      def self.token(strings, double)
+        /(?<comment>#{COMMENT})|(?<backtick>#{BACKTICK})|(?<double>#{double})
+         |(?<literal>#{DOLLAR_QUOTED}|#{strings})|(?<number>#{NUMBER})/x
+      end
+
+      # One way of reading quotes: the token pattern and what "…" is
+      # (:identifier, :literal, or :guess from its contents).
+      Rules = Struct.new(:token, :double)
+      RULES = {
+        postgres: Rules.new(token(/#{ESCAPE_STRING}|#{STANDARD_STRING}/, STANDARD_DOUBLE), :identifier),
+        sqlite: Rules.new(token(STANDARD_STRING, STANDARD_DOUBLE), :guess),
+        mysql: Rules.new(token(BACKSLASH_STRING, BACKSLASH_DOUBLE), :literal),
+        nil => Rules.new(token(BACKSLASH_STRING, BACKSLASH_DOUBLE), :guess)
+      }.freeze
+
+      LIST_ITEM = /(?:-?\?|\$\d+)/
+      IN_LIST = /\bIN\s*\(\s*#{LIST_ITEM}(?:\s*,\s*#{LIST_ITEM})*\s*\)/io
+      VALUES_ROWS = /(\bVALUES\s*\([^()]*\))(?:\s*,\s*\([^()]*\))+/i
+      WHITESPACE = /\s+/
+
+      # +dialect+ is :postgres, :mysql, :sqlite or nil (unknown).
+      def normalize(sql, dialect = nil)
+        text = Text.utf8(sql.is_a?(String) ? sql : sql.to_s)
+        cut = text.length > INPUT_LIMIT
+        text = remove_literals(Text.limit(text, INPUT_LIMIT), dialect, cut)
+        text = text.gsub(IN_LIST, "IN (#{ELLIPSIS})").gsub(VALUES_ROWS) { "#{Regexp.last_match(1)}, #{ELLIPSIS}" }
+        Text.limit(text.gsub(WHITESPACE, " ").strip, OUTPUT_LIMIT)
+      end
+
+      private
+
+      # With a known dialect, a string left open is trusted only where the
+      # length cap cut the statement.
+      def remove_literals(text, dialect, cut)
+        rules = RULES.fetch(dialect, RULES[nil])
+        pass = Pass.new(text, rules)
+        at = pass.first_backslash
+        return pass.result if at.nil? || (dialect && (pass.closed? || cut))
+
+        "#{Pass.new(text[0, at], rules).result} #{PLACEHOLDER}"
+      end
+
+      # One left-to-right replacement of comments, literals and numbers.
+      class Pass
+        attr_reader :result, :first_backslash
+
+        def initialize(text, rules)
+          @rules = rules
+          @open = false
+          @first_backslash = nil
+          @result = text.gsub(rules.token) { replacement(Regexp.last_match) }
+        end
+
+        # => false when a string ran on to the end of the text.
+        def closed? = !@open
+
+        private
+
+        def replacement(match)
+          return " " if match[:comment]
+          return match[0] if match[:backtick] || identifier?(match)
+
+          note_quote(match) unless match[:number]
+          PLACEHOLDER
+        end
+
+        def identifier?(match)
+          return false unless (double = match[:double])
+
+          case @rules.double
+          when :identifier then true
+          when :literal then false
+          else IDENTIFIER.match?(double[1..].delete_suffix("\""))
+          end
+        end
+
+        # Where the first quoted value holding a backslash starts, and
+        # whether one ran on to the end.
+        def note_quote(match)
+          @first_backslash ||= match.begin(0) if match[0].include?("\\")
+          @open = true if match[:close].nil?
+        end
+      end
+    end
+
+    # Which SQL dialect a sql.active_record payload's connection speaks
+    # (:postgres, :mysql, :sqlite, or nil), cached per adapter class.
+    module SqlDialect
+      MAX_ENTRIES = 32
+      @cache = {}
+
+      def self.for(connection)
+        return nil unless connection.respond_to?(:adapter_name)
+
+        klass = connection.class
+        return @cache[klass] if @cache.key?(klass)
+
+        dialect = from_name(connection.adapter_name)
+        @cache[klass] = dialect if @cache.size < MAX_ENTRIES
+        dialect
+      end
+
+      def self.from_name(name)
+        case name.to_s
+        when /mysql|trilogy|maria/i then :mysql
+        when /postg|cockroach/i then :postgres
+        when /sqlite/i then :sqlite
+        end
+      end
+    end
+  end
+end

data/lib/goodsorcery/performance/subscribers.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Performance
+    # ActiveSupport::Notifications subscriptions (DESIGN.md 8.3), made once.
+    # Every callback returns at once unless a recorder is active on this
+    # fiber, and never raises into the instrumented code: a failure stops
+    # recording for that unit of work (Performance.with_recorder).
+    module Subscribers
+      IGNORED_SQL_NAMES = %w[SCHEMA CACHE].freeze
+      RENDER_EVENTS = %w[
+        render_template.action_view render_layout.action_view
+        render_partial.action_view render_collection.action_view
+      ].freeze
+      # retry_on and discard_on handle the exception inside perform_now, so
+      # these mark the attempt as failed.
+      JOB_FAILURE_EVENTS = %w[enqueue_retry.active_job retry_stopped.active_job discard.active_job].freeze
+
+      module_function
+
+      def subscribe
+        return false if @subscribed || !defined?(::ActiveSupport::Notifications)
+
+        @subscribed = true
+        subscribe_timed(::ActiveSupport::Notifications)
+        JOB_FAILURE_EVENTS.each { |name| ::ActiveSupport::Notifications.subscribe(name) { |*| on_job_failure } }
+        RENDER_EVENTS.each { |name| ::ActiveSupport::Notifications.subscribe(name, RenderListener) }
+        true
+      end
+
+      # Monotonic subscribers get (name, start, finish, id, payload).
+      def subscribe_timed(notifications)
+        notifications.monotonic_subscribe("sql.active_record") do |_name, start, finish, _id, payload|
+          on_sql(start, finish, payload)
+        end
+        notifications.monotonic_subscribe("process_action.action_controller") do |_name, _start, _finish, _id, payload|
+          on_action(payload)
+        end
+        notifications.monotonic_subscribe("enqueue.active_job") do |_name, start, finish, _id, payload|
+          on_enqueue(start, finish, payload)
+        end
+      end
+
+      def subscribed?
+        @subscribed ? true : false
+      end
+
+      def on_sql(start, finish, payload)
+        Performance.with_recorder do |recorder|
+          next if payload[:cached] || IGNORED_SQL_NAMES.include?(payload[:name])
+
+          recorder.add_sql(start, finish, payload[:sql], payload[:name], payload[:row_count],
+                           dialect: SqlDialect.for(payload[:connection])) do
+            CallSite.capture(Performance.paths)
+          end
+        end
+      end
+
+      def on_action(payload)
+        Performance.with_recorder do |recorder|
+          next unless recorder.kind == :web && recorder.name.nil?
+
+          controller = payload[:controller]
+          recorder.name = "#{controller}##{payload[:action]}"
+          recorder.route = RoutePattern.for(payload[:request])
+          recorder.source = SourceLocation.for(controller)
+        end
+      end
+
+      def on_enqueue(start, finish, payload)
+        Performance.with_recorder do |recorder|
+          job = payload[:job]
+          recorder.add_enqueue(start, finish, job.class.name, job.queue_name) if job
+        end
+      end
+
+      def on_job_failure
+        Performance.with_recorder { |recorder| recorder.failed! if recorder.kind == :job }
+      end
+    end
+
+    # Evented listener for the render events: the start and finish of each
+    # render, so nested renders are counted once (Recorder#render_finished).
+    module RenderListener
+      module_function
+
+      def start(_name, _id, _payload)
+        Performance.with_recorder { |recorder| recorder.render_started(Performance.monotonic) }
+      end
+
+      def finish(_name, _id, payload)
+        Performance.with_recorder { |recorder| recorder.render_finished(Performance.monotonic, payload[:identifier]) }
+      end
+    end
+
+    # The matched route's pattern ("/products/:id"), without "(.:format)".
+    # Needs Rails 7.1 or newer; nil otherwise.
+    module RoutePattern
+      FORMAT_SUFFIX = "(.:format)"
+
+      def self.for(request)
+        return nil unless request.respond_to?(:route_uri_pattern)
+
+        request.route_uri_pattern&.delete_suffix(FORMAT_SUFFIX)
+      end
+    end
+
+    # The app-relative file that defines a controller or job class, cached
+    # per class name. Classes outside the app root have none.
+    module SourceLocation
+      MAX_ENTRIES = 2_000
+      @cache = {}
+      @lock = Mutex.new
+
+      def self.for(class_name)
+        return nil if class_name.nil?
+
+        name = class_name.to_s
+        cached = @cache.fetch(name, false)
+        return cached unless cached == false
+
+        locate(name).tap { |path| @lock.synchronize { @cache[name] = path if @cache.size < MAX_ENTRIES } }
+      end
+
+      def self.locate(name)
+        file, = Object.const_source_location(name)
+        return nil unless file
+
+        relative = Performance.paths.relative(file)
+        relative.start_with?("/") ? nil : relative
+      rescue NameError, ArgumentError
+        nil
+      end
+
+      def self.clear
+        @lock.synchronize { @cache.clear }
+      end
+    end
+  end
+end