deployangel 0.1.0

data/lib/deployangel/core/aggregator.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "set"
+
+module DeployAngel
+  # Accumulates request behavior into one-minute periods inside the process.
+  # Recording is a few hash updates under a mutex; nothing here touches the
+  # network.
+  class Aggregator
+    OTHER_ROUTE = "__other__"
+    PERIOD_SECONDS = 60
+    MAX_EXCEPTIONS = 20
+    MAX_BACKTRACES = 5
+    MAX_CHECKPOINTS = 100
+
+    RouteStats = Struct.new(:requests, :status_counts, :histogram) do
+      def self.empty
+        new(0, Hash.new(0), Histogram.new)
+      end
+    end
+
+    JobStats = Struct.new(:processed, :failed, :discarded, :duration, :queue_latency) do
+      def self.empty
+        new(0, 0, 0, Histogram.new, Histogram.new)
+      end
+
+      def record(failed, discarded, duration_ms, queue_latency_ms)
+        self.processed += 1
+        self.failed += 1 if failed
+        self.discarded += 1 if discarded
+        duration.record(duration_ms)
+        queue_latency.record(queue_latency_ms) if queue_latency_ms
+      end
+
+      def record_discard
+        self.discarded += 1
+      end
+    end
+
+    class Period
+      attr_reader :started_at, :requests, :status_counts, :unhandled_exceptions, :histogram, :routes,
+        :jobs, :job_classes, :exceptions, :exceptions_truncated, :checkpoints
+
+      def initialize(started_at)
+        @started_at = started_at
+        @requests = 0
+        @status_counts = Hash.new(0)
+        @unhandled_exceptions = 0
+        @histogram = Histogram.new
+        @routes = {}
+        @jobs = JobStats.empty
+        @job_classes = {}
+        @exceptions = {}
+        @exceptions_truncated = 0
+        @checkpoints = Hash.new(0)
+      end
+
+      # Up to 100 names per period; the rest are counted together.
+      def record_checkpoint(name, count)
+        key = @checkpoints.key?(name) || @checkpoints.size < MAX_CHECKPOINTS - 1 ? name : OTHER_ROUTE
+        @checkpoints[key] += count
+      end
+
+      # Up to 20 fingerprints per period; the rest are only counted.
+      def record_exception(details, source, handled, backtrace)
+        entry = @exceptions[details["fingerprint"]]
+        unless entry
+          if @exceptions.size >= MAX_EXCEPTIONS
+            @exceptions_truncated += 1
+            return
+          end
+
+          entry = @exceptions[details["fingerprint"]] = details.merge("count" => 0, "handled_count" => 0, "sources" => Hash.new(0))
+        end
+        handled ? entry["handled_count"] += 1 : entry["count"] += 1
+        entry["sources"][source] += 1 if source
+        entry["backtrace"] ||= backtrace if backtrace
+      end
+
+      def record_job(job_class, failed, discarded, duration_ms, queue_latency_ms, max_classes)
+        @jobs.record(failed, discarded, duration_ms, queue_latency_ms)
+        key = @job_classes.key?(job_class) || @job_classes.size < max_classes - 1 ? job_class : OTHER_ROUTE
+        (@job_classes[key] ||= JobStats.empty).record(failed, discarded, duration_ms, queue_latency_ms)
+      end
+
+      def record_discard(job_class, max_classes)
+        @jobs.record_discard
+        key = @job_classes.key?(job_class) || @job_classes.size < max_classes - 1 ? job_class : OTHER_ROUTE
+        (@job_classes[key] ||= JobStats.empty).record_discard
+      end
+
+      def record(route_key, status, duration_ms, unhandled, max_routes)
+        @requests += 1
+        @status_counts[status.to_s] += 1 if status >= 400
+        @unhandled_exceptions += 1 if unhandled
+        @histogram.record(duration_ms)
+
+        key = @routes.key?(route_key) || @routes.size < max_routes - 1 ? route_key : OTHER_ROUTE
+        route = (@routes[key] ||= RouteStats.empty)
+        route.requests += 1
+        route.status_counts[status.to_s] += 1 if status >= 400
+        route.histogram.record(duration_ms)
+      end
+    end
+
+    def initialize(max_routes: 100, clock: -> { Time.now.utc })
+      @max_routes = max_routes
+      @clock = clock
+      @periods = {}
+      @seen_fingerprints = Set.new
+      @last_drained_at = period_start(@clock.call) - PERIOD_SECONDS
+      @mutex = Mutex.new
+    end
+
+    def record(route_key:, status:, duration_ms:, unhandled: false)
+      started_at = period_start(@clock.call)
+      @mutex.synchronize do
+        (@periods[started_at] ||= Period.new(started_at))
+          .record(route_key, status.to_i, duration_ms, unhandled, @max_routes)
+      end
+    end
+
+    # failed: the attempt raised (or was retried or discarded by the job);
+    # discarded: the job will not run again.
+    def record_job(job_class:, duration_ms:, failed: false, discarded: false, queue_latency_ms: nil)
+      started_at = period_start(@clock.call)
+      @mutex.synchronize do
+        (@periods[started_at] ||= Period.new(started_at))
+          .record_job(job_class.to_s, failed, discarded, duration_ms, queue_latency_ms, @max_routes)
+      end
+    end
+
+    # A job that will not run again, recorded without another attempt (for
+    # example a Sidekiq job that exhausted its retries).
+    def record_discard(job_class:)
+      started_at = period_start(@clock.call)
+      @mutex.synchronize { (@periods[started_at] ||= Period.new(started_at)).record_discard(job_class.to_s, @max_routes) }
+    end
+
+    def record_checkpoint(name:, count: 1)
+      started_at = period_start(@clock.call)
+      @mutex.synchronize { (@periods[started_at] ||= Period.new(started_at)).record_checkpoint(name, count) }
+    end
+
+    # A representative backtrace is kept only the first time this process
+    # sees a fingerprint, and at most 5 per period.
+    def record_exception(details, source: nil, handled: false, backtrace: nil)
+      started_at = period_start(@clock.call)
+      @mutex.synchronize do
+        period = (@periods[started_at] ||= Period.new(started_at))
+        new_here = @seen_fingerprints.add?(details["fingerprint"])
+        keep_trace = new_here && period.exceptions.count { |_, e| e["backtrace"] } < MAX_BACKTRACES
+        period.record_exception(details, source, handled, keep_trace ? backtrace : nil)
+      end
+    end
+
+    # Completed periods, oldest first. Minutes with no requests are returned
+    # as empty periods, so idle processes still report their release.
+    # include_current also closes the in-progress minute (used at shutdown).
+    def drain(include_current: false, max_periods: 10)
+      current = period_start(@clock.call)
+      last = include_current ? current : current - PERIOD_SECONDS
+
+      @mutex.synchronize do
+        first = [ @last_drained_at + PERIOD_SECONDS, last - (max_periods - 1) * PERIOD_SECONDS ].max
+        drained = (first.to_i..last.to_i).step(PERIOD_SECONDS).map do |seconds|
+          started_at = Time.at(seconds).utc
+          @periods.delete(started_at) || Period.new(started_at)
+        end
+        @periods.delete_if { |started_at, _| started_at <= last }
+        @last_drained_at = last if drained.any?
+        drained
+      end
+    end
+
+    private
+      def period_start(time)
+        Time.at(time.to_i - (time.to_i % PERIOD_SECONDS)).utc
+      end
+  end
+end

data/lib/deployangel/core/buffer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  # Bounded FIFO of payloads waiting to be sent. When full, the oldest
+  # payload is dropped: losing telemetry is always preferable to growing
+  # memory in the customer's process.
+  class Buffer
+    attr_reader :dropped
+
+    def initialize(limit)
+      @limit = limit
+      @items = []
+      @dropped = 0
+      @mutex = Mutex.new
+    end
+
+    def push(item)
+      @mutex.synchronize do
+        @items << item
+        while @items.size > @limit
+          @items.shift
+          @dropped += 1
+        end
+      end
+    end
+
+    def shift
+      @mutex.synchronize { @items.shift }
+    end
+
+    def unshift(item)
+      @mutex.synchronize { @items.unshift(item) if @items.size < @limit }
+    end
+
+    def size
+      @mutex.synchronize { @items.size }
+    end
+
+    def clear
+      @mutex.synchronize { @items.clear }
+    end
+  end
+end

data/lib/deployangel/core/fingerprint.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module DeployAngel
+  # Exception fingerprint algorithm v1. Stable across deployments:
+  # no line numbers, no messages, no gem versions, no absolute paths, and no
+  # Ruby-version-specific label formatting.
+  module Fingerprint
+    VERSION = 1
+    GEM_PATH = %r{/gems/([^/]+?)-\d[^/]*/(.+)\z}
+    MESSAGE_PLACEHOLDERS = [
+      [ /\b[\w.+-]+@[\w-]+\.[\w.-]+\b/, "<email>" ],
+      [ /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i, "<uuid>" ],
+      [ /\b0x[0-9a-f]+\b|\b[0-9a-f]{16,}\b/i, "<hex>" ],
+      [ /(["'`]).*?\1/, "<string>" ],
+      [ /\b\d+(\.\d+)?\b/, "<n>" ]
+    ].freeze
+    MAX_MESSAGE = 200
+    MAX_BACKTRACE = 20
+
+    module_function
+
+    def for(exception, root:)
+      frame = top_frame(exception, root: root)
+      {
+        "fingerprint" => Digest::SHA256.hexdigest([ "v#{VERSION}", exception.class.name, frame ].join("|"))[0, 32],
+        "fingerprint_version" => VERSION,
+        "exception_class" => exception.class.name,
+        "message" => normalize_message(exception.message),
+        "top_frame" => frame,
+        "app_frame" => app_frame?(frame)
+      }
+    end
+
+    # First application frame as "relative/path.rb#method", else the first
+    # frame normalized as "gem/path/in/gem.rb#method".
+    def top_frame(exception, root:)
+      frames = locations(exception)
+      app = frames.find { |path, _| app_path?(path, root) }
+      path, label = app || frames.first
+      return "unknown" unless path
+
+      "#{normalize_path(path, root)}##{label}"
+    end
+
+    # Application frames only, relative to the root.
+    def backtrace(exception, root:)
+      locations(exception).select { |path, _| app_path?(path, root) }.first(MAX_BACKTRACE)
+        .map { |path, label| "#{normalize_path(path, root)}##{label}" }
+    end
+
+    def normalize_message(message)
+      text = message.to_s.lines.first.to_s.strip
+      MESSAGE_PLACEHOLDERS.each { |pattern, placeholder| text = text.gsub(pattern, placeholder) }
+      text[0, MAX_MESSAGE]
+    end
+
+    def app_frame?(frame)
+      frame.start_with?("app/", "lib/", "config/")
+    end
+
+    def locations(exception)
+      if exception.backtrace_locations
+        exception.backtrace_locations.map { |location| [ location.absolute_path || location.path, location.base_label ] }
+      else
+        Array(exception.backtrace).map do |line|
+          path, _, label = line.partition(":in ")
+          [ path.sub(/:\d+\z/, ""), label.delete("`'").split(/[#.]/).last.to_s.sub(/\A(block|rescue|ensure) (\(\d+ levels\) )?in /, "") ]
+        end
+      end
+    end
+
+    def app_path?(path, root)
+      return false unless root && path&.start_with?(root)
+
+      relative = path.delete_prefix(root).delete_prefix("/")
+      !relative.start_with?("vendor/", "node_modules/", "tmp/")
+    end
+
+    def normalize_path(path, root)
+      if root && path.start_with?(root)
+        path.delete_prefix(root).delete_prefix("/")
+      elsif (match = GEM_PATH.match(path))
+        "#{match[1]}/#{match[2]}"
+      else
+        File.basename(path.to_s)
+      end
+    end
+  end
+end

data/lib/deployangel/core/histogram.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  # Sparse log-scale latency histogram, scheme log1.1_ms_v1 (Agent Protocol
+  # v1). The agent only counts; percentiles are computed in the cloud after
+  # merging every process, because percentiles cannot be averaged.
+  class Histogram
+    SCHEME = "log1.1_ms_v1"
+    LOG_GAMMA = Math.log(1.1)
+    MAX_BUCKET = 400
+
+    def self.bucket_for(milliseconds)
+      return 0 if milliseconds < 1
+
+      (Math.log(milliseconds) / LOG_GAMMA).ceil.clamp(0, MAX_BUCKET)
+    end
+
+    def initialize
+      @counts = Hash.new(0)
+    end
+
+    def record(milliseconds)
+      @counts[self.class.bucket_for(milliseconds)] += 1
+    end
+
+    def merge!(other)
+      other.counts.each { |bucket, count| @counts[bucket] += count }
+      self
+    end
+
+    def count
+      @counts.values.sum
+    end
+
+    def to_protocol
+      { "scheme" => SCHEME, "counts" => @counts.sort.to_h.transform_keys(&:to_s) }
+    end
+
+    protected
+      attr_reader :counts
+  end
+end

data/lib/deployangel/core/instance.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "socket"
+
+module DeployAngel
+  # One OS process. The random suffix is regenerated after fork, so a forked
+  # child never reuses its parent's identity.
+  class Instance
+    attr_reader :id, :host, :pid, :process_type, :started_at
+
+    def initialize(env: ENV, now: Time.now.utc)
+      @host = env["DYNO"] || Socket.gethostname
+      @pid = Process.pid
+      @process_type = env["DYNO"]&.split(".")&.first
+      @id = "#{@host}:#{@pid}:#{SecureRandom.hex(3)}"
+      @started_at = now
+    end
+
+    def to_protocol
+      {
+        "id" => id,
+        "host" => host,
+        "pid" => pid,
+        "process_type" => process_type,
+        "started_at" => started_at.iso8601
+      }.compact
+    end
+  end
+end

data/lib/deployangel/core/protocol.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  # Builds Agent Protocol v1 telemetry payloads. Only mergeable values are
+  # sent: counts and histograms, never percentiles or rates.
+  module Protocol
+    VERSION = 1
+    module_function
+
+    def telemetry(period, instance:, release:, runtime:, capabilities: %w[http])
+      {
+        "protocol_version" => VERSION,
+        "agent" => { "name" => "deployangel-ruby", "version" => DeployAngel::VERSION },
+        "runtime" => runtime,
+        "instance" => instance.to_protocol,
+        "release" => release.to_protocol,
+        "capabilities" => capabilities,
+        "period" => { "started_at" => period.started_at.iso8601, "duration_seconds" => Aggregator::PERIOD_SECONDS },
+        "http" => {
+          "requests" => period.requests,
+          "status_counts" => period.status_counts.to_h,
+          "unhandled_exceptions" => period.unhandled_exceptions,
+          "latency_histogram" => period.histogram.to_protocol
+        },
+        "routes" => period.routes.map do |key, route|
+          {
+            "key" => key,
+            "requests" => route.requests,
+            "status_counts" => route.status_counts.to_h,
+            "latency_histogram" => route.histogram.to_protocol
+          }
+        end,
+        "exceptions" => period.exceptions.values.map { |e| e.merge("sources" => e["sources"].to_h).compact },
+        "exceptions_truncated" => period.exceptions_truncated,
+        "jobs" => job_stats(period.jobs),
+        "job_classes" => period.job_classes.map { |key, stats| { "key" => key }.merge(job_stats(stats)) },
+        "checkpoints" => period.checkpoints.map { |key, count| { "key" => key, "count" => count } }
+      }
+    end
+
+    def job_stats(stats)
+      {
+        "processed" => stats.processed,
+        "failed" => stats.failed,
+        "discarded" => stats.discarded,
+        "duration_histogram" => stats.duration.to_protocol,
+        "queue_latency_histogram" => stats.queue_latency.to_protocol
+      }
+    end
+
+    def runtime(framework: nil, framework_version: nil)
+      {
+        "language" => "ruby",
+        "language_version" => RUBY_VERSION,
+        "framework" => framework,
+        "framework_version" => framework_version
+      }.compact
+    end
+  end
+end

data/lib/deployangel/core/release.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  # Which release this process is running, resolved once at boot so that
+  # telemetry can be attributed to a deployment.
+  class Release < Struct.new(:version, :commit, :source)
+    COMMIT_FORMAT = /\A[0-9a-f]{7,40}\z/
+
+    # Order: explicit configuration, Heroku dyno metadata, the hosting
+    # platform's own variables (Kamal, Render, Fly.io, Railway, Coolify, and
+    # Dokku's GIT_REV), then a REVISION file.
+    def self.resolve(config:, env: ENV, root: nil)
+      if present?(config.release_version) || present?(config.revision)
+        build(config.release_version, config.revision, "config")
+      elsif present?(env["HEROKU_RELEASE_VERSION"]) || present?(env["HEROKU_SLUG_COMMIT"])
+        build(env["HEROKU_RELEASE_VERSION"], env["HEROKU_SLUG_COMMIT"], "heroku_dyno_metadata")
+      elsif present?(env["KAMAL_VERSION"])
+        kamal(env["KAMAL_VERSION"])
+      elsif present?(env["RENDER_GIT_COMMIT"])
+        build(nil, env["RENDER_GIT_COMMIT"], "render")
+      elsif (tag = fly_tag(env["FLY_IMAGE_REF"]))
+        build(tag, nil, "fly")
+      elsif present?(env["RAILWAY_GIT_COMMIT_SHA"]) || present?(env["RAILWAY_DEPLOYMENT_ID"])
+        railway(env)
+      elsif present?(env["SOURCE_COMMIT"]) && present?(env["COOLIFY_CONTAINER_NAME"] || env["COOLIFY_RESOURCE_UUID"])
+        build(nil, env["SOURCE_COMMIT"], "coolify")
+      # Dokku sets GIT_REV, but the name is generic, so the source says so.
+      elsif present?(env["GIT_REV"])
+        build(nil, env["GIT_REV"], "git_rev")
+      elsif root && File.file?(revision_path = File.join(root, "REVISION"))
+        build(nil, File.read(revision_path, 100), "revision_file")
+      else
+        new(nil, nil, "unknown")
+      end
+    end
+
+    # Kamal sets KAMAL_VERSION in every app container: the git commit by
+    # default, with "_uncommitted_<random>" added for a dirty working tree,
+    # or a version you declared. A plain commit is reported as the commit,
+    # so it matches deploys registered by commit; anything else is the
+    # version, with the commit it starts with.
+    def self.kamal(value)
+      value = value.to_s.strip
+      plain_commit = value.downcase.match?(COMMIT_FORMAT)
+      build(plain_commit ? nil : value, value.split("_", 2).first, "kamal")
+    end
+
+    # Railway sets the commit for deploys from GitHub. Others, such as
+    # `railway up`, only have a deployment ID, which identifies the release.
+    def self.railway(env)
+      if present?(env["RAILWAY_GIT_COMMIT_SHA"])
+        build(nil, env["RAILWAY_GIT_COMMIT_SHA"], "railway")
+      else
+        build(env["RAILWAY_DEPLOYMENT_ID"], nil, "railway")
+      end
+    end
+
+    # Fly.io tags each deploy's image ("registry.fly.io/shop:deployment-01H9…"),
+    # and the tag identifies the release. Fly.io sets no commit; pass one in
+    # with DEPLOYANGEL_REVISION for commit-level change tracking.
+    def self.fly_tag(image_ref)
+      name = image_ref.to_s.strip.split("@", 2).first.to_s.split("/").last.to_s
+      tag = name.split(":", 2)[1].to_s.delete_prefix("deployment-")
+      tag unless tag.empty?
+    end
+
+    # The cloud rejects malformed commits, which would drop every payload,
+    # so anything that is not a hex SHA is left out.
+    def self.build(version, commit, source)
+      commit = commit.to_s.strip.downcase
+      new(present?(version) ? version.to_s.strip[0, 100] : nil,
+        commit.match?(COMMIT_FORMAT) ? commit : nil,
+        source)
+    end
+
+    def self.present?(value)
+      !value.to_s.strip.empty?
+    end
+
+    def unknown?
+      version.nil? && commit.nil?
+    end
+
+    def to_protocol
+      { "version" => version, "commit" => commit, "source" => source }
+    end
+  end
+end

data/lib/deployangel/core/transport.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "zlib"
+require "stringio"
+
+module DeployAngel
+  # Sends gzipped JSON to DeployAngel. Only ever called from the background
+  # thread, never from a request.
+  class Transport
+    Result = Struct.new(:outcome, :status, :retry_after, :body) do
+      def ok?
+        outcome == :ok
+      end
+    end
+
+    def initialize(config)
+      @config = config
+    end
+
+    # :ok (2xx), :retry (network error or 5xx), or :drop (any other status,
+    # including 429 rate limiting, which the agent honors by pausing).
+    def post(path, body)
+      uri = URI.join(@config.endpoint.end_with?("/") ? @config.endpoint : "#{@config.endpoint}/", path.delete_prefix("/"))
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{@config.token}"
+      request["Content-Type"] = "application/json"
+      request["Content-Encoding"] = "gzip"
+      request["User-Agent"] = "deployangel-ruby/#{DeployAngel::VERSION} ruby/#{RUBY_VERSION}"
+      request.body = gzip(JSON.generate(body))
+
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+        open_timeout: @config.open_timeout, read_timeout: @config.read_timeout,
+        write_timeout: @config.read_timeout) { |http| http.request(request) }
+      classify(response)
+    rescue StandardError => e
+      Result.new(:retry, nil, nil).tap { @config.logger&.debug("DeployAngel transport error: #{e.class}: #{e.message}") }
+    end
+
+    private
+      def classify(response)
+        status = response.code.to_i
+        case status
+        when 200..299 then Result.new(:ok, status, nil, parse_body(response.body))
+        when 500..599 then Result.new(:retry, status, nil)
+        else Result.new(:drop, status, (response["Retry-After"].to_i if status == 429))
+        end
+      end
+
+      def parse_body(body)
+        body.to_s.empty? ? {} : JSON.parse(body)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def gzip(string)
+        io = StringIO.new
+        writer = Zlib::GzipWriter.new(io)
+        writer.write(string)
+        writer.close
+        io.string
+      end
+  end
+end

data/lib/deployangel/fork_hook.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module DeployAngel
+  # Resets the agent in forked children (Puma cluster mode, Sidekiq swarm,
+  # etc.) using Process._fork, available since Ruby 3.1.
+  module ForkHook
+    def _fork
+      pid = super
+      DeployAngel.after_fork if pid.zero?
+      pid
+    end
+  end
+end
+
+Process.singleton_class.prepend(DeployAngel::ForkHook)