sixty 0.1.0

data/lib/sixty/tracer.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Sixty
+  # Span lifecycle and context propagation.
+  #
+  # The important property, and it is the same one the Node agent has: EVERY
+  # call is measured, but only a few are *transmitted* as traces. Spans are
+  # cheap objects that feed a local aggregator; full span trees are serialized
+  # only for sampled traces, errors and latency outliers. That is what keeps
+  # both agent overhead and ingest cost proportional to cardinality rather than
+  # to traffic.
+  #
+  # Attribution rules, which are the whole reason this file exists:
+  #   self time — duration minus the sum of direct children. "Did MY code get
+  #               slower, or did something I called get slower?"
+  #   db calls  — every descendant db span, credited to every ancestor. A method
+  #               going from 3 to 47 queries is an N+1 being born, and it has to
+  #               be visible on the method, not only on the query.
+  #   rows      — the same transitive credit. This is the 30 -> 30,000 signal.
+  #
+  # ── How "the current span" is tracked ─────────────────────────────────────
+  #
+  # `Thread.current[]` is fiber-local storage, which is the closest thing Ruby
+  # has to Node's AsyncLocalStorage. Under Puma, Unicorn and Sidekiq — a thread
+  # or a process per unit of work — it is exactly right. Under a fiber
+  # scheduler (Falcon, async gem) each fiber starts with an empty context
+  # instead of inheriting its parent's, so a query issued inside a spawned fiber
+  # is recorded with correct timings but no parent. The counts stay right; the
+  # edge is lost. That trade is stated here rather than discovered later, and it
+  # is the same shape of limitation core's synchronous context has in browsers.
+  module Tracer
+    KIND_HTTP = 'http'
+    KIND_FUNCTION = 'function'
+    KIND_DB = 'db'
+
+    # A single pathological request — the N+1 this product exists to catch — can
+    # emit tens of thousands of spans. Aggregates must still count every one of
+    # them, but the retained tree is capped so one bad request cannot exhaust
+    # memory.
+    MAX_SPANS_PER_TRACE = 500
+
+    KEY = :sixty_span
+
+    # A plain class rather than a keyword-initialized Struct, and that is a
+    # measured decision: this object is allocated on every instrumented call in
+    # the application, and building it from a keyword hash costs several
+    # microseconds per span — enough to show up in a benchmark of a method that
+    # does nothing. Assigning ivars directly is the cheapest thing Ruby offers.
+    class Span
+      attr_accessor :id, :trace_id, :parent_id, :parent, :kind, :name, :attrs,
+                    :start, :start_wall, :duration, :child_duration, :db_calls,
+                    :db_rows, :error, :depth, :children, :root, :span_count,
+                    :truncated, :recording
+
+      def initialize(kind, name, attrs, parent)
+        @kind = kind
+        @name = name
+        @attrs = attrs
+        @parent = parent
+        @duration = nil
+        @child_duration = 0.0
+        @db_calls = 0
+        @db_rows = 0
+        @error = nil
+        @children = []
+        @span_count = 0
+        @truncated = false
+        @recording = false
+      end
+    end
+
+    class << self
+      attr_accessor :sink
+
+      def current
+        Thread.current[KEY]
+      end
+
+      def current=(span)
+        Thread.current[KEY] = span
+      end
+
+      def start_span(kind:, name:, attrs: nil)
+        parent = current
+        span = Span.new(kind, name, attrs || {}, parent)
+        span.id = next_id
+        span.start = monotonic_ms
+
+        if parent
+          span.trace_id = parent.trace_id
+          span.parent_id = parent.id
+          span.depth = parent.depth + 1
+          span.root = parent.root
+        else
+          # Only a root pays for entropy and for a wall clock. Child spans are
+          # never looked up by time or id outside the tree they belong to, and
+          # this runs on every instrumented call in the application.
+          span.trace_id = SecureRandom.hex(16)
+          span.parent_id = nil
+          span.depth = 0
+          span.root = span
+          span.start_wall = (Time.now.to_f * 1000).round
+        end
+
+        # Children are always collected: whether a trace is worth keeping is
+        # only knowable once it finishes (did it raise? was it slow?), and a
+        # tree cannot be rebuilt retroactively.
+        root = span.root
+        root.span_count += 1
+        root.truncated = true if root.span_count > MAX_SPANS_PER_TRACE
+        span
+      end
+
+      def end_span(span, error = nil, duration: nil)
+        return span if span.duration # already ended; guard double-finish
+
+        span.duration = duration || (monotonic_ms - span.start)
+        if error
+          span.error = {
+            # Class name and message only. A backtrace can contain file paths
+            # and interpolated values; we take the message but never the args.
+            type: error.class.name.to_s[0, 200],
+            message: error.message.to_s[0, 500]
+          }
+        end
+
+        parent = span.parent
+        if parent
+          parent.child_duration += span.duration
+          parent.children << span unless span.root.truncated
+        end
+
+        # Credit db work to every ancestor, not only the immediate parent.
+        if span.kind == KIND_DB
+          rows = span.attrs[:rows].is_a?(Numeric) ? span.attrs[:rows] : 0
+          ancestor = span.parent
+          while ancestor
+            ancestor.db_calls += 1
+            ancestor.db_rows += rows
+            ancestor = ancestor.parent
+          end
+        end
+
+        span
+      end
+
+      def self_time(span)
+        [0.0, span.duration.to_f - span.child_duration.to_f].max
+      end
+
+      # Run a block with `span` as the active context, ending and emitting it
+      # however the block leaves — returned value, raised error, or `throw`.
+      def in_span(span)
+        previous = current
+        self.current = span
+        begin
+          result = yield
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          # Exception, not StandardError: a Timeout::Error or an Interrupt still
+          # ended this span, and losing the measurement is the smaller problem
+          # than leaving the context pointing at a span that never closed.
+          self.current = previous
+          end_span(span, e)
+          emit(span)
+          raise
+        end
+        self.current = previous
+        end_span(span)
+        emit(span)
+        result
+      end
+
+      # Record a span that has already happened.
+      #
+      # ActiveSupport::Notifications hands an event to its subscriber *after*
+      # the work finished, with its own start and finish times — so there is
+      # nothing to run a block around. The span is assembled with those times
+      # and parented to whatever is current, which is correct because the
+      # subscriber runs synchronously on the same thread as the query it
+      # describes.
+      def record(kind:, name:, duration_ms:, attrs: {}, start_wall: nil, error: nil)
+        span = start_span(kind: kind, name: name, attrs: attrs)
+        span.start_wall = start_wall if start_wall
+        end_span(span, error, duration: duration_ms)
+        emit(span)
+        span
+      end
+
+      # Handing a span to the sink can never fail the code being measured.
+      #
+      # This runs inside somebody's request path — between their query returning
+      # and their controller resuming — so a raise here does not lose a
+      # measurement, it fails their request. `Sixty.on_span_end` rescues and
+      # warns, which is where an agent bug should be noticed; this is the floor
+      # underneath that, for a sink installed by anything else. Losing one span
+      # is recoverable and invisible. Breaking the host application is neither.
+      def emit(span)
+        handler = @sink
+        handler&.call(span)
+      rescue StandardError
+        nil
+      end
+
+      def monotonic_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000.0
+      end
+
+      private
+
+      # A counter, not entropy. A span id only has to be unique inside the trace
+      # it belongs to — the trace id carries the randomness — and this is called
+      # on every instrumented call, where a call into the CSPRNG would be the
+      # single most expensive thing about tracing a method that does nothing.
+      def next_id
+        @seq = (@seq || 0) + 1
+        @seq.to_s(36)
+      end
+    end
+  end
+end

data/lib/sixty/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Sixty
+  VERSION = '0.1.0'
+end

data/lib/sixty.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require_relative 'sixty/version'
+require_relative 'sixty/config'
+require_relative 'sixty/sketch'
+require_relative 'sixty/sql'
+require_relative 'sixty/stack'
+require_relative 'sixty/plans'
+require_relative 'sixty/tracer'
+require_relative 'sixty/aggregator'
+require_relative 'sixty/exporter'
+require_relative 'sixty/shape'
+require_relative 'sixty/instrumented'
+
+# sixty — zero-configuration performance drift detection, for Ruby.
+#
+#   require 'sixty'
+#   Sixty.init   # reads SIXTY_API_KEY, SIXTY_SERVICE, SIXTY_RELEASE from ENV
+#
+# In a Rails application the railtie calls this for you and installs the Rack
+# middleware, the ActiveRecord subscriber and the controller instrumentation, so
+# the only line an application needs is the gem in its Gemfile.
+#
+# What it reports is deliberately not latency alone. It is *shape*: how many
+# rows a query returned, how many queries a method issued, how much of a
+# request was spent in your own code rather than below it. Those are the numbers
+# that barely move on a warm development database and take production down a
+# week later.
+module Sixty
+  class << self
+    attr_reader :config, :aggregator, :exporter
+
+    def init(options = {})
+      return @state if @state
+
+      config = Config.new(options)
+      @config = config
+
+      unless config.active?
+        config.on_warn.call(
+          'sixty: no API key found (set SIXTY_API_KEY or pass api_key:). Agent is inactive.'
+        )
+        return nil
+      end
+
+      Stack.root = rails_root || Dir.pwd
+
+      @aggregator = Aggregator.new(on_warn: config.on_warn)
+      @exporter = Exporter.new(
+        endpoint: config.endpoint,
+        api_key: config.api_key,
+        service: config.service,
+        environment: config.environment,
+        release: config.release,
+        repo_url: config.repo_url,
+        on_warn: config.on_warn
+      )
+
+      Tracer.sink = method(:on_span_end)
+      @enabled = true
+      @flush_hooks = []
+      start_flusher
+
+      install_database_instrumentation(config)
+      # Retried on every flush, because a driver is a constant that may not
+      # exist yet. `Sixty.init` in a Sinatra app can easily run before
+      # `require 'mysql2'`, and an agent that decided once at boot would report
+      # no queries at all for the rest of the process — silently, which is the
+      # failure this project refuses. Every installer is idempotent, so the
+      # retry costs a few `defined?` checks a minute.
+      before_flush { install_database_instrumentation(config) }
+
+      # Rack and ActionController install themselves through the railtie when
+      # Rails is present. A plain Rack or Sinatra app calls
+      # Sixty::Instrument::Rack directly, which is why neither is here.
+      #
+      # The last window is worth one short attempt and no more. A process being
+      # asked to stop is often a deploy waiting on it, and an agent that can add
+      # ten seconds to every shutdown because a collector is unreachable is an
+      # agent that will be removed — correctly.
+      at_exit { flush(timeout: 2) }
+
+      @state = { config: config, aggregator: @aggregator, exporter: @exporter }
+      if config.debug
+        config.on_warn.call(
+          "sixty: active — service=#{config.service} env=#{config.environment} " \
+          "release=#{config.release.empty? ? '(none)' : config.release} " \
+          "endpoint=#{config.endpoint}"
+        )
+      end
+      @state
+    end
+
+    def enabled?
+      @enabled == true
+    end
+
+    # Measure a block as one operation.
+    #
+    # The escape hatch for code the automatic instrumentation cannot see, and
+    # the building block `Sixty::Instrumented` uses. `name` is an identity that
+    # will be compared across releases, so it must not contain anything that
+    # varies per call — an id in a name mints an operation per id and blows the
+    # cardinality cap.
+    def trace(name, kind: Tracer::KIND_FUNCTION, attrs: nil)
+      return yield unless enabled?
+
+      span = Tracer.start_span(kind: kind, name: name, attrs: attrs)
+      Tracer.in_span(span) { yield }
+    end
+
+    # Record a value observed inside the current operation — e.g. the size of a
+    # result the caller cares about. Attaches to the active span.
+    def annotate(key, value)
+      span = Tracer.current
+      span.attrs[key] = value if span
+    end
+
+    # Upgrade the current request's span to a framework-supplied route pattern.
+    # A real route always beats the path heuristic: without it every
+    # /users/42 is its own operation.
+    def set_route(route)
+      span = Tracer.current
+      return unless span && route.is_a?(String) && !route.empty?
+
+      root = span.root
+      return unless root && root.kind == Tracer::KIND_HTTP
+
+      root.name = "#{root.attrs[:method]} #{route}"
+    end
+
+    # Called on every completed span. Everything downstream of here is the
+    # agent's own work, so it is wrapped: an agent bug must never surface as an
+    # application error.
+    def on_span_end(span)
+      ensure_flusher
+      aggregator.record(span)
+      keep_exemplar(span)
+    rescue StandardError => e
+      config.on_warn.call("sixty: internal error recording span: #{e.message}")
+    end
+
+    # Flush now, from whatever thread asks. Used by the interval thread, by
+    # at_exit, and by tests that cannot wait fifteen seconds.
+    def flush(timeout: Exporter::TIMEOUT_SECONDS)
+      return unless enabled?
+
+      run_flush_hooks
+      exporter.flush(aggregator.drain, timeout: timeout)
+    rescue StandardError => e
+      config&.on_warn&.call("sixty: flush failed: #{e.message}")
+    end
+
+    # Work that should happen on the agent's thread, just before a flush.
+    #
+    # The ActiveRecord instrumentation registers the EXPLAIN pass here: it needs
+    # a database connection and must never run on the request path, and this is
+    # the one thread in the process that satisfies both.
+    def before_flush(&block)
+      (@flush_hooks ||= []) << block
+    end
+
+    # Test seam. Forgets everything and stops the flush thread.
+    def reset!
+      @flusher&.kill
+      @flusher = nil
+      @state = nil
+      @enabled = false
+      @flush_hooks = []
+      Tracer.sink = nil
+      Tracer.current = nil
+      Stack.reset!
+      Plans.reset!
+    end
+
+    private
+
+    # Which database clients to measure, and — the part that matters — which
+    # ones not to.
+    #
+    # ── Why ActiveRecord excludes the raw drivers ─────────────────────────────
+    #
+    # `sql.active_record` and a patched `PG::Connection` see the *same query*:
+    # the adapter runs it through the driver. Installing both would count every
+    # query in a Rails app twice, and a doubled `db_calls` is not a visible
+    # error — it is a plausible-looking number that makes every fanout finding
+    # wrong by a factor of two.
+    #
+    # So the notification subscriber wins wherever ActiveRecord exists, because
+    # it is public API, knows the dialect, and reports the row count the adapter
+    # already has. The driver patches are for everything else — Sinatra, Sequel,
+    # ROM, a worker, a script — and they are chosen by whether the ORM is in the
+    # process at all, not by whether it happens to be loaded yet, so the answer
+    # cannot change halfway through boot.
+    #
+    # `config.instrument` overrides all of it: an application that really does
+    # issue queries outside ActiveRecord can ask for both and accept the
+    # double count on the queries that go through the adapter.
+    def install_database_instrumentation(config)
+      require_relative 'sixty/instrument/active_record'
+      require_relative 'sixty/instrument/pg'
+      require_relative 'sixty/instrument/mysql'
+      require_relative 'sixty/instrument/mongo'
+
+      wanted = config.instrument
+      active_record = defined?(::ActiveRecord)
+
+      if wanted.nil? ? active_record : wanted.include?(:active_record)
+        # In a Rails app the railtie installs this on `active_record` load
+        # instead, because referencing ActiveRecord::Base here would eagerly
+        # load the ORM — and open a connection — in processes that never needed
+        # one. This covers Sinatra and friends, where nothing else will.
+        Instrument::ActiveRecord.install(config) if defined?(::ActiveRecord::Base)
+      end
+
+      raw_drivers = wanted.nil? ? !active_record : true
+      if raw_drivers
+        Instrument::Pg.install(config) if wanted.nil? || wanted.include?(:pg)
+        Instrument::Mysql.install(config) if wanted.nil? || wanted.include?(:mysql)
+      end
+
+      # Mongo is never a double count: no ORM in this list speaks to it, and
+      # Mongoid drives the very same driver the subscription is attached to.
+      Instrument::Mongo.install(config) if wanted.nil? || wanted.include?(:mongo)
+    rescue StandardError => e
+      config.on_warn.call("sixty: could not install database instrumentation: #{e.message}")
+    end
+
+    def rails_root
+      return nil unless defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+
+      ::Rails.root.to_s
+    end
+
+    # Keep the full span tree when it is worth keeping. Aggregates already cover
+    # "what happened"; exemplars exist to answer "show me one".
+    def keep_exemplar(span)
+      return if span.parent # only complete traces
+
+      is_error = !span.error.nil?
+      is_slow = span.duration.to_f > config.slow_trace_ms
+      return unless span.recording || is_error || is_slow
+
+      exporter.queue_exemplar(
+        traceId: span.trace_id,
+        startedAt: span.start_wall,
+        durationMs: span.duration,
+        isError: is_error,
+        reason: is_error ? 'error' : (is_slow ? 'slow' : 'sampled'),
+        rootKey: Aggregator.span_key(span),
+        spans: flatten(span)
+      )
+    end
+
+    def flatten(span, out = [], parent_id = nil)
+      out << {
+        id: span.id,
+        parentId: parent_id,
+        kind: span.kind,
+        name: span.name,
+        durationMs: round(span.duration),
+        selfMs: round(Tracer.self_time(span)),
+        dbCalls: span.db_calls,
+        dbRows: span.db_rows,
+        # camelCased on the way out because the collector, the web app and the
+        # MCP server all read the JavaScript agent's spelling — one wire format,
+        # whatever language wrote it.
+        attrs: exported_attrs(span.attrs),
+        error: span.error
+      }
+      span.children.each { |child| flatten(child, out, span.id) }
+      out
+    end
+
+    ATTR_NAMES = {
+      normalized_sql: :normalizedSql, rows: :rows, fields: :fields, bytes: :bytes,
+      status: :status, method: :method, file: :file, line: :line, host: :host,
+      round_trips: :roundTrips,
+      direction: :direction, frames: :frames, cached: :cached
+    }.freeze
+
+    def exported_attrs(attrs)
+      attrs.each_with_object({}) do |(key, value), out|
+        name = ATTR_NAMES[key]
+        out[name] = value if name
+      end
+    end
+
+    def round(value)
+      (value.to_f * 1000).round / 1000.0
+    end
+
+    def start_flusher
+      @flush_pid = Process.pid
+      @flusher = Thread.new do
+        loop do
+          sleep config.flush_interval
+          flush
+        end
+      end
+      # Not joined at exit, and deliberately so: a background thread that keeps
+      # a process alive to finish reporting is an agent that has decided its
+      # telemetry matters more than the operator's shutdown. The at_exit flush
+      # is what catches the last window.
+      @flusher.abort_on_exception = false
+      @flusher.name = 'sixty-flush' if @flusher.respond_to?(:name=)
+    end
+
+    # Puma and Unicorn fork worker processes after boot, and a thread does not
+    # survive a fork — so a gem initialized in the parent has a dead flusher in
+    # every child, which reports nothing and says nothing about it. This is
+    # checked on the cheapest thing available (an integer compare) on the span
+    # path, because there is no portable hook that fires in every forking server.
+    def ensure_flusher
+      return if @flush_pid == Process.pid
+
+      start_flusher
+    end
+
+    def run_flush_hooks
+      (@flush_hooks || []).each do |hook|
+        hook.call
+      rescue StandardError => e
+        config.on_warn.call("sixty: flush hook failed: #{e.message}")
+      end
+    end
+  end
+end
+
+require_relative 'sixty/railtie' if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: sixty
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- sixty
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  Measures what your application normally does — per method, per query — and
+  reports the shape of it: rows returned, queries issued, time spent in your
+  own code. The collector compares one release against the next and surfaces
+  what a deploy changed.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/sixty.rb
+- lib/sixty/aggregator.rb
+- lib/sixty/config.rb
+- lib/sixty/exporter.rb
+- lib/sixty/instrument/action_controller.rb
+- lib/sixty/instrument/active_record.rb
+- lib/sixty/instrument/mongo.rb
+- lib/sixty/instrument/mysql.rb
+- lib/sixty/instrument/pg.rb
+- lib/sixty/instrument/rack.rb
+- lib/sixty/instrumented.rb
+- lib/sixty/plans.rb
+- lib/sixty/railtie.rb
+- lib/sixty/shape.rb
+- lib/sixty/sketch.rb
+- lib/sixty/sql.rb
+- lib/sixty/stack.rb
+- lib/sixty/tracer.rb
+- lib/sixty/version.rb
+homepage: https://github.com/andana-to/drift
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/andana-to/drift
+  source_code_uri: https://github.com/andana-to/drift/tree/main/packages/ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Zero-config performance drift detection for Ruby and Rails services
+test_files: []