rails_pulse 0.4.2 → 0.5.0.pre.2

data/app/services/rails_pulse/cloud/batch.rb

@@ -0,0 +1,83 @@
+require "zlib"
+require "securerandom"
+
+module RailsPulse
+  module Cloud
+    # Items wrapped in the envelope the sync contract defines, split so no
+    # batch exceeds what Cloud accepts. Each batch gets its own `batch_id`
+    # when it is built; a retry resends the same one, which is how Cloud
+    # tells a resend from new data.
+    class Batch
+      CONTRACT = 1
+      MAX_ITEMS = 5_000
+      MAX_COMPRESSED_BYTES = 1_000_000
+
+      attr_reader :envelope, :items, :batch_id
+
+      # @param items [Array<Hash>]
+      # @param envelope [Hash] the fields every batch repeats (see .envelope)
+      # @return [Array<Batch>] one or more batches, none over the limits
+      def self.build(items, envelope:)
+        items.each_slice(MAX_ITEMS).flat_map { |slice| fitting(slice, envelope) }
+      end
+
+      # Halves a batch until each part compresses under the limit. A single
+      # item larger than the limit is left as a batch of one; Cloud refuses
+      # it, which is the right outcome for an item that cannot be sent.
+      def self.fitting(items, envelope)
+        batch = new(items, envelope: envelope)
+        return [ batch ] if items.size <= 1 || batch.compressed_bytesize <= MAX_COMPRESSED_BYTES
+
+        middle = items.size / 2
+        fitting(items.first(middle), envelope) + fitting(items.drop(middle), envelope)
+      end
+
+      # The envelope fields that identify where a batch came from.
+      def self.envelope(application:, environment:, installation_id:)
+        {
+          contract: CONTRACT,
+          application: application,
+          environment: environment,
+          installation_id: installation_id,
+          time_zone: Time.zone.tzinfo.name,
+          gem_version: RailsPulse::VERSION,
+          rails_version: Rails.version,
+          ruby_version: RUBY_VERSION,
+          database_adapter: RailsPulse::ApplicationRecord.connection_db_config.adapter.to_s
+        }
+      end
+
+      # A UUID version 7: a millisecond timestamp followed by random bits, so
+      # batch IDs sort by when they were built.
+      def self.uuid_v7(time = Time.current)
+        return SecureRandom.uuid_v7 if SecureRandom.respond_to?(:uuid_v7)
+
+        milliseconds = (time.to_r * 1000).to_i
+        bytes = [ milliseconds >> 16, milliseconds & 0xffff ].pack("Nn").bytes + SecureRandom.random_bytes(10).bytes
+        bytes[6] = (bytes[6] & 0x0f) | 0x70
+        bytes[8] = (bytes[8] & 0x3f) | 0x80
+        hex = bytes.pack("C*").unpack1("H*")
+        [ hex[0, 8], hex[8, 4], hex[12, 4], hex[16, 4], hex[20, 12] ].join("-")
+      end
+
+      def initialize(items, envelope:, batch_id: self.class.uuid_v7, sent_at: Time.current)
+        @items = items
+        @envelope = envelope
+        @batch_id = batch_id
+        @sent_at = sent_at
+      end
+
+      def to_h
+        { contract: CONTRACT, batch_id: @batch_id, sent_at: @sent_at.utc.iso8601, **@envelope.except(:contract), items: @items }
+      end
+
+      def to_json(*)
+        to_h.to_json
+      end
+
+      def compressed_bytesize
+        Zlib.gzip(to_json).bytesize
+      end
+    end
+  end
+end

data/app/services/rails_pulse/cloud/client.rb

@@ -0,0 +1,68 @@
+require "net/http"
+require "zlib"
+require "json"
+
+module RailsPulse
+  module Cloud
+    # Posts one batch to Rails Pulse Cloud. Gzipped JSON, the contract
+    # version in a header, and short timeouts: it runs in a background job,
+    # but a hung connection would still hold a worker.
+    class Client
+      OPEN_TIMEOUT = 5
+      READ_TIMEOUT = 15
+      PATH = "/v1/batches".freeze
+
+      Response = Struct.new(:status, :body, :headers, keyword_init: true) do
+        # The JSON error body Cloud sends, or an empty hash.
+        def error
+          parsed = JSON.parse(body.to_s)
+          parsed.is_a?(Hash) ? parsed : {}
+        rescue JSON::ParserError
+          {}
+        end
+
+        def message
+          error["message"].presence || "HTTP #{status}"
+        end
+
+        def header(name)
+          headers[name.downcase]
+        end
+      end
+
+      # Raised when Cloud could not be reached or did not answer in time.
+      class Unavailable < StandardError; end
+
+      def initialize(settings = RailsPulse.configuration.cloud)
+        @settings = settings
+      end
+
+      # @param body [String] the batch as JSON
+      # @return [Response]
+      def post(body)
+        uri = URI.join(@settings.url.to_s.chomp("/") + "/", PATH.delete_prefix("/"))
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{@settings.api_key}"
+        request["Content-Type"] = "application/json"
+        request["Content-Encoding"] = "gzip"
+        request["Rails-Pulse-Contract"] = Batch::CONTRACT.to_s
+        request["User-Agent"] = user_agent
+        request.body = Zlib.gzip(body)
+
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                   open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT, write_timeout: READ_TIMEOUT) do |http|
+          http.request(request)
+        end
+        Response.new(status: response.code.to_i, body: response.body, headers: response.each_header.to_h)
+      rescue Timeout::Error, SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse, EOFError => e
+        raise Unavailable, "#{e.class}: #{e.message}"
+      end
+
+      private
+
+      def user_agent
+        "rails_pulse/#{RailsPulse::VERSION} (ruby #{RUBY_VERSION}; rails #{Rails.version})"
+      end
+    end
+  end
+end

data/app/services/rails_pulse/cloud/combined_metrics.rb

@@ -0,0 +1,49 @@
+module RailsPulse
+  module Cloud
+    # Several summary rows of one hour folded into one item's metrics: the
+    # unmatched paths under one prefix, the routes or queries past the
+    # per-hour cap, or two stored routes that share a pattern. Counts, totals
+    # and status counts add up exactly, as do min, max, the mean and the
+    # standard deviation; percentiles are the count-weighted average of the
+    # rows', as SummaryService does when it rolls hours up into a day.
+    module CombinedMetrics
+      PERCENTILES = %i[p50_duration p95_duration p99_duration].freeze
+      COUNTS = %i[error_count success_count status_2xx status_3xx status_4xx status_5xx].freeze
+
+      module_function
+
+      # @param rows [Array<#[]>] summary rows, or hashes with the same keys
+      # @return [Hash] the metric fields of a summary item
+      def of(rows, counts: COUNTS)
+        rows = rows.reject { |row| row[:count].to_i.zero? }
+        count = rows.sum { |row| row[:count].to_i }
+        return { count: 0 } if count.zero?
+
+        weighted_mean_sum = rows.sum { |row| row[:count].to_i * row[:avg_duration].to_f }
+        {
+          count: count,
+          avg_duration: weighted_mean_sum / count,
+          min_duration: rows.filter_map { |row| row[:min_duration]&.to_f }.min,
+          max_duration: rows.filter_map { |row| row[:max_duration]&.to_f }.max,
+          total_duration: rows.sum { |row| row[:total_duration].to_f },
+          **PERCENTILES.index_with { |column| weighted(rows, column) },
+          stddev_duration: Statistics.pooled_stddev(
+            count: count,
+            within_sum: rows.sum { |row| (row[:count].to_i - 1) * (row[:stddev_duration].to_f**2) },
+            weighted_mean_sum: weighted_mean_sum,
+            weighted_square_sum: rows.sum { |row| row[:count].to_i * (row[:avg_duration].to_f**2) }
+          ),
+          **counts.index_with { |column| rows.sum { |row| row[column].to_i } }
+        }
+      end
+
+      def weighted(rows, column)
+        present = rows.reject { |row| row[column].nil? }
+        weight = present.sum { |row| row[:count].to_i }
+        return nil if weight.zero?
+
+        present.sum { |row| row[column].to_f * row[:count].to_i } / weight
+      end
+    end
+  end
+end

data/app/services/rails_pulse/cloud/health_item.rb

@@ -0,0 +1,77 @@
+module RailsPulse
+  module Cloud
+    # The `health` item for one minute: request volume, errors and response
+    # time across the application, exceptions raised, and each host's
+    # writers. It runs every minute, so every read is a range on an indexed
+    # occurred_at column over that minute alone.
+    class HealthItem
+      def self.for_minute_before(time = Time.current)
+        window_start = (time - 1.minute).beginning_of_minute
+        new(window_start).item
+      end
+
+      def initialize(window_start)
+        @window = window_start...(window_start + 1.minute)
+      end
+
+      def item
+        durations, statuses = request_rows
+        sorted = durations.compact.sort
+        {
+          type: "health",
+          window_start: @window.begin.utc.iso8601,
+          window_end: @window.end.utc.iso8601,
+          request_count: durations.size,
+          error_count: statuses.count { |status| status.to_i >= 500 },
+          avg_duration: sorted.any? ? sorted.sum.to_f / sorted.size : nil,
+          p95_duration: Statistics.calculate_percentile(sorted, 0.95)&.to_f,
+          exception_count: exception_count,
+          hosts: hosts
+        }
+      end
+
+      private
+
+      def request_rows
+        rows = Request.where(occurred_at: @window).pluck(:duration, :status)
+        [ rows.map(&:first), rows.map(&:last) ]
+      end
+
+      def exception_count
+        return 0 unless ExceptionOccurrence.table_exists?
+
+        ExceptionOccurrence.where(occurred_at: @window).count
+      end
+
+      # One entry per host from the writer heartbeats: the processes that
+      # reported recently, their latest queue depth, and requests dropped
+      # inside the minute. Process IDs are not sent.
+      def hosts
+        return [] unless Event.table_available?
+
+        recent = WriterHeartbeat.events
+          .where(occurred_at: (@window.end - WriterHeartbeat::LIVE_WINDOW)...@window.end)
+          .recent
+          .to_a
+        latest_per_process = recent.uniq(&:subject)
+
+        latest_per_process.group_by { |event| host_of(event) }.map do |host, events|
+          subjects = events.map(&:subject)
+          {
+            host: host,
+            processes: events.size,
+            queue_depth: events.sum { |event| event.metadata_hash["queue_depth"].to_i },
+            dropped: recent.select { |event| subjects.include?(event.subject) && @window.cover?(event.occurred_at) }.sum { |event| event.value.to_i },
+            last_heartbeat_at: events.map(&:occurred_at).max.utc.iso8601
+          }
+        end.sort_by { |entry| entry[:host].to_s }
+      end
+
+      # config.cloud.host_label when the host set one, otherwise its hostname.
+      def host_of(event)
+        metadata = event.metadata_hash
+        metadata["host_label"].presence || metadata["hostname"].presence || event.subject.to_s.rpartition(":").first
+      end
+    end
+  end
+end

data/app/services/rails_pulse/cloud/path_prefix.rb

@@ -0,0 +1,50 @@
+module RailsPulse
+  module Cloud
+    # The prefix a request the router did not recognise is sent to Cloud
+    # under. The stored path is the raw URL, which can carry tokens, IDs or
+    # email addresses, so only a first segment that looks like code
+    # (`/wp-admin`, `/.env`) survives, and everything after it becomes `/*`.
+    #
+    #   PathPrefix.for("/wp-admin/setup.php")          # => "/wp-admin/*"
+    #   PathPrefix.for("/wp-login.php")                # => "/wp-login.php"
+    #   PathPrefix.for("/users/jane.doe@example.com")  # => "/users/*"
+    #   PathPrefix.for("/8f3a9c1e2b7d")                # => "/*"
+    module PathPrefix
+      # Every prefix past the busiest in an hour is combined under this one.
+      OTHER = "*".freeze
+
+      SAFE_SEGMENT = /\A[A-Za-z0-9._-]{1,40}\z/
+      DIGIT_RUN = /\d{4}/
+      HEXADECIMAL = /\A\h{8,}\z/
+      UUID = /\h{8}-\h{4}-\h{4}-\h{4}-\h{12}/
+      EMAIL_MARKERS = [ "@", "%40" ].freeze
+
+      module_function
+
+      def for(path)
+        path = path.to_s
+        return "/" if path == "/"
+
+        first, rest = path.delete_prefix("/").split("/", 2)
+        return "/*" unless safe_segment?(first)
+
+        rest.nil? ? "/#{first}" : "/#{first}/*"
+      end
+
+      # True for a path segment that reads as part of the application rather
+      # than something a user supplied.
+      def safe_segment?(segment)
+        return false unless segment.is_a?(String) && segment.match?(SAFE_SEGMENT)
+
+        !identifier?(segment)
+      end
+
+      def identifier?(segment)
+        segment.match?(DIGIT_RUN) ||
+          segment.match?(HEXADECIMAL) ||
+          segment.match?(UUID) ||
+          EMAIL_MARKERS.any? { |marker| segment.include?(marker) }
+      end
+    end
+  end
+end

data/app/services/rails_pulse/cloud/preview.rb

@@ -0,0 +1,83 @@
+require "json"
+
+module RailsPulse
+  module Cloud
+    # What `rails rails_pulse:cloud:preview` prints: the batches the next
+    # hourly sync would queue, and the health update for the minute just
+    # ended. It reads the same plan and builds items with the same code as
+    # Sync, so the preview cannot drift from what is sent, and it writes
+    # nothing: no installation row, no buffered batch, no request.
+    class Preview
+      METADATA_NOTICE = "Deployment metadata is sent as recorded: everything your deploy script puts in it goes to Rails Pulse Cloud.".freeze
+
+      def initialize(settings: RailsPulse.configuration.cloud, now: Time.current)
+        @settings = settings
+        @now = now
+        @installation = Installation.table_exists? ? Installation.existing : nil
+      rescue ActiveRecord::ActiveRecordError
+        @installation = nil
+      end
+
+      def plan
+        @plan ||= Sync.new(settings: @settings, now: @now).plan_for(@installation)
+      end
+
+      def batches
+        route_patterns = RoutePattern.new
+        items = plan.hours.flat_map do |hour|
+          SummaryItems.new(hour, adapter: envelope[:database_adapter], route_patterns: route_patterns).items
+        end
+        items += RecordItems.exception_groups_updated(plan.exception_groups)
+        items += RecordItems.deployments_updated(plan.deployments)
+        Batch.build(items, envelope: envelope)
+      end
+
+      def health_batch
+        Batch.new([ HealthItem.for_minute_before(@now) ], envelope: envelope, sent_at: @now)
+      end
+
+      def render
+        lines = [ "Rails Pulse Cloud preview", "" ]
+        lines << status_line
+        lines << "Installation ID: assigned on the first sync" if @installation.nil?
+        lines << ""
+
+        built = batches
+        if plan.hours.empty?
+          lines << "No newly summarized hour to send. Is SummaryJob scheduled?"
+        else
+          lines << "Next hourly sync: #{plan.hours.map { |hour| hour.utc.iso8601 }.join(', ')}."
+        end
+        lines << "#{pluralize(built.sum { |batch| batch.items.size }, 'item')} in #{pluralize(built.size, 'batch')}."
+        lines << METADATA_NOTICE
+        lines << ""
+        built.each { |batch| lines << JSON.pretty_generate(batch.to_h) }
+
+        lines << ""
+        lines << "Health update for the minute just ended, sent every minute and never buffered:"
+        lines << JSON.pretty_generate(health_batch.to_h)
+        lines.join("\n") + "\n"
+      end
+
+      private
+
+      def envelope
+        @envelope ||= Batch.envelope(application: @settings.application, environment: @settings.environment,
+                                     installation_id: @installation&.installation_id)
+      end
+
+      def status_line
+        if @settings.enabled?
+          "Sending to #{@settings.url} as #{@settings.application} (#{@settings.environment})."
+        else
+          "Not sending: set config.cloud.api_key and config.cloud.application to turn Rails Pulse Cloud on. " \
+            "Until then no network calls are made."
+        end
+      end
+
+      def pluralize(count, word)
+        "#{count} #{count == 1 ? word : word.pluralize}"
+      end
+    end
+  end
+end

data/app/services/rails_pulse/cloud/query_shape.rb

@@ -0,0 +1,195 @@
+module RailsPulse
+  module Cloud
+    # What Cloud receives for a query, rebuilt from the normalised SQL by
+    # allow-list. Normalisation replaces the literals it recognises with `?`,
+    # so a literal in a form it does not recognise stays in the stored SQL;
+    # here every token must be a keyword, an identifier, an operator, a
+    # number or a placeholder, and a query with anything else has no shape.
+    #
+    #   shape = QueryShape.new('SELECT "users".* FROM "users" WHERE "users"."email" = ? LIMIT ?')
+    #   shape.sql_shape  # => "SELECT users.* FROM users WHERE users.email = ? LIMIT ?"
+    #   shape.label      # => "SELECT users"
+    #
+    #   QueryShape.new("SELECT * FROM notes WHERE body = $$jane@example.com$$").sql_shape  # => nil
+    class QueryShape
+      MAX_LENGTH = 2_000
+      MAX_LABEL_TABLES = 5
+
+      IDENTIFIER = /[A-Za-z_][A-Za-z0-9_$]*/
+      BARE_IDENTIFIER = /\A#{IDENTIFIER}\z/
+      NUMBER = /\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/
+      OPERATOR = %r{[=<>!+\-*/%:|]+}
+      PUNCTUATION = /[.,();]/
+      PLACEHOLDER = /\?|\$\d+/
+      # Comments carry no shape, and query log tags put request IDs in them.
+      COMMENT = %r{/\*.*?(?:\*/|\z)|--[^\n]*}m
+
+      # Keywords after which the next name is a table.
+      TABLE_KEYWORDS = %w[FROM JOIN INTO UPDATE].freeze
+
+      # Keywords that take a parenthesised list, so `IN (?, ?)` is not
+      # rendered like a function call.
+      KEYWORDS_BEFORE_PARENTHESIS = %w[
+        ALL AND ANY AS EXISTS FROM IN INTO JOIN LATERAL NOT ON OR SELECT SET SOME THEN UNION USING VALUES WHEN WHERE
+      ].freeze
+
+      # MySQL quotes identifiers with backticks; a double-quoted token there
+      # is a string, whatever it contains.
+      def self.for_adapter(sql, adapter)
+        new(sql, double_quotes_are_strings: adapter.to_s.match?(/mysql|trilogy/i))
+      end
+
+      def initialize(sql, double_quotes_are_strings: false)
+        @sql = sql.to_s.gsub(COMMENT, " ")
+        @double_quotes_are_strings = double_quotes_are_strings
+      end
+
+      # The shape, or nil when any token is not on the allow-list.
+      def sql_shape
+        return @sql_shape if defined?(@sql_shape)
+
+        @sql_shape = tokens.any? { |kind, _| kind == :unsafe } ? nil : render.first(MAX_LENGTH)
+      end
+
+      # The statement type and up to five table names, always available
+      # because it is built only from tokens that pass.
+      def label
+        first_kind, first_text = tokens.first
+        statement = first_kind == :word ? first_text.upcase : "QUERY"
+        tables = table_names
+        tables.empty? ? statement : "#{statement} #{tables.join(', ')}"
+      end
+
+      private
+
+      # [[kind, text], ...] where kind is :word, :name (a quoted identifier,
+      # unquoted), :number, :placeholder, :operator or :unsafe.
+      def tokens
+        @tokens ||= begin
+          scanner = StringScanner.new(@sql)
+          result = []
+          until scanner.eos?
+            next if scanner.skip(/\s+/)
+
+            result << next_token(scanner)
+          end
+          result
+        end
+      end
+
+      def next_token(scanner)
+        if (text = scanner.scan(IDENTIFIER)) then [ :word, text ]
+        elsif scanner.scan(NUMBER) then [ :number, "?" ]
+        elsif (text = scanner.scan(PLACEHOLDER)) then [ :placeholder, "?" ]
+        elsif (text = scanner.scan(/"(?:[^"]|"")*"?/)) then quoted(text, '"')
+        elsif (text = scanner.scan(/`[^`]*`?/)) then quoted(text, "`")
+        elsif (text = scanner.scan(/'(?:[^']|'')*'?/)) then [ :unsafe, text ]
+        elsif (text = scanner.scan(PUNCTUATION)) then [ :operator, text ]
+        elsif (text = scanner.scan(OPERATOR)) then [ :operator, text ]
+        else [ :unsafe, scanner.getch ]
+        end
+      end
+
+      def quoted(text, quote)
+        return [ :unsafe, text ] if quote == '"' && @double_quotes_are_strings
+
+        content = text.delete_prefix(quote).delete_suffix(quote)
+        content.match?(BARE_IDENTIFIER) && text.end_with?(quote) && text.length > 1 ? [ :name, content ] : [ :unsafe, text ]
+      end
+
+      # Tokens rejoined with single spaces, except none around `.`, after `(`,
+      # before `)` and `,`, or between a function name and its `(`, with
+      # schema qualifiers dropped.
+      def render
+        output = +""
+        tokens = without_schemas
+        tokens.each_with_index do |token, index|
+          output << " " if index.positive? && space_between?(tokens[index - 1], token, index > 1 ? tokens[index - 2] : nil)
+          output << token.last
+        end
+        output
+      end
+
+      def space_between?(previous, token, earlier)
+        before = previous.last
+        text = token.last
+        return false if before == "." || text == "." || before == "(" || text == ")" || text == ","
+        return false if text == "(" && function_name?(previous, earlier)
+
+        true
+      end
+
+      # A word before `(` is a function call, unless it is a keyword or the
+      # table named after INTO (`INSERT INTO posts (title)`).
+      def function_name?(token, earlier)
+        kind, text = token
+        return false unless kind == :word && !KEYWORDS_BEFORE_PARENTHESIS.include?(text.upcase)
+
+        !(earlier && earlier.first == :word && TABLE_KEYWORDS.include?(earlier.last.upcase))
+      end
+
+      # A three-part name (schema.table.column) loses its schema anywhere; a
+      # two-part name right after FROM, JOIN, INTO or UPDATE is schema.table
+      # and loses its schema too. Apps with one schema per tenant name their
+      # customers there.
+      def without_schemas
+        list = tokens.dup
+        index = 0
+        result = []
+        while index < list.size
+          if qualified_name?(list, index, 3)
+            index += 2
+          elsif qualified_name?(list, index, 2) && table_position?(result)
+            index += 2
+          end
+          result << list[index]
+          index += 1
+        end
+        result
+      end
+
+      # A name of `parts` identifiers joined by dots starts at `index`.
+      def qualified_name?(list, index, parts)
+        (0...parts).all? do |part|
+          kind, text = list[index + (part * 2)]
+          dot = list[index + (part * 2) + 1]
+          name = %i[word name].include?(kind)
+          last = part == parts - 1
+          name && (last || dot&.last == ".") && (!last || text != "*")
+        end
+      end
+
+      def table_position?(result)
+        kind, text = result.last
+        kind == :word && TABLE_KEYWORDS.include?(text.upcase)
+      end
+
+      def table_names
+        names = []
+        tokens.each_with_index do |(kind, text), index|
+          next unless kind == :word && TABLE_KEYWORDS.include?(text.upcase)
+
+          name = table_after(index + 1)
+          names << name if name && !names.include?(name)
+          break if names.size >= MAX_LABEL_TABLES
+        end
+        names
+      end
+
+      # The table named after a keyword, with any schema dropped. Nil when
+      # what follows is not a plain name (a subquery, or anything unsafe).
+      def table_after(index)
+        name = nil
+        loop do
+          kind, text = tokens[index]
+          return name unless %i[word name].include?(kind)
+
+          name = text
+          return name unless tokens[index + 1]&.last == "."
+
+          index += 2
+        end
+      end
+    end
+  end
+end

data/app/services/rails_pulse/cloud/record_items.rb

@@ -0,0 +1,60 @@
+module RailsPulse
+  module Cloud
+    # Items for exception groups and deployments, the two records Cloud
+    # keeps whole rather than as hourly numbers. Each is sent when it
+    # changes: a group when its status or counts move, a deployment when it
+    # is recorded or finished.
+    module RecordItems
+      # Larger metadata is replaced rather than cut, so Cloud never shows a
+      # half of what the deploy script recorded.
+      METADATA_LIMIT = 4.kilobytes
+      TRUNCATED = { "truncated" => true }.freeze
+
+      module_function
+
+      # Items for the groups whose rows changed inside `window`.
+      def exception_groups_updated(window)
+        ExceptionGroup.where(updated_at: window).order(:id).map { |record| exception_group(record) }
+      end
+
+      # Items for the deployments recorded or finished inside `window`.
+      def deployments_updated(window)
+        Deployment.where(updated_at: window).order(:started_at, :id).map { |record| deployment(record) }
+      end
+
+      # The message is never sent: it is built from runtime values and can
+      # carry anything a user typed.
+      def exception_group(group)
+        {
+          type: "exception_group",
+          fingerprint: group.fingerprint,
+          exception_class: group.exception_class,
+          location: group.location,
+          status: group.status,
+          first_seen_at: group.first_seen_at&.utc&.iso8601,
+          last_seen_at: group.last_seen_at&.utc&.iso8601,
+          resolved_at: group.resolved_at&.utc&.iso8601,
+          occurrence_count: group.occurrence_count.to_i
+        }
+      end
+
+      # Metadata is sent as recorded: the deploy script decides what goes in
+      # it, and the preview task says so.
+      def deployment(deployment)
+        {
+          type: "deployment",
+          revision: deployment.revision,
+          started_at: deployment.started_at.utc.iso8601,
+          finished_at: deployment.finished_at&.utc&.iso8601,
+          metadata: metadata(deployment.metadata_hash)
+        }
+      end
+
+      def metadata(value)
+        return {} unless value.is_a?(Hash)
+
+        value.to_json.bytesize > METADATA_LIMIT ? TRUNCATED : value
+      end
+    end
+  end
+end