metrixwire 0.2.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 60349ff1d29a910423b140cf510ecb4134a7ebbab5785018b97633d93d7b6a12
+  data.tar.gz: a945b1cd55dbba41183f4b1a59b6154fe58d98d9b74ef4614e37094fcafd22d6
+SHA512:
+  metadata.gz: 5deefc9b6d766d44d7c1da82bc876cd15bc143c200cd190c057666f773d86f1ccb3c1d249ce523e63c6494dbbe73eec2344cde0f6cbc3b37006d2c8ae48b9c1a
+  data.tar.gz: f75038a4a6e3f00d13f81979b52dd73c18dc301c3e971c0c6de2d965e4068c467f91452e47cddcf7157ce2769a7c632857491c164f69f26d3246662fa9391e71

data/README.md

@@ -0,0 +1,93 @@
+# metrixwire
+
+Zero-config APM SDK for **Ruby** — Rails, Sinatra & bare Rack. In Rails it's fully automatic: add the gem and set `METRIXWIRE_KEY`. Elsewhere, call `MetrixWire.init` once. Every request, database query, outbound HTTP call and cache op is instrumented automatically. There is no manual span API and no middleware to wire up. Non-blocking: if the MetrixWire endpoint is down, your app keeps running normally.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'metrixwire', require: 'metrixwire'
+```
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Rails — fully automatic
+
+Add the gem, set the key, done. A Railtie auto-initializes from ENV, inserts the Rack middleware (one trace per request), and subscribes to `ActiveSupport::Notifications` — no code changes:
+
+```bash
+export METRIXWIRE_KEY=mw_...
+```
+
+### Sinatra & bare Rack — automatic
+
+Just require the gem and call `init` once, as early as possible:
+
+```ruby
+require 'metrixwire'
+MetrixWire.init(api_key: ENV['METRIXWIRE_KEY'])
+```
+
+The SDK patches `Rack::Builder#to_app`, so the tracing middleware is inserted for you — you never write `use MetrixWire::Rack`. Every HTTP request becomes a **trace**, and every query / HTTP call / cache op within it becomes a **span**.
+
+## How the automatic tracing works
+
+| Framework | Traced automatically | Notes |
+|---|---|---|
+| **Rails** | ✅ | Route refined to `controller#action` via `ActiveSupport::Notifications`. 5xx & exceptions captured. |
+| **Sinatra** | ✅ | Route pattern (`GET /users/:id`) detected from `sinatra.route`. Zero wiring. |
+| **bare Rack** | ✅ | Middleware auto-inserted via `Rack::Builder#to_app`. |
+
+The Rails path uses `ActiveSupport::Notifications` (the idiomatic, reliable route): `sql.active_record` for DB spans, `process_action.action_controller` for the route + errors, `cache_*.active_support` for cache spans, and `transaction.active_record` for transaction spans. Outside Rails, DB and HTTP are captured by patching the underlying drivers directly.
+
+## Automatically instrumented libraries
+
+| Library | How |
+|---|---|
+| **ActiveRecord** (Rails) | `sql.active_record` notifications (db_query + rowCount) |
+| **pg** | patches `PG::Connection#exec`/`#exec_params`/`#async_exec` (rowCount from the result; transaction spans from `BEGIN…COMMIT`) |
+| **mysql2** | patches `Mysql2::Client#query` |
+| **sqlite3** | patches `SQLite3::Database#execute` |
+| **Net::HTTP** (and libs built on it) | patches `Net::HTTP#request` (http_call span + statusCode) |
+| **redis / redis-client** | cache spans (hit/miss where known) for the slow-cache detector |
+
+Each patch is guarded: if the library or constant isn't present, it's skipped silently. The core has **zero runtime gem dependencies** (stdlib only).
+
+## `init` options
+
+```ruby
+MetrixWire.init(
+  api_key: 'mw_...',                        # required (falls back to METRIXWIRE_KEY)
+  endpoint: 'http://localhost:3000/ingest',  # default (a base URL is accepted; /ingest is appended)
+  flush_interval_ms: 5000,                   # how often batches are sent
+  enabled: true,                             # set to false to disable entirely (or METRIXWIRE_ENABLED=false)
+  timeout_ms: 3000,                          # send timeout (short, non-blocking)
+  max_batch: 20,                             # flush immediately once this many are queued
+  capture_source: true                       # capture the file:line a span originated from
+)
+```
+
+All options fall back to environment variables when omitted: `METRIXWIRE_KEY`, `METRIXWIRE_ENDPOINT`, `METRIXWIRE_ENABLED`. With no API key the SDK runs in disabled mode instead of raising.
+
+## Non-blocking behavior
+
+- Traces are batched on a background **daemon thread** and sent off the request path with a short timeout.
+- **All** transport errors are swallowed — instrumentation never throws into or blocks your app.
+- A final flush runs on `at_exit`; you can also call `MetrixWire.flush` before a short-lived process exits.
+
+## Error boundary (escape hatch)
+
+For frameworks the SDK can't hook automatically, attach an exception to the active trace — this is **not** a manual span API; requests/queries are still captured automatically:
+
+```ruby
+begin
+  do_work
+rescue => e
+  MetrixWire.capture_exception(e)
+  raise
+end
+```

data/lib/metrixwire/config.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  # Immutable-ish config holder. Built once by {MetrixWire.init} from explicit
+  # options with ENV fallbacks. Nothing here throws — bad input degrades to a
+  # sensible default so instrumentation never breaks the host app.
+  class Config
+    DEFAULT_ENDPOINT = "http://localhost:3000/ingest"
+    DEFAULT_FLUSH_INTERVAL_MS = 5000
+    DEFAULT_TIMEOUT_MS = 3000
+    DEFAULT_MAX_BATCH = 20
+
+    attr_reader :api_key, :endpoint, :flush_interval_ms, :enabled,
+                :timeout_ms, :max_batch, :capture_source
+
+    def initialize(opts = {})
+      @api_key = to_s(opts.fetch(:api_key, env("METRIXWIRE_KEY")))
+      @endpoint = normalize_endpoint(opts.fetch(:endpoint, env("METRIXWIRE_ENDPOINT")) || DEFAULT_ENDPOINT)
+      @flush_interval_ms = to_i(opts[:flush_interval_ms], DEFAULT_FLUSH_INTERVAL_MS)
+      @timeout_ms = to_i(opts[:timeout_ms], DEFAULT_TIMEOUT_MS)
+      @max_batch = to_i(opts[:max_batch], DEFAULT_MAX_BATCH)
+      @capture_source = opts.fetch(:capture_source, true) ? true : false
+
+      enabled = opts.key?(:enabled) ? opts[:enabled] : env_enabled
+      # No key ⇒ disabled mode (never throw). Matches Node/PHP behavior.
+      @enabled = (enabled ? true : false) && !@api_key.empty?
+    end
+
+    # Accept a base URL too: append /ingest when missing.
+    def normalize_endpoint(url)
+      url = to_s(url)
+      url = DEFAULT_ENDPOINT if url.empty?
+      url = url.sub(%r{/+\z}, "")
+      url = "#{url}/ingest" unless url.end_with?("/ingest")
+      url
+    rescue StandardError
+      DEFAULT_ENDPOINT
+    end
+
+    private
+
+    def env(key)
+      v = ENV[key]
+      v.nil? || v.empty? ? nil : v
+    end
+
+    def env_enabled
+      raw = ENV["METRIXWIRE_ENABLED"]
+      return true if raw.nil? || raw.empty?
+
+      !%w[false 0 no off].include?(raw.strip.downcase)
+    end
+
+    def to_s(v)
+      v.nil? ? "" : v.to_s
+    end
+
+    def to_i(v, default)
+      return default if v.nil?
+
+      i = Integer(v.to_s, exception: false)
+      i.nil? || i <= 0 ? default : i
+    rescue StandardError
+      default
+    end
+  end
+end

data/lib/metrixwire/context.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  # Thread/fiber-local "current trace" holder. Every entry point (Rack
+  # middleware, ActiveSupport subscribers, DB/HTTP patches) reads the active
+  # trace from here so spans attach to the right request. Fiber-local storage
+  # (Thread#[]) keeps concurrent requests isolated on threaded servers.
+  module Context
+    KEY = :__metrixwire_current_trace__
+
+    module_function
+
+    def current
+      Thread.current[KEY]
+    end
+
+    def current=(trace)
+      Thread.current[KEY] = trace
+    end
+
+    # Run a block with `trace` as the active trace, restoring the previous one
+    # afterwards. Restores even if the block raises.
+    def with(trace)
+      prev = Thread.current[KEY]
+      Thread.current[KEY] = trace
+      yield
+    ensure
+      Thread.current[KEY] = prev
+    end
+
+    def clear
+      Thread.current[KEY] = nil
+    end
+  end
+end

data/lib/metrixwire/instrument/active_support.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  module Instrument
+    # Subscribes to ActiveSupport::Notifications for the idiomatic, reliable
+    # Rails path: SQL queries, controller actions (route refinement + errors),
+    # and cache reads/writes. Each subscriber is guarded and never throws.
+    module ActiveSupportSubscriber
+      SCHEMA_SQL = /\A\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE|SET|SHOW|PRAGMA)\b/i.freeze
+
+      module_function
+
+      def install
+        return unless defined?(::ActiveSupport::Notifications)
+        return if @installed
+
+        subscribe_sql
+        subscribe_process_action
+        subscribe_cache
+        subscribe_transaction
+        @installed = true
+      rescue StandardError
+        nil
+      end
+
+      # db_query spans from sql.active_record. rowCount from the result payload
+      # when ActiveRecord exposes it.
+      def subscribe_sql
+        ::ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+          begin
+            trace = Context.current
+            next if trace.nil?
+
+            event = event_of(args)
+            payload = event.payload
+            name = payload[:name].to_s
+            sql = payload[:sql].to_s
+            # Skip schema/transaction control + AR's own housekeeping queries.
+            next if sql.empty? || SCHEMA_SQL.match?(sql)
+            next if name == "SCHEMA" || name == "TRANSACTION"
+
+            meta = row_count_from_payload(payload)
+            Helpers.add_span("db_query", sql, event.duration, meta: meta, source_location: nil)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      # Refine the route to controller#action, capture 5xx + exceptions.
+      def subscribe_process_action
+        ::ActiveSupport::Notifications.subscribe("process_action.action_controller") do |*args|
+          begin
+            trace = Context.current
+            next if trace.nil?
+
+            payload = event_of(args).payload
+            controller = payload[:controller]
+            action = payload[:action]
+            method = payload[:method] || trace.method
+            if controller && action
+              trace.route = "#{method} #{controller}##{action}"
+            end
+
+            status = payload[:status].to_i
+            trace.status = "error" if status >= 500
+
+            if (ex = payload[:exception_object])
+              trace.capture_exception(ex)
+            elsif (ex_arr = payload[:exception])
+              # [class_name, message]
+              trace.set_meta(:exception, {
+                type: ex_arr[0].to_s,
+                message: ex_arr[1].to_s
+              })
+              trace.status = "error"
+            end
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      # Cache reads/writes → custom cache spans. hit is known for cache_read.
+      def subscribe_cache
+        ::ActiveSupport::Notifications.subscribe(/\Acache_(read|fetch_hit|write|delete)\.active_support\z/) do |*args|
+          begin
+            trace = Context.current
+            next if trace.nil?
+
+            event = event_of(args)
+            name = event.name.to_s
+            payload = event.payload
+            op, hit = cache_op(name, payload)
+            meta = { kind: "cache", op: op }
+            meta[:hit] = hit unless hit.nil?
+            Helpers.add_span("custom", "cache #{op}", event.duration, meta: meta, source_location: nil)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      # ActiveRecord transaction notifications (Rails 7.2+) → transaction spans.
+      def subscribe_transaction
+        ::ActiveSupport::Notifications.subscribe("transaction.active_record") do |*args|
+          begin
+            trace = Context.current
+            next if trace.nil?
+
+            event = event_of(args)
+            Helpers.add_span("custom", "DB transaction", event.duration,
+                             meta: { kind: "transaction" }, source_location: nil)
+          rescue StandardError
+            nil
+          end
+        end
+      rescue StandardError
+        nil
+      end
+
+      def cache_op(name, payload)
+        case name
+        when "cache_read.active_support"
+          ["read", payload.key?(:hit) ? (payload[:hit] ? true : false) : nil]
+        when "cache_fetch_hit.active_support"
+          ["read", true]
+        when "cache_write.active_support"
+          ["write", nil]
+        when "cache_delete.active_support"
+          ["delete", nil]
+        else
+          [name.split(".").first.sub("cache_", ""), nil]
+        end
+      end
+
+      def row_count_from_payload(payload)
+        row_count = payload[:row_count]
+        return { rowCount: row_count.to_i } if row_count
+
+        result = payload[:result]
+        n = Helpers.extract_row_count(result)
+        n.nil? ? nil : { rowCount: n }
+      rescue StandardError
+        nil
+      end
+
+      # Build an ActiveSupport::Notifications::Event from the raw subscribe args.
+      def event_of(args)
+        ::ActiveSupport::Notifications::Event.new(*args)
+      end
+    end
+  end
+end

data/lib/metrixwire/instrument/helpers.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  module Instrument
+    # Shared helpers used by every low-level patch (PG, mysql2, Net::HTTP, …).
+    # These attach spans to the *current* trace only; if there's no active trace
+    # (work outside a request), they no-op. Never throw.
+    module Helpers
+      module_function
+
+      # Add a span to the active trace. `duration_ms` is a float; description is
+      # e.g. the SQL text or "GET https://host/path".
+      def add_span(type, description, duration_ms, meta: nil, source_location: :auto)
+        trace = Context.current
+        return if trace.nil? || description.nil? || description.to_s.empty?
+
+        loc = source_location == :auto ? SourceLocation.nearest : source_location
+        span = Span.new(
+          type: type,
+          description: description.to_s,
+          started_at: MetrixWire.iso8601(Time.now - (duration_ms / 1000.0)),
+          duration_ms: [duration_ms, 0].max.round,
+          source_location: loc,
+          meta: (meta && !meta.empty? ? meta : nil)
+        )
+        trace.add_span(span)
+      rescue StandardError
+        # instrumentation must never throw
+      end
+
+      # Time a block, then record a db_query span. Returns the block's result.
+      def db_query(sql)
+        return yield if Context.current.nil?
+
+        t0 = MetrixWire.monotonic_ms
+        result = yield
+        add_span("db_query", sql, MetrixWire.monotonic_ms - t0, meta: row_count_meta(result))
+        result
+      rescue StandardError
+        raise
+      end
+
+      def row_count_meta(result)
+        n = extract_row_count(result)
+        n.nil? ? nil : { rowCount: n }
+      rescue StandardError
+        nil
+      end
+
+      # Best-effort row count across PG::Result / Mysql2::Result / Array / etc.
+      def extract_row_count(result)
+        if result.respond_to?(:cmd_tuples) && result.respond_to?(:ntuples)
+          # PG::Result: prefer affected rows for writes, tuple count for reads.
+          nt = result.ntuples
+          return nt if nt && nt > 0
+
+          ct = result.cmd_tuples
+          return ct if ct && ct >= 0
+
+          nt
+        elsif result.respond_to?(:count) && !result.is_a?(String)
+          result.count
+        elsif result.respond_to?(:size)
+          result.size
+        end
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/metrixwire/instrument/mysql2.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  module Instrument
+    # Best-effort patch of the `mysql2` gem (Mysql2::Client#query). Guarded:
+    # skips silently if the gem isn't loaded.
+    module Mysql2
+      module_function
+
+      def install
+        return unless defined?(::Mysql2::Client)
+        return if ::Mysql2::Client.instance_variable_get(:@__metrixwire_patched)
+
+        ::Mysql2::Client.prepend(Patch)
+        ::Mysql2::Client.instance_variable_set(:@__metrixwire_patched, true)
+      rescue StandardError
+        nil
+      end
+
+      module Patch
+        def query(*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/instrument/net_http.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module MetrixWire
+  module Instrument
+    # Patches Net::HTTP#request so outbound HTTP calls become http_call spans
+    # with the response status code. Covers Net::HTTP directly and libraries
+    # built on it. Skips requests to the MetrixWire ingest endpoint itself so we
+    # never trace our own telemetry.
+    module NetHttp
+      module_function
+
+      def install
+        return if ::Net::HTTP.instance_variable_get(:@__metrixwire_patched)
+
+        ::Net::HTTP.prepend(Patch)
+        ::Net::HTTP.instance_variable_set(:@__metrixwire_patched, true)
+      rescue StandardError
+        nil
+      end
+
+      module Patch
+        def request(req, body = nil, &block)
+          return super if Context.current.nil?
+
+          desc = MetrixWire::Instrument::NetHttp.describe(self, req)
+          if desc.nil? || MetrixWire::Instrument::NetHttp.own_endpoint?(desc)
+            return super
+          end
+
+          t0 = MetrixWire.monotonic_ms
+          resp = super
+          status = begin
+            resp.respond_to?(:code) ? resp.code.to_i : nil
+          rescue StandardError
+            nil
+          end
+          Helpers.add_span("http_call", desc, MetrixWire.monotonic_ms - t0,
+                           meta: (status ? { statusCode: status } : nil))
+          resp
+        rescue StandardError => e
+          raise e
+        end
+      end
+
+      # Build "GET https://host/path" from the connection + request objects.
+      def describe(http, req)
+        method = req.respond_to?(:method) ? req.method : "GET"
+        scheme = http.respond_to?(:use_ssl?) && http.use_ssl? ? "https" : "http"
+        host = http.respond_to?(:address) ? http.address : nil
+        port = http.respond_to?(:port) ? http.port : nil
+        return nil if host.nil?
+
+        path = req.respond_to?(:path) ? req.path.to_s.split("?").first : "/"
+        hostport = default_port?(scheme, port) ? host : "#{host}:#{port}"
+        "#{method} #{scheme}://#{hostport}#{path}"
+      rescue StandardError
+        nil
+      end
+
+      def default_port?(scheme, port)
+        (scheme == "https" && port == 443) || (scheme == "http" && port == 80)
+      rescue StandardError
+        true
+      end
+
+      def own_endpoint?(desc)
+        ep = MetrixWire.endpoint
+        return false if ep.nil? || ep.empty?
+
+        host = URI.parse(ep).host
+        host && desc.include?("//#{host}") || (host && desc.include?("//#{host}:"))
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/metrixwire/instrument/pg.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  module Instrument
+    # Patches the `pg` gem (PG::Connection) so raw queries outside Rails become
+    # db_query spans with a row count. Guarded: skips silently if `pg` isn't
+    # loaded. Also detects BEGIN…COMMIT/ROLLBACK to emit a transaction span.
+    module Pg
+      module_function
+
+      def install
+        return unless defined?(::PG::Connection)
+        return if ::PG::Connection.instance_variable_get(:@__metrixwire_patched)
+
+        ::PG::Connection.prepend(Patch)
+        ::PG::Connection.instance_variable_set(:@__metrixwire_patched, true)
+      rescue StandardError
+        nil
+      end
+
+      # A per-connection cursor tracking an open transaction's start time.
+      module Patch
+        %i[exec exec_params async_exec sync_exec query].each do |m|
+          define_method(m) do |*args, &blk|
+            sql = args.first
+            return super(*args, &blk) if Context.current.nil? || !sql.is_a?(String)
+
+            MetrixWire::Instrument::Pg.handle_transaction(self, sql)
+
+            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
+            # If our bookkeeping fails, still run the real query.
+            super(*args, &blk)
+          end
+        end
+      end
+
+      # Emit a transaction span on COMMIT/ROLLBACK, timed from the BEGIN.
+      def handle_transaction(conn, sql)
+        stmt = sql.strip
+        if /\A(BEGIN|START\s+TRANSACTION)\b/i.match?(stmt)
+          conn.instance_variable_set(:@__metrixwire_tx_start, MetrixWire.monotonic_ms)
+        elsif /\A(COMMIT|ROLLBACK)\b/i.match?(stmt)
+          started = conn.instance_variable_get(:@__metrixwire_tx_start)
+          conn.instance_variable_set(:@__metrixwire_tx_start, nil)
+          if started
+            Helpers.add_span("custom", "DB transaction", MetrixWire.monotonic_ms - started,
+                             meta: { kind: "transaction" })
+          end
+        end
+      rescue StandardError
+        nil
+      end
+
+      def control_statement?(sql)
+        /\A\s*(BEGIN|START\s+TRANSACTION|COMMIT|ROLLBACK|SAVEPOINT|RELEASE)\b/i.match?(sql)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/metrixwire/instrument/rack_builder.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module MetrixWire
+  module Instrument
+    # Auto-inserts {MetrixWire::Rack} into any Rack app that isn't Rails, by
+    # patching Rack::Builder#to_app to wrap the built app once. This is what
+    # makes Sinatra / bare Rack "zero-wiring": the user never adds `use`.
+    #
+    # Rails is handled by the Railtie instead (this patch skips when Rails is
+    # defined so we don't double-wrap).
+    module RackBuilder
+      module_function
+
+      def install
+        return unless defined?(::Rack::Builder)
+        return if ::Rack::Builder.instance_variable_get(:@__metrixwire_patched)
+
+        ::Rack::Builder.prepend(Patch)
+        ::Rack::Builder.instance_variable_set(:@__metrixwire_patched, true)
+      rescue StandardError
+        nil
+      end
+
+      module Patch
+        def to_app
+          app = super
+          return app if app.nil?
+          return app if defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+          # Wrap once. Marking the built app prevents re-wrapping if to_app runs
+          # more than once (e.g. nested builders).
+          return app if app.instance_variable_get(:@__metrixwire_wrapped)
+
+          wrapped = MetrixWire::Rack.new(app)
+          wrapped.instance_variable_set(:@__metrixwire_wrapped, true)
+          wrapped
+        rescue StandardError
+          super
+        end
+      end
+    end
+  end
+end