visionary-sdk 0.4.0

data/lib/visionary/system/sources.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module Visionary
+  module System
+    # Readers for host and process figures. Linux has /proc; elsewhere most
+    # host figures are unavailable and stay NULL. Every reader returns nil
+    # (or an empty Hash) when its source fails.
+    module Sources
+      LINUX = RUBY_PLATFORM.include?("linux")
+      WINDOWS = Gem.win_platform?
+      CPU_FIELDS = %i[user nice system idle iowait irq softirq steal guest guest_nice].freeze
+      # Partitions and virtual devices whose I/O is already counted in a
+      # whole disk, so totals are not doubled.
+      PARTITION = /\A((sd|vd|xvd|hd)[a-z]+\d+|nvme\d+n\d+p\d+|mmcblk\d+p\d+|loop\d+|ram\d+|zram\d+|dm-\d+|sr\d+|fd\d+|md\d+)\z/
+
+      module_function
+
+      def quiet
+        yield
+      rescue StandardError, NotImplementedError
+        nil
+      end
+
+      def read(path)
+        File.read(path)
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      # /proc/stat: aggregate CPU times, context switches, running and
+      # blocked processes.
+      def proc_stat
+        out = {}
+        read("/proc/stat")&.each_line do |line|
+          parts = line.split
+          case parts[0]
+          when "cpu" then out[:cpu] = CPU_FIELDS.zip(parts[1..].map(&:to_f)).to_h.reject { |_, v| v.nil? }
+          when "ctxt", "procs_running", "procs_blocked" then out[parts[0].to_sym] = parts[1].to_i
+          end
+        end
+        out
+      end
+
+      def loadavg
+        f = read("/proc/loadavg")&.split
+        f && f.size >= 3 ? f[0, 3].map(&:to_f) : nil
+      end
+
+      # /proc/meminfo in bytes.
+      def meminfo
+        out = {}
+        read("/proc/meminfo")&.each_line do |line|
+          name, rest = line.split(":", 2)
+          fields = rest.to_s.split
+          next if fields.empty?
+          out[name] = fields[0].to_i * (fields[1] == "kB" ? 1024 : 1)
+        end
+        out
+      end
+
+      # Whole disks: name => [read bytes, written bytes, reads, writes, ms
+      # reading + writing, ms doing I/O].
+      def diskstats
+        out = {}
+        read("/proc/diskstats")&.each_line do |line|
+          p = line.split
+          next if p.size < 14 || PARTITION.match?(p[2])
+          out[p[2]] = [p[5].to_i * 512, p[9].to_i * 512, p[3].to_i, p[7].to_i, p[6].to_i + p[10].to_i, p[12].to_i]
+        end
+        out
+      end
+
+      # All interfaces: [rx bytes, tx bytes, rx packets, tx packets, errors, drops].
+      def net_dev
+        text = read("/proc/net/dev") or return nil
+        sums = [0, 0, 0, 0, 0, 0]
+        text.each_line do |line|
+          next unless line.include?(":")
+          p = line.split(":", 2)[1].split
+          next if p.size < 12
+          sums[0] += p[0].to_i
+          sums[1] += p[8].to_i
+          sums[2] += p[1].to_i
+          sums[3] += p[9].to_i
+          sums[4] += p[2].to_i + p[10].to_i
+          sums[5] += p[3].to_i + p[11].to_i
+        end
+        sums
+      end
+
+      # /proc/net/snmp Tcp counters (CurrEstab, RetransSegs, ...).
+      def tcp
+        rows = read("/proc/net/snmp")&.each_line&.select { |l| l.start_with?("Tcp:") }&.map(&:split)
+        return {} unless rows && rows.size >= 2
+        rows[0][1..].zip(rows[1][1..].map(&:to_i)).to_h
+      end
+
+      # VmRSS (bytes) and Threads from /proc/self/status.
+      def self_status
+        out = {}
+        read("/proc/self/status")&.each_line do |line|
+          if line.start_with?("VmRSS:") then out[:rss] = line.split[1].to_i * 1024
+          elsif line.start_with?("Threads:") then out[:threads] = line.split[1].to_i
+          end
+        end
+        out
+      end
+
+      def self_io
+        vals = {}
+        read("/proc/self/io")&.each_line do |line|
+          k, v = line.split(":", 2)
+          vals[k.strip] = v.to_i
+        end
+        vals.key?("read_bytes") ? [vals["read_bytes"], vals["write_bytes"].to_i] : nil
+      end
+
+      def open_fds
+        quiet { Dir.children("/proc/self/fd").size } if LINUX
+      end
+
+      def host_procs
+        quiet { Dir.children("/proc").count { |n| n.match?(/\A\d+\z/) } } if LINUX
+      end
+
+      def max_fds
+        soft = quiet { Process.getrlimit(:NOFILE)[0] }
+        return nil unless soft
+        soft.positive? && soft < (1 << 40) && soft != Process::RLIM_INFINITY ? soft : nil
+      end
+
+      def cpu_count = quiet { Etc.nprocessors }
+
+      def process_cpu_seconds
+        quiet { Process.clock_gettime(Process::CLOCK_PROCESS_CPUTIME_ID) } ||
+          quiet { Process.times.then { |t| t.utime + t.stime } }
+      end
+
+      # The filesystem holding path, from df (POSIX output, 1 KiB blocks):
+      # { total:, used:, free: } in bytes, plus inode use when df knows it.
+      def disk(path)
+        return nil if WINDOWS || @no_df
+        blocks = df(["-Pk", path]) or return nil
+        out = { total: blocks[1] * 1024, used: blocks[2] * 1024, free: blocks[3] * 1024 }
+        if LINUX && (inodes = df(["-Pi", path])) && inodes[1].positive?
+          out[:inodes_percent] = inodes[2] * 100.0 / inodes[1]
+        end
+        out
+      end
+
+      def df(args)
+        text = IO.popen(["df", *args], err: File::NULL, &:read)
+        fields = text.lines[1..].to_a.join(" ").split
+        nums = fields[1, 3].to_a
+        return nil unless nums.size == 3 && nums.all? { |n| n.match?(/\A\d+\z/) }
+        [fields[0], *nums.map(&:to_i)]
+      rescue Errno::ENOENT
+        @no_df = true
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # Ruby heap: live slots and the pages holding them.
+      def heap
+        st = GC.stat
+        consts = defined?(GC::INTERNAL_CONSTANTS) ? GC::INTERNAL_CONSTANTS : {}
+        slot = consts[:BASE_SLOT_SIZE] || consts[:RVALUE_SIZE] || 40
+        page = consts[:HEAP_PAGE_SIZE]
+        {
+          live: st[:heap_live_slots],
+          alloc_bytes: st[:heap_live_slots] && st[:heap_live_slots] * slot,
+          inuse_bytes: page && st[:heap_allocated_pages] && st[:heap_allocated_pages] * page,
+          gc_count: GC.count,
+          gc_ms: st[:time]
+        }
+      end
+
+      # The app's ActiveRecord pool, when it has one.
+      def active_record_pool
+        return nil unless defined?(::ActiveRecord::Base) && ::ActiveRecord::Base.respond_to?(:connection_pool)
+        st = ::ActiveRecord::Base.connection_pool.stat
+        { total: st[:connections], idle: st[:idle], in_use: st[:busy], max: st[:size] }
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/visionary/telemetry/errors.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+require "rbconfig"
+
+module Visionary
+  module Telemetry
+    # Exception rows: type, message, stack and a fingerprint that groups
+    # occurrences of the same error.
+    module Errors
+      MAX_MESSAGE = 1000
+      MAX_STACK = 16 * 1024
+      FRAMES = 5
+      PER_MINUTE = 20
+      SDK_DIR = File.expand_path("..", __dir__)
+
+      module_function
+
+      # The first 16 hex chars of SHA-1 over the type and the top in-app
+      # frames as "function@file" (no line numbers); without frames, over the
+      # type and the message with digit runs replaced by 0.
+      def fingerprint(exception)
+        type = exception.class.name || exception.class.to_s
+        frames = app_frames(exception)
+        basis = frames.empty? ? "#{type}\n#{exception.message.to_s.gsub(/\d+/, '0')}" : "#{type}\n#{frames.join("\n")}"
+        Digest::SHA1.hexdigest(basis)[0, 16]
+      end
+
+      # Top frames from the application's own code: not the standard library,
+      # installed gems or this SDK. When every frame is library code, the top
+      # frames as they are.
+      def app_frames(exception)
+        locs = exception.backtrace_locations
+        frames = if locs
+                   locs.map { |l| [l.label.to_s, (l.absolute_path || l.path).to_s] }
+                 else
+                   Array(exception.backtrace).map { |line| parse_line(line) }.compact
+                 end
+        own = frames.reject { |_, file| library?(file) }
+        own = frames if own.empty?
+        own.first(FRAMES).map { |label, file| "#{label}@#{relative(file)}" }
+      end
+
+      def parse_line(line)
+        m = line.match(/\A(.+?):\d+:in [`'](.*)'\z/)
+        m && [m[2], m[1]]
+      end
+
+      def library?(file)
+        return true if file.empty? || file.start_with?("<internal:") || file.start_with?("<")
+        f = file.tr("\\", "/")
+        library_dirs.any? { |dir| f.start_with?(dir) } || f.include?("/gems/") || f.include?("/vendor/bundle/")
+      end
+
+      def library_dirs
+        @library_dirs ||= begin
+          dirs = [SDK_DIR, RbConfig::CONFIG["rubylibdir"], RbConfig::CONFIG["rubyarchdir"], RbConfig::CONFIG["rubylibprefix"]]
+          dirs.concat(Gem.path) if defined?(Gem) && Gem.respond_to?(:path)
+          dirs << Bundler.bundle_path.to_s if defined?(Bundler) && Bundler.respond_to?(:bundle_path)
+          dirs.compact.map { |d| d.to_s.tr("\\", "/").chomp("/") + "/" }.reject { |d| d == "/" }.uniq.freeze
+        rescue StandardError
+          [SDK_DIR.tr("\\", "/") + "/"].freeze
+        end
+      end
+
+      # Paths relative to the app root, so instances deployed to different
+      # directories fingerprint alike.
+      def relative(file)
+        f = file.tr("\\", "/")
+        root = (@root ||= Dir.pwd.tr("\\", "/").chomp("/") + "/")
+        f.start_with?(root) ? f.delete_prefix(root) : f
+      end
+
+      def type_name(exception)
+        exception.class.name || exception.class.to_s
+      end
+
+      def message(exception)
+        m = exception.message.to_s.scrub
+        m.length > MAX_MESSAGE ? m[0, MAX_MESSAGE] : m
+      end
+
+      # Ruby's own format: "file:line:in 'method': message (Class)" then the
+      # "from" lines, causes included.
+      def stack(exception)
+        s = if exception.backtrace
+              exception.full_message(highlight: false, order: :top)
+            else
+              "#{message(exception)} (#{type_name(exception)})"
+            end
+        s = s.scrub
+        s.bytesize > MAX_STACK ? s.byteslice(0, MAX_STACK).scrub("") : s
+      rescue StandardError
+        ""
+      end
+
+      # At most PER_MINUTE rows per fingerprint per minute in this process.
+      class Limiter
+        def initialize
+          @mutex = Mutex.new
+          @minute = nil
+          @counts = Hash.new(0)
+        end
+
+        def allow?(fingerprint)
+          minute = (Process.clock_gettime(Process::CLOCK_MONOTONIC) / 60).floor
+          @mutex.synchronize do
+            if minute != @minute
+              @minute = minute
+              @counts.clear
+            end
+            (@counts[fingerprint] += 1) <= PER_MINUTE
+          end
+        end
+      end
+    end
+  end
+end

data/lib/visionary/telemetry/hooks.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Visionary
+  module Telemetry
+    # Database spans from ActiveRecord's sql.active_record notifications.
+    module ActiveRecordHook
+      SKIP = %w[SCHEMA CACHE].freeze
+      SYSTEMS = { "postg" => "postgresql", "mysql" => "mysql", "trilogy" => "mysql", "sqlite" => "sqlite" }.freeze
+
+      @installed = false
+      @targets = {}
+      @mutex = Mutex.new
+
+      class << self
+        def installed? = @installed
+
+        def install
+          return if @installed || !defined?(::ActiveSupport::Notifications)
+          @installed = true
+          ::ActiveSupport::Notifications.subscribe("sql.active_record") do |_name, start, finish, _id, payload|
+            record(start, finish, payload)
+          end
+        end
+
+        def record(start, finish, payload)
+          rec = Visionary.telemetry
+          return unless rec&.spans_on
+          return if payload[:cached] || SKIP.include?(payload[:name])
+          return if Telemetry.internal?
+
+          duration = (finish - start).to_f * 1000.0
+          sql = payload[:sql].to_s
+          exc = payload[:exception]
+          rec.span(
+            kind: "db", name: SQLText.name(sql), target: target(payload[:connection]),
+            detail: SQLText.sanitize(sql), start_mono: Telemetry.now_ms - duration, duration_ms: duration,
+            status: exc ? "error" : "ok", error: exc && "#{exc[0]}: #{exc[1]}",
+            row_count: payload[:row_count].is_a?(Integer) ? payload[:row_count] : nil
+          )
+        rescue StandardError
+          nil
+        end
+
+        # "postgresql/voygram", cached per pool.
+        def target(conn)
+          return nil unless conn.respond_to?(:pool)
+          pool = conn.pool
+          @mutex.synchronize do
+            @targets.fetch(pool.object_id) do
+              @targets[pool.object_id] = describe(pool, conn)
+            end
+          end
+        rescue StandardError
+          nil
+        end
+
+        def describe(pool, conn)
+          cfg = pool.respond_to?(:db_config) ? pool.db_config : nil
+          adapter = (cfg ? cfg.adapter : conn.adapter_name).to_s.downcase
+          system = SYSTEMS.find { |k, _| adapter.include?(k) }&.last || adapter
+          db = cfg&.database.to_s
+          db = File.basename(db, ".*") if system == "sqlite"
+          db.empty? ? system : "#{system}/#{db}"
+        end
+      end
+    end
+
+    # Outbound HTTP spans from Net::HTTP (and the many clients built on it).
+    module NetHTTPHook
+      def request(req, body = nil, &block)
+        rec = Visionary.telemetry
+        # Net::HTTP#request calls itself again once the connection is up;
+        # that inner call is the one measured.
+        return super unless rec&.spans_on && started? && !Telemetry.internal?
+
+        t0 = Telemetry.now_ms
+        status = "ok"
+        error = nil
+        begin
+          res = super
+          status = "error" if res.code.to_i >= 500
+          res
+        rescue Exception => e # re-raised; the caller sees the same failure
+          status = "error"
+          error = "#{e.class}: #{e.message}"
+          raise
+        ensure
+          Telemetry::NetHTTPHook.record(rec, self, req, t0, status, error)
+        end
+      end
+
+      def self.record(rec, http, req, t0, status, error)
+        host = http.address.to_s
+        scheme = http.use_ssl? ? "https" : "http"
+        port = http.port == (http.use_ssl? ? 443 : 80) ? "" : ":#{http.port}"
+        path = req.path.to_s.split("?", 2).first
+        path = URI(path).path if path.start_with?("http://", "https://")
+        rec.span(
+          kind: "http", name: "#{req.method} #{host}", target: host,
+          detail: "#{req.method} #{scheme}://#{host}#{port}#{path}",
+          start_mono: t0, duration_ms: Telemetry.now_ms - t0, status: status, error: error
+        )
+      rescue StandardError
+        nil
+      end
+
+      def self.install
+        return if @installed
+        require "net/http"
+        Net::HTTP.prepend(self)
+        @installed = true
+      end
+    end
+  end
+end

data/lib/visionary/telemetry/sql_text.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Visionary
+  module Telemetry
+    # Statement sanitizing and span names for database calls.
+    module SQLText
+      STRING = /'(?:[^']|'')*'/
+      # A number not part of an identifier (t1, $1 placeholders stay).
+      NUMBER = /(?<![\w$.])-?\d+(?:\.\d+)?(?:e[+-]?\d+)?(?![\w.])/i
+      IN_LIST = /\bIN\s*\(\s*\?(?:\s*,\s*\?)*\s*\)/i
+      TABLE_AFTER = {
+        "SELECT" => /\bFROM\s+([\w."`\[\]]+)/i,
+        "DELETE" => /\bFROM\s+([\w."`\[\]]+)/i,
+        "INSERT" => /\bINTO\s+([\w."`\[\]]+)/i,
+        "REPLACE" => /\bINTO\s+([\w."`\[\]]+)/i,
+        "UPDATE" => /\AUPDATE\s+(?:ONLY\s+)?([\w."`\[\]]+)/i
+      }.freeze
+      MAX_DETAIL = 2000
+
+      module_function
+
+      # Literals become ?, IN lists collapse to IN (?), whitespace to one space.
+      def sanitize(sql)
+        s = sql.to_s.scrub("")
+        s = s.gsub(STRING, "?").gsub(NUMBER, "?").gsub(IN_LIST, "IN (?)")
+        s = s.gsub(/\s+/, " ").strip
+        s.length > MAX_DETAIL ? s[0, MAX_DETAIL] : s
+      end
+
+      # "SELECT users", "INSERT bookings", "BEGIN".
+      def name(sql)
+        s = sql.to_s.lstrip
+        s = s.sub(%r{\A(?:/\*.*?\*/\s*)+}m, "")
+        verb = s[/\A[a-zA-Z]+/].to_s.upcase
+        return "SQL" if verb.empty?
+        re = TABLE_AFTER[verb]
+        table = re && s[re, 1]
+        return verb unless table
+        table = table.delete("\"`[]").split(".").last
+        table && !table.empty? ? "#{verb} #{table}" : verb
+      end
+    end
+  end
+end

data/lib/visionary/telemetry.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "telemetry/sql_text"
+require_relative "telemetry/errors"
+
+module Visionary
+  module Telemetry
+    INTERNAL = :visionary_internal
+
+    # Marks the current thread as Visionary's own, so its database and HTTP
+    # calls (the writes themselves) never become spans.
+    def self.internal!
+      Thread.current[INTERNAL] = true
+      RequestContext.current = nil
+    end
+
+    def self.internal? = Thread.current[INTERNAL] == true
+
+    def self.runtime
+      @runtime ||= if RUBY_ENGINE == "ruby" then "CRuby #{RUBY_VERSION}"
+                   elsif defined?(JRUBY_VERSION) then "JRuby #{JRUBY_VERSION}"
+                   else "#{RUBY_ENGINE} #{RUBY_ENGINE_VERSION}"
+                   end
+    end
+
+    def self.now_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000.0
+
+    # Turns spans and exceptions into rows: inside a request they attach to
+    # it (and are written with it), outside they go straight to the writer.
+    class Recorder
+      attr_reader :spans_on, :errors_on
+
+      def initialize(cfg, instance, writer)
+        @cfg = cfg
+        @instance = instance
+        @writer = writer
+        @spans_on = cfg.spans ? true : false
+        @errors_on = cfg.errors ? true : false
+        @threshold = cfg.span_threshold_ms.to_f
+        @limiter = Errors::Limiter.new
+      end
+
+      # start_mono is the CLOCK_MONOTONIC start in ms, duration in ms.
+      def span(kind:, name:, start_mono:, duration_ms:, target: nil, detail: nil, status: "ok", error: nil, row_count: nil)
+        return unless @spans_on && @writer
+        return if Telemetry.internal?
+
+        ctx = RequestContext.current
+        duration_ms = duration_ms.to_f
+        started_at = Time.now - ((Telemetry.now_ms - start_mono) / 1000.0)
+        span = Span.new(
+          kind: kind.to_s, name: cut(name.to_s, 255), target: target && cut(target.to_s, 255),
+          detail: detail && cut(detail.to_s, SQLText::MAX_DETAIL), started_at: started_at,
+          offset_ms: ctx ? (start_mono - ctx.started_mono).round(3) : nil,
+          duration_ms: duration_ms.round(3), status: status, error: error && cut(error.to_s, 500),
+          row_count: row_count, request_id: ctx&.request_id
+        )
+        if ctx
+          ctx.add_span(span)
+        elsif duration_ms >= @threshold
+          @writer.enqueue([:span, span_row(span)])
+        end
+      rescue StandardError
+        nil
+      end
+
+      def span_row(span)
+        [Visionary.timestamp(span.started_at), span.request_id, @cfg.service, @instance, span.kind, span.name,
+         span.target, span.detail, span.offset_ms, span.duration_ms, span.status, span.error, span.row_count]
+      end
+
+      # Rows for a finished request's spans when it was slow or failed.
+      def request_span_rows(ctx, duration_ms, status)
+        return [] unless @spans_on && (duration_ms >= @threshold || status >= 500)
+        ctx.spans.map { |s| span_row(s) }
+      end
+
+      def exception(exception, handled:, ctx: RequestContext.current)
+        return unless @errors_on && @writer && exception.is_a?(Exception)
+
+        fp = Errors.fingerprint(exception)
+        return unless @limiter.allow?(fp)
+
+        row = {
+          created_at: Visionary.timestamp(Time.now), type: Errors.type_name(exception),
+          message: Errors.message(exception), stack: Errors.stack(exception),
+          fingerprint: fp, handled: handled ? 1 : 0
+        }
+        if ctx
+          ctx.add_error(row)
+        else
+          @writer.enqueue([:error, error_row(row, nil, nil)])
+        end
+      rescue StandardError
+        nil
+      end
+
+      # route and user come from the request when it has finished.
+      def error_row(row, ctx, route, user_id = nil)
+        [row[:created_at], @cfg.service, @instance, @cfg.version, ctx&.request_id, ctx&.method, nonempty(route),
+         ctx&.path, nonempty(user_id), row[:type], nonempty(row[:message]), nonempty(row[:stack]),
+         row[:fingerprint], row[:handled], Telemetry.runtime]
+      end
+
+      private
+
+      def nonempty(s)
+        s.nil? || s.to_s.empty? ? nil : s
+      end
+
+      def cut(s, max)
+        s.length > max ? s[0, max] : s
+      end
+    end
+  end
+end

data/lib/visionary/version.rb

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