metrixwire 0.2.3

data/lib/metrixwire/instrument/redis.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  module Instrument
+    # Best-effort patch of the `redis` gem → cache custom spans. The redis gem
+    # funnels commands through the client's `call`/`call_v`, so we time those and
+    # tag them meta.kind='cache' with `hit` known for GET-style reads. Guarded:
+    # skips silently if the gem/const isn't present.
+    module Redis
+      READS = %w[get mget hget hmget hgetall exists].freeze
+
+      module_function
+
+      def install
+        target = redis_client_class
+        return if target.nil?
+        return if target.instance_variable_get(:@__metrixwire_patched)
+
+        target.prepend(Patch)
+        target.instance_variable_set(:@__metrixwire_patched, true)
+      rescue StandardError
+        nil
+      end
+
+      # redis-rb >= 5 uses RedisClient; older versions ship Redis::Client.
+      def redis_client_class
+        if defined?(::RedisClient) && ::RedisClient.method_defined?(:call)
+          ::RedisClient
+        elsif defined?(::Redis::Client) && ::Redis::Client.method_defined?(:call)
+          ::Redis::Client
+        end
+      rescue StandardError
+        nil
+      end
+
+      module Patch
+        def call(command, *rest, &blk)
+          return super if Context.current.nil?
+
+          op = MetrixWire::Instrument::Redis.command_name(command)
+          t0 = MetrixWire.monotonic_ms
+          result = super
+          MetrixWire::Instrument::Redis.record(op, MetrixWire.monotonic_ms - t0, result)
+          result
+        rescue StandardError
+          super
+        end
+      end
+
+      def command_name(command)
+        c = command.is_a?(Array) ? command.first : command
+        c.to_s.downcase
+      rescue StandardError
+        "cmd"
+      end
+
+      def record(op, duration_ms, result)
+        meta = { kind: "cache", op: op }
+        meta[:hit] = !result.nil? if READS.include?(op)
+        Helpers.add_span("custom", "cache #{op}", duration_ms, meta: meta, source_location: nil)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/metrixwire/instrument/source_location.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  module Instrument
+    # Finds the nearest application caller frame (file.rb:42) for a span, so the
+    # dashboard can point at the line that issued a query / HTTP call. Skips the
+    # SDK's own frames and common vendor/stdlib paths. Best-effort — returns nil
+    # rather than throwing.
+    module SourceLocation
+      SKIP = %r{/metrixwire/|/gems/|/ruby/\d|/lib/ruby/|<internal:}.freeze
+
+      module_function
+
+      def nearest
+        return nil unless MetrixWire.capture_source?
+
+        caller_locations(2, 40)&.each do |loc|
+          path = loc.absolute_path || loc.path
+          next if path.nil?
+          next if SKIP.match?(path)
+
+          return "#{File.basename(path)}:#{loc.lineno}"
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/metrixwire/instrument/sqlite3.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  module Instrument
+    # Best-effort patch of the `sqlite3` gem (SQLite3::Database#execute).
+    # Guarded: skips silently if the gem isn't loaded.
+    module Sqlite3
+      module_function
+
+      def install
+        return unless defined?(::SQLite3::Database)
+        return if ::SQLite3::Database.instance_variable_get(:@__metrixwire_patched)
+
+        ::SQLite3::Database.prepend(Patch)
+        ::SQLite3::Database.instance_variable_set(:@__metrixwire_patched, true)
+      rescue StandardError
+        nil
+      end
+
+      module Patch
+        def execute(*args, &blk)
+          sql = args.first
+          return super(*args, &blk) if Context.current.nil? || !sql.is_a?(String)
+
+          t0 = MetrixWire.monotonic_ms
+          result = super(*args, &blk)
+          unless MetrixWire::Instrument::Pg.control_statement?(sql)
+            Helpers.add_span("db_query", sql, MetrixWire.monotonic_ms - t0,
+                             meta: Helpers.row_count_meta(result))
+          end
+          result
+        rescue StandardError
+          super(*args, &blk)
+        end
+      end
+    end
+  end
+end

data/lib/metrixwire/rack.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  # Rack middleware — opens exactly one trace per incoming request, runs the app
+  # inside that trace's context, and enqueues the finished trace. Works for
+  # Sinatra, bare Rack, Rails (inserted via the Railtie) and anything else Rack.
+  #
+  # It is intentionally defensive at every step: a failure in instrumentation
+  # must never change the response the app returns.
+  class Rack
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      return @app.call(env) unless MetrixWire.enabled?
+
+      method = env["REQUEST_METHOD"] || "GET"
+      route = "#{method} #{derive_path(env)}"
+      trace = Trace.new(route: route, method: method)
+      start_heap = MetrixWire.rss_kb
+
+      status, headers, body = nil
+      Context.with(trace) do
+        begin
+          status, headers, body = @app.call(env)
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          trace.capture_exception(e)
+          finish(trace, 500, nil, start_heap)
+          raise
+        end
+
+        # Refine the route from the framework's matched pattern if available
+        # (Sinatra exposes sinatra.route; Rails sets it via notifications).
+        refine_route(trace, env)
+        finish(trace, status, headers, start_heap)
+      end
+
+      [status, headers, body]
+    rescue Exception # rubocop:disable Lint/RescueException
+      # If we've already opened a trace it was handled above; re-raise so the
+      # host app's own error handling runs unchanged.
+      raise
+    end
+
+    private
+
+    def finish(trace, status, headers, start_heap)
+      code = status.to_i
+      trace.status = "error" if code >= 500
+      trace.finalize_duration!
+
+      mem = MetrixWire.memory_delta_mb(start_heap)
+      trace.set_meta(:memoryMb, mem) if mem && mem > 0
+
+      bytes = response_bytes(headers)
+      trace.set_meta(:responseBytes, bytes) if bytes && bytes > 0
+
+      MetrixWire.enqueue(trace)
+    rescue StandardError
+      # never let instrumentation break the response
+    end
+
+    def derive_path(env)
+      path = env["PATH_INFO"]
+      path = "/" if path.nil? || path.empty?
+      path
+    rescue StandardError
+      "/"
+    end
+
+    # Prefer a matched route pattern (stable across ids) over the raw path.
+    def refine_route(trace, env)
+      matched = env["sinatra.route"] # e.g. "GET /users/:id"
+      trace.route = matched if matched.is_a?(String) && !matched.empty?
+    rescue StandardError
+      nil
+    end
+
+    def response_bytes(headers)
+      return nil unless headers
+
+      len = headers["Content-Length"] || headers["content-length"]
+      len ? len.to_i : nil
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/metrixwire/railtie.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  # Rails integration. Loaded automatically when the gem is required inside a
+  # Rails app (Rails::Railtie is defined). It:
+  #   (a) auto-inits the SDK from ENV before initializers run,
+  #   (b) inserts the Rack middleware so one trace opens per request,
+  #   (c) wires ActiveSupport::Notifications subscribers (SQL, controller, cache).
+  # Fully automatic: add the gem + set METRIXWIRE_KEY — no code changes.
+  class Railtie < ::Rails::Railtie
+    # Init as early as possible so subscribers are attached before requests flow.
+    config.before_configuration do
+      MetrixWire.init unless MetrixWire.initialized?
+    end
+
+    # Insert the Rack middleware at the top of the stack (one trace per request).
+    initializer "metrixwire.middleware", before: :load_config_initializers do |app|
+      if MetrixWire.enabled?
+        begin
+          app.config.app_middleware.use MetrixWire::Rack
+        rescue StandardError
+          nil
+        end
+      end
+    end
+
+    # Attach the notification subscribers once the app has finished booting.
+    config.after_initialize do
+      if MetrixWire.enabled?
+        begin
+          MetrixWire::Instrument::ActiveSupportSubscriber.install
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/metrixwire/span.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  # A single unit of work within a trace (db_query | http_call | custom).
+  # Users never build these by hand — instrumentation creates them.
+  class Span
+    attr_reader :type, :description, :started_at, :duration_ms, :source_location, :meta
+
+    # @param type [String] "db_query" | "http_call" | "custom"
+    # @param started_at [String] ISO8601
+    # @param meta [Hash, nil] optional signal (e.g. { rowCount: }, { statusCode: })
+    def initialize(type:, description:, started_at:, duration_ms:, source_location: nil, meta: nil)
+      @type = type
+      @description = description
+      @started_at = started_at
+      @duration_ms = duration_ms
+      @source_location = source_location
+      @meta = meta
+    end
+
+    def to_h
+      out = {
+        type: @type,
+        description: @description,
+        startedAt: @started_at,
+        durationMs: @duration_ms
+      }
+      out[:sourceLocation] = @source_location if @source_location
+      out[:meta] = @meta if @meta && !@meta.empty?
+      out
+    end
+  end
+end

data/lib/metrixwire/trace.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "time"
+
+module MetrixWire
+  # One request / unit of work. Holds its spans and trace-level meta. Serialized
+  # to the exact ingest wire shape. Nothing here is part of the public API.
+  class Trace
+    attr_accessor :route, :method, :status, :meta
+    attr_reader :spans, :started_mono, :started_at
+
+    # @param started_mono [Float] monotonic clock at open (for duration)
+    def initialize(route:, method:, started_at: nil, started_mono: nil)
+      @route = route
+      @method = method
+      @started_mono = started_mono || MetrixWire.monotonic_ms
+      @started_at = started_at || MetrixWire.iso8601(Time.now)
+      @status = "success"
+      @spans = []
+      @meta = {}
+      @duration_ms = nil
+    end
+
+    def add_span(span)
+      @spans << span
+    end
+
+    def set_meta(key, value)
+      @meta[key] = value
+    end
+
+    # Attach an exception to this trace and flag it as an error. Never throws.
+    def capture_exception(err)
+      @meta[:exception] = MetrixWire.exception_meta(err)
+      @status = "error"
+    rescue StandardError
+      # instrumentation must never throw
+    end
+
+    def duration_ms
+      @duration_ms ||= [(MetrixWire.monotonic_ms - @started_mono), 0].max.round
+    end
+
+    # Freeze the duration at the moment the trace closes.
+    def finalize_duration!
+      @duration_ms = [(MetrixWire.monotonic_ms - @started_mono), 0].max.round
+    end
+
+    def to_h
+      out = {
+        route: @route,
+        method: @method,
+        startedAt: @started_at,
+        durationMs: duration_ms,
+        status: @status,
+        spans: @spans.map(&:to_h)
+      }
+      out[:meta] = @meta if @meta && !@meta.empty?
+      out
+    end
+  end
+end

data/lib/metrixwire/transport.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "thread"
+require "uri"
+
+module MetrixWire
+  # Batches finished traces on an in-memory Queue and flushes them to the ingest
+  # endpoint from a background daemon Thread. Every network path is wrapped so a
+  # dead or slow MetrixWire API can never crash or block the host app: short
+  # timeout, all errors swallowed, sends happen off the request path. A final
+  # flush runs at_exit.
+  class Transport
+    def initialize(config)
+      @config = config
+      @queue = Queue.new
+      @buffer = []
+      @mutex = Mutex.new
+      @thread = nil
+      @stopping = false
+      @uri = safe_uri(config.endpoint)
+    end
+
+    def start
+      return unless @config.enabled
+      return if @thread&.alive?
+
+      @thread = Thread.new { run_loop }
+      @thread.name = "metrixwire-transport" if @thread.respond_to?(:name=)
+      @thread.abort_on_exception = false
+
+      # Last-chance flush on process exit.
+      at_exit { flush_sync }
+    rescue StandardError
+      # never let startup break the host app
+    end
+
+    # Enqueue a finished trace. Non-blocking. Flushes immediately once the batch
+    # threshold is reached.
+    def enqueue(trace)
+      return unless @config.enabled
+
+      @queue << trace
+      @signal_flush = true if @queue.size >= @config.max_batch
+    rescue StandardError
+      # swallow — monitoring must never break the app
+    end
+
+    # Synchronous flush of everything currently queued. Safe to call anytime.
+    def flush_sync
+      drain_queue
+      batch = nil
+      @mutex.synchronize do
+        return if @buffer.empty?
+
+        batch = @buffer.slice!(0, @buffer.length)
+      end
+      send_batch(batch) if batch && !batch.empty?
+    rescue StandardError
+      # swallow
+    end
+
+    private
+
+    def run_loop
+      interval = @config.flush_interval_ms / 1000.0
+      loop do
+        begin
+          sleep(interval)
+        rescue StandardError
+          nil
+        end
+        flush_sync
+      end
+    rescue StandardError
+      # thread must never die loudly; if it does, we simply stop flushing
+    end
+
+    def drain_queue
+      until @queue.empty?
+        item = begin
+          @queue.pop(true)
+        rescue ThreadError
+          break
+        end
+        @mutex.synchronize { @buffer << item }
+      end
+    rescue StandardError
+      nil
+    end
+
+    def send_batch(batch)
+      return if batch.nil? || batch.empty?
+      return if @config.api_key.to_s.empty? || @uri.nil?
+
+      body = JSON.generate(traces: batch.map { |t| t.is_a?(Hash) ? t : t.to_h })
+
+      timeout = @config.timeout_ms / 1000.0
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      http.use_ssl = (@uri.scheme == "https")
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+
+      req = Net::HTTP::Post.new(@uri.request_uri)
+      req["Content-Type"] = "application/json"
+      req["x-api-key"] = @config.api_key
+      req.body = body
+
+      http.start { |h| h.request(req) }
+    rescue StandardError
+      # Swallow everything — instrumentation must never throw into the app.
+    end
+
+    def safe_uri(endpoint)
+      URI.parse(endpoint)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/metrixwire/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  VERSION = "0.2.3"
+end

data/lib/metrixwire.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "time"
+require "securerandom"
+
+require_relative "metrixwire/version"
+require_relative "metrixwire/config"
+require_relative "metrixwire/span"
+require_relative "metrixwire/trace"
+require_relative "metrixwire/context"
+require_relative "metrixwire/transport"
+require_relative "metrixwire/rack"
+require_relative "metrixwire/instrument/source_location"
+require_relative "metrixwire/instrument/helpers"
+require_relative "metrixwire/instrument/pg"
+require_relative "metrixwire/instrument/mysql2"
+require_relative "metrixwire/instrument/sqlite3"
+require_relative "metrixwire/instrument/net_http"
+require_relative "metrixwire/instrument/redis"
+require_relative "metrixwire/instrument/rack_builder"
+require_relative "metrixwire/instrument/active_support"
+
+# Zero-config APM SDK for Ruby. Call {MetrixWire.init} once (or, in Rails, just
+# add the gem + set METRIXWIRE_KEY and it's fully automatic). Every HTTP request
+# becomes a trace and every DB query / outbound HTTP call / cache op within it
+# becomes a span. There is no manual span API and no middleware to wire up.
+#
+# Non-blocking: traces are batched on a background thread with a short send
+# timeout, and ALL transport errors are swallowed — instrumentation must never
+# throw into or block the host application.
+module MetrixWire
+  class << self
+    # Initialize the SDK. Args fall back to ENV: METRIXWIRE_KEY,
+    # METRIXWIRE_ENDPOINT, METRIXWIRE_ENABLED. Idempotent — a second call is a
+    # no-op. Auto-installs every instrumentation whose library is present.
+    def init(opts = {})
+      return if @config # already initialised
+
+      @config = Config.new(opts || {})
+      @transport = Transport.new(@config)
+
+      warn("[metrixwire] no apiKey provided — SDK disabled.") if @config.api_key.empty? && !opts_disabled?(opts)
+
+      if @config.enabled
+        @transport.start
+        install_all
+      end
+      nil
+    rescue StandardError => e
+      # init itself must never break the host app.
+      begin
+        warn("[metrixwire] init failed: #{e.message}")
+      rescue StandardError
+        nil
+      end
+      nil
+    end
+
+    def initialized?
+      !@config.nil?
+    end
+
+    def enabled?
+      @config ? @config.enabled : false
+    end
+
+    def capture_source?
+      @config ? @config.capture_source : true
+    end
+
+    def endpoint
+      @config ? @config.endpoint : nil
+    end
+
+    # Enqueue a finished trace for delivery. Internal — used by instrumentation.
+    def enqueue(trace)
+      @transport&.enqueue(trace)
+    end
+
+    # Manually flush the queue (e.g. before a short-lived process exits).
+    def flush
+      @transport&.flush_sync
+    end
+
+    # Escape hatch mirroring Node/PHP: attach an exception to the active trace
+    # for frameworks the SDK can't hook automatically. NOT a manual span API.
+    def capture_exception(err)
+      trace = Context.current
+      trace&.capture_exception(err)
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # ── shared utilities used across the SDK ──────────────────────────────────
+
+    # Monotonic milliseconds — safe for measuring durations (never goes back).
+    def monotonic_ms
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000.0
+    end
+
+    # ISO8601 UTC with millisecond precision, e.g. "2026-07-14T10:00:00.000Z".
+    def iso8601(time)
+      time.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+    rescue StandardError
+      Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+    end
+
+    # Build the ExceptionMeta hash from an arbitrary error. Keeps the top ~8
+    # backtrace frames — enough to fingerprint and guide a fix.
+    def exception_meta(err)
+      return nil if err.nil?
+
+      {
+        type: err.class.name.to_s,
+        message: err.respond_to?(:message) ? err.message.to_s : err.to_s,
+        stack: (err.respond_to?(:backtrace) && err.backtrace ? err.backtrace.first(8).join("\n") : nil)
+      }.compact
+    rescue StandardError
+      nil
+    end
+
+    # Current process RSS in KB (best-effort, portable-ish). Used to compute a
+    # per-request memory delta for the memory_spike detector.
+    def rss_kb
+      # Linux: read RSS pages straight from /proc (no fork, fast).
+      if File.readable?("/proc/self/statm")
+        status = File.read("/proc/self/statm")
+        pages = status.split[1].to_i
+        return pages * (page_size / 1024)
+      end
+      # macOS / BSD: shell out to ps (cheap, once per request boundary).
+      out = `ps -o rss= -p #{Process.pid} 2>/dev/null`.to_s.strip
+      out.empty? ? nil : out.to_i
+    rescue StandardError
+      nil
+    end
+
+    # Memory delta in MB since `start_kb`. Returns 0 when unavailable.
+    def memory_delta_mb(start_kb)
+      return 0 if start_kb.nil?
+
+      now = rss_kb
+      return 0 if now.nil?
+
+      ((now - start_kb) / 1024.0).round
+    rescue StandardError
+      0
+    end
+
+    private
+
+    def page_size
+      @page_size ||= (`getconf PAGESIZE 2>/dev/null`.to_s.strip.to_i.nonzero? || 4096)
+    rescue StandardError
+      4096
+    end
+
+    def opts_disabled?(opts)
+      opts.is_a?(Hash) && opts.key?(:enabled) && !opts[:enabled]
+    end
+
+    # Auto-detect and patch everything present. Each guarded internally so a
+    # missing library / const is skipped silently.
+    def install_all
+      Instrument::NetHttp.install
+      Instrument::Pg.install
+      Instrument::Mysql2.install
+      Instrument::Sqlite3.install
+      Instrument::Redis.install
+      # Non-Rails Rack apps (Sinatra / bare Rack) get the middleware auto-inserted.
+      Instrument::RackBuilder.install
+      # Rails path (if we were init'd manually inside Rails without the Railtie).
+      Instrument::ActiveSupportSubscriber.install if defined?(::ActiveSupport::Notifications)
+    rescue StandardError
+      nil
+    end
+  end
+end
+
+# Load the Railtie only inside a Rails app so Rails is fully automatic.
+if defined?(::Rails::Railtie)
+  begin
+    require_relative "metrixwire/railtie"
+  rescue StandardError
+    nil
+  end
+end