sixty 0.1.0

data/lib/sixty/instrument/pg.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require_relative '../tracer'
+require_relative '../sql'
+require_relative '../stack'
+
+module Sixty
+  module Instrument
+    # The `pg` gem, patched directly.
+    #
+    # ── Who this is for ───────────────────────────────────────────────────────
+    #
+    # A Rails application is covered by `sql.active_record`, which is a public
+    # interface every adapter emits and every version has — strictly better than
+    # patching, so when ActiveRecord is in the process this is not installed at
+    # all. What it covers is everything else: Sinatra, Roda, a Sidekiq worker
+    # that talks to Postgres directly, Sequel and ROM (both of which run their
+    # queries through this class), and scripts.
+    #
+    # ── What is captured beyond timing ───────────────────────────────────────
+    #
+    #   rows   : `ntuples` for a read, `cmd_tuples` for a write. The 30 → 30,000
+    #            signal, and the one thing a slow-query log cannot show you.
+    #   fields : column count, which is how `select *` creeping into a hot path
+    #            becomes visible.
+    #   bytes  : a sampled estimate of the result's size.
+    #
+    # Never the SQL text, and never a parameter: only the normalized shape.
+    #
+    # ── No query plans on this path ──────────────────────────────────────────
+    #
+    # The ActiveRecord instrumentation captures plans because it can borrow a
+    # connection from a pool that is designed to be borrowed from. Here there is
+    # no pool — only the caller's own `PG::Connection`, which is not thread-safe
+    # and may be mid-query on another thread when the flush thread wakes up. The
+    # alternatives are worse: running the EXPLAIN inline puts a second round trip
+    # in front of a user, and opening a connection of our own means an
+    # observability agent quietly consuming a slot in somebody's connection
+    # limit. So plans are a Rails feature for now, and this path reports
+    # everything else.
+    module Pg
+      # `exec`, `query` and `async_exec` are the same method under three names in
+      # modern pg, and `super` resolves by name — so a call to `exec` reaches the
+      # original `exec` rather than this module's `async_exec`, and nothing is
+      # counted twice. `sync_*` are separate implementations and need their own
+      # wrapper.
+      TEXT_FIRST = %i[exec query async_exec sync_exec exec_params async_exec_params
+                      sync_exec_params].freeze
+
+      class << self
+        def install(config = nil)
+          return false if @installed
+          return false unless defined?(::PG::Connection)
+
+          @config = config
+          ::PG::Connection.prepend(Patch)
+          @installed = true
+        end
+
+        def installed?
+          @installed == true
+        end
+
+        attr_reader :config
+
+        # Prepared statements name a query somewhere other than the call site.
+        # `exec_prepared('find_user', [id])` has no SQL in it at all, so the text
+        # is remembered when the statement is prepared and looked up when it is
+        # run. Bounded, because a process that has prepared a thousand distinct
+        # statements is not going to learn much from the next one.
+        MAX_PREPARED = 500
+
+        def remember_prepared(name, sql)
+          return unless name.is_a?(String) && sql.is_a?(String)
+
+          @prepared ||= {}
+          @prepared.clear if @prepared.size >= MAX_PREPARED
+          @prepared[name] = sql
+        end
+
+        def prepared_sql(name)
+          @prepared&.[](name)
+        end
+
+        def reset!
+          @installed = false
+          @prepared = nil
+        end
+
+        # One span for one statement. Shared by every wrapper below so that the
+        # rules — never raise, always emit, capture frames once — live in one
+        # place rather than in seven.
+        def measure(sql)
+          return yield unless Sixty.enabled? && sql.is_a?(String) && !sql.empty?
+
+          normalized = Sql.normalize_sql(sql)
+          started = Tracer.monotonic_ms
+          begin
+            result = yield
+          rescue StandardError => e
+            record(sql, normalized, Tracer.monotonic_ms - started, nil, e)
+            raise
+          end
+          record(sql, normalized, Tracer.monotonic_ms - started, result, nil)
+          result
+        end
+
+        private
+
+        def record(sql, normalized, duration_ms, result, error)
+          attrs = { normalized_sql: normalized }
+          frames = Stack.capture(normalized)
+          if frames
+            attrs[:frames] = frames
+            attrs[:file] = frames.first[:file]
+            attrs[:line] = frames.first[:line]
+          end
+          measure_result(result, attrs) if result
+
+          Tracer.record(
+            kind: Tracer::KIND_DB,
+            name: Sql.sql_operation_name(normalized),
+            duration_ms: duration_ms,
+            attrs: attrs,
+            error: error
+          )
+        rescue StandardError
+          # An unmeasured query, not a failed one.
+          nil
+        end
+
+        def measure_result(result, attrs)
+          return unless result.respond_to?(:ntuples)
+
+          returned = result.ntuples
+          # A write returns no tuples and reports what it changed instead. Both
+          # are "rows this statement was responsible for", which is what the
+          # signal means everywhere else in this agent.
+          attrs[:rows] = returned.positive? ? returned : result.cmd_tuples.to_i
+          attrs[:fields] = result.nfields if result.respond_to?(:nfields)
+          attrs[:bytes] = estimate_bytes(result) if returned.positive?
+        rescue StandardError
+          nil
+        end
+
+        # Sampled and extrapolated: a full measurement of every result would
+        # itself be the performance problem this agent exists to find.
+        #
+        # `getlength` asks libpq for the size of a value in bytes without
+        # building anything. The obvious spelling — `result[i].to_s.bytesize` —
+        # materialises a Ruby hash per row and renders it to a string, which
+        # measured at six microseconds a query on a two-column table and would
+        # grow with every column. This is the same number, without the garbage.
+        def estimate_bytes(result)
+          rows = result.ntuples
+          fields = result.nfields
+          sample = [rows, 3].min
+          return 0 if sample.zero? || fields.zero?
+
+          total = 0
+          sample.times { |i| fields.times { |j| total += result.getlength(i, j) } }
+          ((total.to_f / sample) * rows).round
+        rescue StandardError
+          0
+        end
+      end
+
+      # Prepended rather than aliased, so `super` reaches the driver's own
+      # implementation and an application that removes the gem's instrumentation
+      # gets its untouched methods back.
+      module Patch
+        Sixty::Instrument::Pg::TEXT_FIRST.each do |method|
+          define_method(method) do |*args, &block|
+            sql = args.first
+            sql = sql[:text] || sql['text'] if sql.is_a?(Hash)
+            Sixty::Instrument::Pg.measure(sql) { super(*args, &block) }
+          end
+          ruby2_keywords method
+        end
+
+        def prepare(*args, &block)
+          Sixty::Instrument::Pg.remember_prepared(args[0], args[1])
+          super
+        end
+
+        def exec_prepared(*args, &block)
+          sql = Sixty::Instrument::Pg.prepared_sql(args[0])
+          # A statement prepared before the agent started has no text here. It is
+          # measured under its own name rather than dropped, because a query
+          # nobody can see is worse than one labelled by its statement name.
+          Sixty::Instrument::Pg.measure(sql || "prepared #{args[0]}") { super }
+        end
+        ruby2_keywords :exec_prepared
+      end
+    end
+  end
+end

data/lib/sixty/instrument/rack.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative '../tracer'
+require_relative '../sql'
+
+module Sixty
+  module Instrument
+    # Inbound HTTP.
+    #
+    # This is the root span every other span in a request hangs off, and it is
+    # what makes "which endpoint got slower" answerable at all. It is Rack
+    # middleware rather than a Rails hook so the same class covers Sinatra,
+    # Roda, Hanami and a bare Rack app — the Node agent patches `http.Server`
+    # for the same reason.
+    #
+    # ── Naming, and why the route matters so much ─────────────────────────────
+    #
+    # Middleware runs before routing, so at span start all we have is the path.
+    # `/users/42` and `/users/43` are different paths and the same endpoint, and
+    # recording them separately would mint an operation per user id — the
+    # cardinality cap would be hit within minutes and every one of those
+    # operations would have too little traffic to compare against anything.
+    #
+    # So the path is templated on the way in, and on the way out the real Rails
+    # route pattern replaces it if the router recorded one. The template is the
+    # fallback; the pattern is the truth.
+    class Rack
+      def initialize(app, config: nil)
+        @app = app
+        @config = config
+      end
+
+      # ── The rule this method is written to ────────────────────────────────
+      #
+      # Nothing the agent does may change what the application returns, and
+      # nothing the agent gets wrong may stop it returning at all. So every
+      # line that belongs to us is inside a rescue, and the one line that
+      # belongs to the application — `@app.call(env)` — is not wrapped in
+      # anything that could swallow or alter it. A middleware that 500s a
+      # request because a measurement failed has done more damage than every
+      # finding it could ever produce.
+      def call(env)
+        span = begin
+          start(env)
+        rescue StandardError
+          nil
+        end
+
+        return @app.call(env) unless span
+
+        previous = Tracer.current
+        Tracer.current = span
+        begin
+          status, headers, body = @app.call(env)
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          Tracer.current = previous
+          safely { span.attrs[:status] = 500 }
+          safely { finish(span, env, e) }
+          raise
+        end
+
+        Tracer.current = previous
+        safely do
+          span.attrs[:status] = status
+          length = headers && (headers['content-length'] || headers['Content-Length'])
+          span.attrs[:bytes] = length.to_i if length
+          # A 5xx is an error whether or not anything was raised: the exception
+          # may have been rescued into a rendered error page three layers down,
+          # and from the outside those are the same failure.
+          finish(span, env, status.to_i >= 500 ? StandardError.new("HTTP #{status}") : nil)
+        end
+
+        [status, headers, body]
+      end
+
+      private
+
+      # Read lazily rather than captured at construction: Rails builds its
+      # middleware stack while the initializer that calls `Sixty.init` may not
+      # have run yet, and a middleware holding a nil config would silently
+      # ignore nothing and sample at zero for the life of the process.
+      def config
+        @config || Sixty.config
+      end
+
+      # @return [Tracer::Span, nil] nil when this request is not ours to measure
+      def start(env)
+        return nil unless Sixty.enabled?
+
+        path = env['PATH_INFO'].to_s
+        return nil if config&.ignore?(path)
+
+        method = env['REQUEST_METHOD'].to_s
+        span = Tracer.start_span(
+          kind: Tracer::KIND_HTTP,
+          name: "#{method} #{Sql.template_path(path)}",
+          attrs: { method: method }
+        )
+        # Head sampling decides whether an *uneventful* trace is retained.
+        # Errors and slow outliers are kept regardless, decided at finish time.
+        span.recording = rand < config&.sample_rate.to_f
+        span
+      end
+
+      def safely
+        yield
+      rescue StandardError => e
+        Sixty.config&.on_warn&.call("sixty: middleware error: #{e.message}")
+      end
+
+      def finish(span, env, error)
+        route = route_pattern(env)
+        span.name = "#{span.attrs[:method]} #{route}" if route
+        Tracer.end_span(span, error)
+        Tracer.emit(span)
+      end
+
+      # What the router matched, in three descending preferences. All are read
+      # after the app has run, because none of them exists before routing.
+      #
+      #   1. `action_dispatch.route_uri_pattern` — the pattern as a string, if
+      #      anything in the request already asked for it.
+      #   2. `action_dispatch.route` — the matched route itself. This is the one
+      #      that is actually present on a plain request: Rails fills the header
+      #      above lazily, the first time somebody calls `route_uri_pattern`,
+      #      and on most requests nobody does.
+      #   3. the recognized parameters, which give `orders#index` rather than a
+      #      path. Less readable, still one operation per endpoint, and it is
+      #      what a Rails older than 7.1 has.
+      def route_pattern(env)
+        pattern = env['action_dispatch.route_uri_pattern']
+        return normalize_pattern(pattern) if pattern.is_a?(String) && !pattern.empty?
+
+        route = env['action_dispatch.route']
+        if route
+          spec = begin
+            route.path.spec.to_s
+          rescue StandardError
+            nil
+          end
+          return normalize_pattern(spec) if spec.is_a?(String) && !spec.empty?
+        end
+
+        params = env['action_dispatch.request.path_parameters']
+        return nil unless params.is_a?(Hash) && params[:controller]
+
+        "#{params[:controller]}##{params[:action]}"
+      end
+
+      # `/users/:id(.:format)` is the same endpoint as `/users/:id`, and the
+      # optional format segment appears on every Rails route — carrying it would
+      # add noise to every operation name in the feed.
+      def normalize_pattern(pattern)
+        pattern.sub(/\(\.:format\)\z/, '')
+      end
+    end
+  end
+end

data/lib/sixty/instrumented.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require_relative 'tracer'
+require_relative 'stack'
+
+module Sixty
+  # Your own code, measured.
+  #
+  #   class OrdersQuery
+  #     include Sixty::Instrumented
+  #
+  #     def for_user(id) = Order.where(user_id: id).limit(30).to_a
+  #     def enrich(orders) = ...
+  #   end
+  #
+  # Every public instance method defined after the include becomes an operation:
+  # its own latency, its self time, and — the number that matters — how many
+  # queries and how many rows it is responsible for, including everything it
+  # calls.
+  #
+  # ── Why this is opt-in ────────────────────────────────────────────────────
+  #
+  # The Node agent wraps functions with a build transform, which can afford to
+  # instrument everything because it happens once at build time. Ruby has no
+  # build step: the equivalent would be walking ObjectSpace at boot and
+  # prepending a module to every class in `app/`, which is both slow and a
+  # decision nobody asked us to make on their behalf — including on classes
+  # whose methods are called in a tight loop, where a span per call is real
+  # overhead for no signal.
+  #
+  # So this is a line the application writes on the classes worth measuring:
+  # services, query objects, jobs. Controllers and queries are covered
+  # automatically by the railtie, which is enough for the feed to be useful
+  # before anybody adds a single include.
+  #
+  # ── What it costs when the agent is off ───────────────────────────────────
+  #
+  # One method call. `Sixty.trace` checks a boolean and yields, so an
+  # uninitialized agent — every test suite, every rake task, every developer's
+  # console — adds a frame and nothing else.
+  module Instrumented
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.sixty_install_wrapper!
+    end
+
+    module ClassMethods
+      def sixty_install_wrapper!
+        Sixty::Instrumented.wrapper_for(self)
+      end
+
+      def method_added(name)
+        super
+        Sixty::Instrumented.wrap(self, name) unless name.to_s.start_with?('sixty_')
+      end
+
+      # ── Why visibility has to be followed, not just read ──────────────────
+      #
+      # `def helper; end` followed by `private :helper` is the common spelling,
+      # and at `method_added` time the method is still public — so it gets
+      # wrapped. The wrapper lives in a prepended module, where `private` on the
+      # class does not reach it, and the result is a method the author made
+      # private that this gem quietly made public again. That is not a
+      # measurement problem; it is a change to the application's API.
+      #
+      # So the declarations are followed. A method turned private loses its
+      # wrapper entirely rather than becoming a private wrapper: private methods
+      # are not instrumented when they are declared private up front, and the
+      # two spellings should not disagree.
+      def private(*names)
+        result = super
+        Sixty::Instrumented.unwrap(self, names.flatten)
+        result
+      end
+
+      def protected(*names)
+        result = super
+        Sixty::Instrumented.revisibility(self, :protected, names.flatten)
+        result
+      end
+
+      def public(*names)
+        result = super
+        Sixty::Instrumented.revisibility(self, :public, names.flatten)
+        result
+      end
+
+      # Opt a class method in too. Rarely what you want — a class method is
+      # usually a constructor or a lookup — but a `Service.call` entry point is
+      # common enough to be worth the two lines.
+      def sixty_trace_singleton(*names)
+        names.each { |name| Sixty::Instrumented.wrap_singleton(self, name) }
+      end
+    end
+
+    class << self
+      # The wrapping lives in a module prepended to the class rather than in an
+      # alias chain: `super` then reaches the original definition, subclasses
+      # and `prepend`ed concerns keep working, and removing the include removes
+      # the instrumentation completely.
+      def wrapper_for(klass)
+        if klass.instance_variable_defined?(:@sixty_wrapper)
+          klass.instance_variable_get(:@sixty_wrapper)
+        else
+          wrapper = Module.new
+          klass.instance_variable_set(:@sixty_wrapper, wrapper)
+          klass.prepend(wrapper)
+          wrapper
+        end
+      end
+
+      # Wrap one instance method of `klass`.
+      def wrap(klass, name)
+        return unless klass.public_method_defined?(name) || klass.protected_method_defined?(name)
+        # An accessor is not an operation. `attr_reader :total` reports a span
+        # per read of an instance variable — pure overhead, and it buries the
+        # methods that do something in a list of the ones that do not.
+        return if name.to_s.end_with?('=')
+
+        original = klass.instance_method(name)
+        return if original.source_location.nil?
+
+        operation = "#{klass.name || 'anonymous'}##{name}"
+        attrs = location_attrs(original)
+        wrapper = wrapper_for(klass)
+        return if wrapper.method_defined?(name)
+
+        wrapper.send(:define_method, name) do |*args, &block|
+          Sixty.trace(operation, attrs: attrs.dup) { super(*args, &block) }
+        end
+        # Keyword arguments survive the splat only if the wrapper is marked:
+        # without this, `save(validate: false)` arrives at the original method
+        # as a positional Hash on Ruby 3, which is a behaviour change an
+        # observability gem has no business introducing.
+        wrapper.send(:ruby2_keywords, name)
+      end
+
+      # Drop the wrapper for methods that turned out to be private.
+      def unwrap(klass, names)
+        wrapper = existing_wrapper(klass)
+        return unless wrapper
+
+        names.each do |name|
+          wrapper.send(:remove_method, name) if wrapper.method_defined?(name)
+        end
+      end
+
+      def revisibility(klass, visibility, names)
+        wrapper = existing_wrapper(klass)
+        return unless wrapper
+
+        names.each do |name|
+          wrapper.send(visibility, name) if wrapper.method_defined?(name)
+        end
+      end
+
+      def wrap_singleton(klass, name)
+        return unless klass.singleton_class.method_defined?(name)
+
+        original = klass.singleton_class.instance_method(name)
+        operation = "#{klass.name || 'anonymous'}.#{name}"
+        attrs = location_attrs(original)
+        wrapper = Module.new do
+          define_method(name) do |*args, &block|
+            Sixty.trace(operation, attrs: attrs.dup) { super(*args, &block) }
+          end
+          ruby2_keywords name
+        end
+        klass.singleton_class.prepend(wrapper)
+      end
+
+      private
+
+      def existing_wrapper(klass)
+        klass.instance_variable_defined?(:@sixty_wrapper) &&
+          klass.instance_variable_get(:@sixty_wrapper)
+      end
+
+      # The file and line the method is written at, captured once at definition
+      # time. This is what turns a finding into a link into the repository, and
+      # it is free here — `source_location` is metadata Ruby already holds.
+      def location_attrs(method)
+        file, line = method.source_location
+        return {} unless file
+
+        { file: Stack.relativise(file), line: line }
+      end
+    end
+  end
+
+  class << self
+    # Instrument methods on a class you do not own — a gem's client, a model
+    # generated elsewhere, anything you cannot add an `include` to.
+    #
+    #   Sixty.instrument(Stripe::Charge, :create)
+    # Only the named methods are wrapped, and no `method_added` hook is
+    # installed: a class you do not own may define methods long after this call
+    # — lazily, or through a gem's own metaprogramming — and silently
+    # instrumenting those is not something a one-line call should decide.
+    def instrument(klass, *names)
+      names.each { |name| Instrumented.wrap(klass, name) }
+    end
+  end
+end