sentiero 1.0.0.alpha1

data/lib/sentiero/analytics/stats_aggregator.rb

@@ -0,0 +1,346 @@
+# frozen_string_literal: true
+
+require_relative "analyzer"
+require_relative "collectors/custom_tag_collector"
+require_relative "../user_agent"
+
+module Sentiero
+  module Analytics
+    class StatsAggregator < Analyzer
+      # Required here, not at file top: ResultBuilder reopens this class, and
+      # requiring it before the `< Analyzer` superclass is established would
+      # raise a superclass mismatch.
+      require_relative "stats_aggregator/result_builder"
+
+      TOP_LIST_LIMIT = 10
+      TOP_TAGS_LIMIT = 20
+      TOP_PROBLEMS_LIMIT = 5
+
+      NAVIGATION_TAG = "navigation"
+
+      INTERNAL_METADATA_KEYS = %w[userAgent url referrer viewport has_errors entry_url entry_referrer].freeze
+
+      MAX_NAV_KEYS = 200
+      MAX_METADATA_KEYS = 50
+      MAX_METADATA_VALUES_PER_KEY = 50
+      MAX_TAG_SERIES_KEYS = 200
+      MAX_OVERLAY_PROBLEMS = 200
+      MAX_OCCURRENCES_PER_PROBLEM = 500
+
+      DURATION_BUCKETS = [
+        ["0-30s", 30_000],
+        ["30s-2m", 120_000],
+        ["2-5m", 300_000],
+        ["5-15m", 900_000],
+        ["15m+", nil]
+      ].freeze
+
+      WEEK_BUCKET_THRESHOLD_DAYS = 45
+
+      def aggregate(range_days: 30, since: nil, until_time: nil, server_exception_overlay: false)
+        scan_cap = store.limits.analytics_max_scan_sessions
+        since ||= default_since(range_days, until_time)
+
+        acc = new_accumulator(since, until_time)
+        seen_sessions = {}
+
+        store.each_session_events(limit: scan_cap, since: since, until_time: until_time) do |summary, _window_id, events|
+          accumulate_window(acc, seen_sessions, summary, events)
+        end
+
+        finalize(acc, seen_sessions, scan_cap, overlay: server_exception_overlay)
+      end
+
+      # Derives BOTH the current-window aggregate and the equal-length
+      # prior-window aggregate from a SINGLE widened scan over
+      # [prior_since, until_time], partitioning each session into the current or
+      # prior bucket by its updated_at. Returns {current:, prior:}; prior is nil
+      # when no comparison is possible (zero-length window) or when the widened
+      # scan is truncated — in which case the current aggregate is recomputed
+      # from an exact single-window scan so the displayed numbers stay correct
+      # (deltas are dropped on truncation anyway).
+      def aggregate_with_prior(range_days: 30, since: nil, until_time: nil)
+        scan_cap = store.limits.analytics_max_scan_sessions
+        since ||= default_since(range_days, until_time)
+        window_until = until_time || Time.now.to_f
+        span = window_until - since
+
+        return {current: aggregate(since: since, until_time: until_time, server_exception_overlay: true), prior: nil} unless span > 0
+
+        prior_since = since - span
+        prior_until = since - 0.001
+
+        current = {acc: new_accumulator(since, until_time), seen: {}}
+        prior = {acc: new_accumulator(prior_since, prior_until), seen: {}}
+
+        store.each_session_events(limit: scan_cap, since: prior_since, until_time: until_time) do |summary, _window_id, events|
+          bucket = (summary[:updated_at] >= since) ? current : prior
+          accumulate_window(bucket[:acc], bucket[:seen], summary, events)
+        end
+
+        if current[:seen].size + prior[:seen].size >= scan_cap
+          return {current: aggregate(since: since, until_time: until_time, server_exception_overlay: true), prior: nil}
+        end
+
+        {
+          current: finalize(current[:acc], current[:seen], scan_cap, overlay: true),
+          prior: finalize(prior[:acc], prior[:seen], scan_cap, overlay: false)
+        }
+      end
+
+      private
+
+      def accumulate_window(acc, seen_sessions, summary, events)
+        session_id = summary[:session_id]
+        collect_session(acc, summary, seen_sessions) unless seen_sessions.key?(session_id)
+        update_entry_candidate(seen_sessions[session_id], events)
+        collect_events(acc, events)
+      end
+
+      def finalize(acc, seen_sessions, scan_cap, overlay:)
+        tally_entries(acc, seen_sessions)
+        overlay_truncated = overlay ? collect_server_overlay(acc) : false
+        ResultBuilder.new(store).build(acc, seen_sessions.size, scan_cap, overlay_truncated)
+      end
+
+      # range_days - 1: the start day is itself one of the range_days buckets.
+      def default_since(range_days, until_time)
+        end_date = (until_time ? Time.at(until_time) : Time.now).utc.to_date
+        start_date = end_date - (range_days - 1)
+        Time.utc(start_date.year, start_date.month, start_date.day).to_f
+      end
+
+      # Mutable bag of the running tallies for one aggregate scan. A Struct (not a
+      # Hash) so the ~24 fields are named accessors threaded through the tally_*
+      # methods rather than string-typed acc.key lookups.
+      Accumulator = Struct.new(
+        :event_types, :custom_tags, :browser_tags, :browsers, :devices,
+        :entry_pages, :entry_page_errors, :referrers, :duration_buckets,
+        :total_events, :durations, :since, :until_time,
+        :per_day_events, :per_day_sessions, :per_day_errors, :per_day_tags,
+        :per_day_server_errors, :nav_internal, :nav_external, :nav_texts,
+        :metadata_keys, :metadata_values, :sessions_with_errors,
+        keyword_init: true
+      )
+
+      def new_accumulator(since, until_time)
+        Accumulator.new(
+          event_types: Hash.new(0),
+          custom_tags: CustomTagCollector.new,
+          browser_tags: Hash.new(0),
+          browsers: Hash.new(0),
+          devices: Hash.new(0),
+          entry_pages: Hash.new(0),
+          entry_page_errors: Hash.new(0),
+          referrers: Hash.new(0),
+          duration_buckets: DURATION_BUCKETS.to_h { |label, _| [label, 0] },
+          total_events: 0,
+          durations: [],
+          since: since,
+          until_time: until_time,
+          per_day_events: Hash.new(0),
+          per_day_sessions: Hash.new(0),
+          per_day_errors: Hash.new(0),
+          per_day_tags: {},
+          per_day_server_errors: Hash.new(0),
+          nav_internal: Hash.new(0),
+          nav_external: Hash.new(0),
+          nav_texts: Hash.new(0),
+          metadata_keys: Hash.new(0),
+          metadata_values: {},
+          sessions_with_errors: 0
+        )
+      end
+
+      # Runs once per session (windows share metadata and one duration).
+      def collect_session(acc, summary, seen_sessions)
+        metadata = summary[:metadata] || {}
+        entry_url = metadata["entry_url"]
+        seen_sessions[summary[:session_id]] = {
+          entry_url: entry_url,
+          # A real entry_url is authoritative; a first-Meta href may only claim
+          # the slot when we started from nil.
+          entry_anchor: entry_url ? -Float::INFINITY : nil,
+          referrer: metadata["entry_referrer"] || metadata["referrer"],
+          has_errors: !!metadata["has_errors"]
+        }
+
+        tally_browser_device(acc, metadata["userAgent"])
+        acc.sessions_with_errors += 1 if metadata["has_errors"]
+
+        tally_metadata(acc, metadata)
+        record_duration(acc, summary)
+        record_session_day(acc, summary)
+      end
+
+      # Deferred until every window is seen: entry page is the first Meta href,
+      # not the metadata URL the recorder overwrites on each navigation.
+      # Same-origin referrers dropped so Top Referrers shows only acquisition.
+      def tally_entries(acc, seen_sessions)
+        seen_sessions.each_value do |state|
+          entry_url = state[:entry_url]
+          tally(acc.entry_pages, entry_url)
+          tally(acc.entry_page_errors, entry_url) if state[:has_errors]
+
+          tally(acc.referrers, state[:referrer]) unless same_origin?(state[:referrer], entry_url)
+        end
+      end
+
+      # Values are tracked only for keys that survived the key cap.
+      def tally_metadata(acc, metadata)
+        metadata.each do |key, value|
+          next unless key.is_a?(String) && !key.empty?
+          next if INTERNAL_METADATA_KEYS.include?(key)
+          next unless bounded_tally(acc.metadata_keys, key, MAX_METADATA_KEYS)
+
+          values = acc.metadata_values[key] ||= Hash.new(0)
+          bounded_tally(values, value.to_s, MAX_METADATA_VALUES_PER_KEY)
+        end
+      end
+
+      def collect_events(acc, events)
+        events.each do |event|
+          next unless in_window?(acc, event["timestamp"])
+
+          type = event["type"]
+          acc.event_types[type] += 1
+          acc.total_events += 1
+          tally_custom_tag(acc, event) if type == CUSTOM
+          record_event_day(acc, event)
+          record_error_day(acc, event) if error_event?(event)
+        end
+      end
+
+      # Clamps per-event tallies to [since, until_time]: an in-range session can
+      # carry out-of-window events that must not inflate totals. Events without a
+      # numeric timestamp are kept (unplaceable).
+      def in_window?(acc, timestamp_ms)
+        return true unless timestamp_ms.is_a?(Numeric)
+
+        ts = timestamp_ms / 1000.0
+        ts >= acc.since && (acc.until_time.nil? || ts <= acc.until_time)
+      end
+
+      def tally_browser_device(acc, user_agent)
+        browser = UserAgent.browser(user_agent)
+        device = UserAgent.device(user_agent)
+        acc.browsers[browser] += 1 if browser
+        acc.devices[device] += 1 if device
+      end
+
+      def tally_custom_tag(acc, event)
+        data = event["data"]
+        return unless data.is_a?(Hash)
+        tag = data["tag"]
+        return unless tag.is_a?(String)
+
+        tally_navigation(acc, data["payload"]) if tag == NAVIGATION_TAG
+
+        # Branch on #tally's return so browser_tags and per-day series share its
+        # gate (internal "__" annotations and the JS-error tag are excluded).
+        return unless acc.custom_tags.tally(tag)
+
+        acc.browser_tags[tag] += 1
+        record_tag_day(acc, tag, event["timestamp"])
+      end
+
+      # New series bounded by MAX_TAG_SERIES_KEYS; existing tags count past it.
+      def record_tag_day(acc, tag, timestamp_ms)
+        date = day_string(timestamp_ms)
+        return unless date
+
+        series = acc.per_day_tags[tag]
+        series = acc.per_day_tags[tag] = Hash.new(0) if series.nil? && acc.per_day_tags.size < MAX_TAG_SERIES_KEYS
+        series[date] += 1 if series
+      end
+
+      def tally_navigation(acc, payload)
+        return unless payload.is_a?(Hash)
+
+        bucket = payload["external"] ? acc.nav_external : acc.nav_internal
+        bounded_tally(bucket, payload["url"], MAX_NAV_KEYS)
+        bounded_tally(acc.nav_texts, payload["text"], MAX_NAV_KEYS)
+      end
+
+      # Cap a per-value tally, ignoring blank/non-string values.
+      def bounded_tally(counts, value, cap)
+        return false unless value.is_a?(String) && !value.empty?
+
+        bounded_increment(counts, value, cap)
+      end
+
+      def tally(counts, value)
+        counts[value] += 1 if value.is_a?(String) && !value.empty?
+      end
+
+      def record_duration(acc, summary)
+        first = summary[:first_event_at]
+        last = summary[:last_event_at]
+        return unless first && last
+
+        duration = (last - first).abs
+        acc.durations << duration
+        label = bucket_label(duration)
+        acc.duration_buckets[label] += 1
+      end
+
+      def bucket_label(duration_ms)
+        label, _bound = DURATION_BUCKETS.find { |_label, bound| bound.nil? || duration_ms < bound }
+        label
+      end
+
+      def record_session_day(acc, summary)
+        date = day_string(summary[:first_event_at] || summary[:created_at])
+        acc.per_day_sessions[date] += 1 if date
+      end
+
+      def record_event_day(acc, event)
+        date = day_string(event["timestamp"])
+        acc.per_day_events[date] += 1 if date
+      end
+
+      def error_event?(event)
+        return false unless event["type"] == CUSTOM
+        data = event["data"]
+        data.is_a?(Hash) && data["tag"] == "error"
+      end
+
+      def record_error_day(acc, event)
+        date = day_string(event["timestamp"])
+        acc.per_day_errors[date] += 1 if date
+      end
+
+      # Per-day server-occurrence counts (occurrence timestamps are epoch
+      # seconds); returns whether either cap was hit. since filters problems by
+      # last_seen (safe: an in-window occurrence implies last_seen >= since).
+      # until_time is applied per occurrence, not to list_problems, since a
+      # still-active problem can own in-window occurrences.
+      def collect_server_overlay(acc)
+        since = acc.since
+        until_time = acc.until_time
+        problems = store.list_problems(project: nil, limit: MAX_OVERLAY_PROBLEMS, since: since)
+        truncated = problems.size >= MAX_OVERLAY_PROBLEMS
+
+        problems.each do |problem|
+          occurrences = store.get_occurrences(problem[:id], after: since, limit: MAX_OCCURRENCES_PER_PROBLEM)
+          truncated = true if occurrences.size >= MAX_OCCURRENCES_PER_PROBLEM
+
+          occurrences.each do |occurrence|
+            ts = occurrence["timestamp"].to_f
+            next if until_time && ts > until_time
+            acc.per_day_server_errors[Time.at(ts).utc.to_date.to_s] += 1
+          end
+        end
+
+        truncated
+      end
+
+      def day_string(timestamp_ms)
+        return nil unless timestamp_ms
+        Time.at(timestamp_ms / 1000.0).utc.to_date.to_s
+      rescue TypeError, ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/sentiero/analytics/web_vitals_analyzer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "analyzer"
+require_relative "collectors/vitals_collector"
+
+module Sentiero
+  module Analytics
+    # Aggregates Web Vitals per page URL, scanning the store on read. The recorder
+    # emits one "__perf" custom event per metric report carrying {metric, value,
+    # rating}; ratings come from the client web-vitals library and are tallied
+    # as-is. Per-segment math (last-wins collapse, rating histogram, worst-sample)
+    # lives in VitalsCollector, shared with PageReportAnalyzer.
+    class WebVitalsAnalyzer < Analyzer
+      # Cap on distinct URLs tracked; sessions scan newest-first, so the cap keeps
+      # the most recently visited URLs.
+      MAX_URLS = 200
+
+      MAX_SAMPLES_PER_METRIC = 2000
+
+      # Samples are attributed per page segment so each report lands on the page it
+      # measured. Within a segment, repeated reports of the same metric collapse to
+      # the LAST one (one sample == one page view's final value) so re-emitted
+      # candidates and reloads cannot inflate counts or skew percentiles.
+      def analyze(limit: nil, since: nil, until_time: nil)
+        pages = {} # url => VitalsCollector
+        accumulation_capped = false
+
+        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time) do |summary, window_id, events|
+          each_page_segment(events) do |url, segment, anchor|
+            next unless url
+
+            collector = collector_for(pages, url)
+            unless collector
+              accumulation_capped = true
+              next
+            end
+
+            collector.collect(segment, session_id: summary[:session_id], window_id: window_id, anchor: anchor)
+            accumulation_capped = true if collector.capped
+          end
+        end
+
+        {
+          pages: pages.transform_values(&:summarize),
+          was_truncated: accumulation_capped || hit_cap
+        }
+      end
+
+      private
+
+      # VitalsCollector for a URL, or nil when the URL-row cap is full.
+      def collector_for(pages, url)
+        bounded_fetch(pages, url, MAX_URLS) { VitalsCollector.new(max_samples: MAX_SAMPLES_PER_METRIC) }
+      end
+    end
+  end
+end

data/lib/sentiero/configuration.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Sentiero
+  class Configuration
+    attr_reader :store
+
+    attr_accessor :cors_origins,
+      :auth_callback,
+      :flush_interval_ms,
+      :flush_event_threshold,
+      :max_events_per_page,
+      :max_events_per_request,
+      :max_sessions,
+      :max_events_per_session,
+      :max_problems,
+      :max_server_events,
+      :ingest_keys,
+      :cross_tab_sessions,
+      :capture_metadata,
+      :capture_errors,
+      :track_navigation,
+      :track_custom_events,
+      :capture_clicks,
+      :track_forms,
+      # snake_case rrweb recorder options; converted to camelCase for the frontend.
+      :mask_all_inputs,
+      :mask_input_options,
+      :block_selector,
+      :mask_text_selector,
+      :ignore_selector,
+      :sampling,
+      :inline_stylesheet,
+      :checkout_every_n_ms,
+      # Raw camelCase hash passed to rrweb verbatim; first-class attributes above
+      # take precedence for overlapping keys.
+      :recorder_options,
+      :capture_web_vitals,
+      :analytics_max_scan_sessions,
+      :user_opt_out,
+      :opt_out_cookie_name,
+      :respect_gpc,
+      :retention_period,
+      :anonymize_ip,
+      :redaction,
+      :audit_log,
+      :shareable_replays,
+      :basic_auth,
+      # Escape hatch: serve the dashboard/analytics/monitoring UIs with NO auth
+      # (see Configuration#initialize). Off by default so the UI fails closed.
+      :allow_insecure_dashboard
+
+    # session_idle_timeout / session_max_age have validating writers below (a
+    # bad value here is serialized straight into client-side session-rotation
+    # logic), so they're declared separately from the plain attr_accessor list.
+    attr_reader :session_idle_timeout, :session_max_age
+
+    ENFORCED_PRIVACY = {
+      maskInputOptions: {password: true}
+    }.freeze
+
+    # Replay sessions follow a user journey, so the idle boundary is generous
+    # (a lunch break shouldn't split a journey); max age is the hard cap that
+    # keeps the identifier from living forever on never-idle tabs.
+    DEFAULT_SESSION_IDLE_TIMEOUT = 6 * 60 * 60
+    DEFAULT_SESSION_MAX_AGE = 7 * 24 * 60 * 60
+
+    # Composition root for store caps: a store assigned to the configuration is
+    # bound to the configuration's caps here, so the store itself never reads
+    # global state. Set caps before assigning the store; inject explicit
+    # Store::Limits on the store afterward to override.
+    def store=(store)
+      store.limits = Store::Limits.from_configuration(self) if store.respond_to?(:limits=)
+      @store = store
+    end
+
+    # Reach the Rails / Reporter config from the one core object, e.g.
+    # Sentiero.configure { |c| c.reporter.endpoint = "..." }. They remain separate
+    # instances so the reporter stays usable as a standalone client.
+    def reporter
+      require_subsystem!("Sentiero::Reporter", 'require "sentiero/reporter"')
+      Reporter.configuration
+    end
+
+    def rails
+      require_subsystem!("Sentiero::Rails", "the sentiero-rails gem")
+      Rails.configuration
+    end
+
+    private def require_subsystem!(const_name, hint)
+      return if Object.const_defined?(const_name)
+
+      raise Error, "#{const_name} is not loaded — #{hint} to configure it."
+    end
+
+    # A non-positive or non-numeric value would either disable rotation
+    # (never expire) or break the client's Date.now() arithmetic once
+    # serialized into the config JSON, so it silently falls back instead of
+    # raising.
+    def session_idle_timeout=(value)
+      @session_idle_timeout = clamp_positive_seconds(value, DEFAULT_SESSION_IDLE_TIMEOUT)
+    end
+
+    def session_max_age=(value)
+      @session_max_age = clamp_positive_seconds(value, DEFAULT_SESSION_MAX_AGE)
+    end
+
+    private def clamp_positive_seconds(value, default)
+      (value.is_a?(Numeric) && value.finite? && value > 0) ? value : default
+    end
+
+    def initialize
+      @store = nil
+      @cors_origins = []
+      @auth_callback = nil
+      @flush_interval_ms = 10_000
+      @flush_event_threshold = 50
+      @max_events_per_page = 1_000
+      @max_problems = 5_000
+      @max_server_events = 50_000
+      @ingest_keys = {}
+      @cross_tab_sessions = true
+      @capture_metadata = false
+      @capture_errors = false
+      @track_navigation = false
+      @track_custom_events = false
+      @capture_clicks = false
+      @track_forms = false
+
+      @mask_all_inputs = true
+      @mask_input_options = {}
+      @block_selector = "[data-rr-block]"
+      @mask_text_selector = "[data-rr-mask]"
+      @ignore_selector = "[data-rr-ignore]"
+      @sampling = {scroll: 150, input: "last"}
+      @inline_stylesheet = nil
+      @checkout_every_n_ms = nil
+      @recorder_options = {}
+
+      @capture_web_vitals = false
+      @analytics_max_scan_sessions = 5000
+      @user_opt_out = false
+      @opt_out_cookie_name = "sentiero_optout"
+      @respect_gpc = true
+      @retention_period = nil
+      @session_idle_timeout = DEFAULT_SESSION_IDLE_TIMEOUT
+      @session_max_age = DEFAULT_SESSION_MAX_AGE
+      @redaction = Sentiero::Redaction::Config.new
+      @anonymize_ip = true
+      @audit_log = nil
+      # Opt-in: a share file is a full session dump leaving the operator's
+      # infrastructure, so export/import routes 404 until explicitly enabled.
+      @shareable_replays = false
+      @basic_auth = nil
+      # The dashboard exposes recordings/analytics, so with neither basic_auth nor
+      # auth_callback set it fails closed (403). Set true to opt into serving it
+      # unauthenticated (e.g. behind a trusted proxy or in local dev).
+      @allow_insecure_dashboard = false
+    end
+
+    def effective_recorder_options
+      first_class = {
+        maskAllInputs: mask_all_inputs,
+        maskInputOptions: mask_input_options,
+        blockSelector: block_selector,
+        maskTextSelector: mask_text_selector,
+        ignoreSelector: ignore_selector,
+        sampling: sampling
+      }
+
+      first_class[:inlineStylesheet] = inline_stylesheet unless inline_stylesheet.nil?
+      first_class[:checkoutEveryNms] = checkout_every_n_ms unless checkout_every_n_ms.nil?
+
+      recorder_options
+        .merge(first_class)
+        .merge(ENFORCED_PRIVACY) { |_key, existing, enforced|
+          if enforced.is_a?(Hash)
+            (existing.is_a?(Hash) ? existing : {}).merge(enforced)
+          else
+            enforced
+          end
+        }
+    end
+  end
+end

data/lib/sentiero/erasure.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Sentiero
+  # Right-to-erasure helpers (GDPR Art. 17). Store-agnostic.
+  # Erasure is destructive and irreversible; deleted sessions cannot be recovered.
+  module Erasure
+    module_function
+
+    def erase_sessions(store, ids)
+      ids.each do |id|
+        raise ArgumentError, "Invalid ID: #{id.inspect}" unless Store::VALID_ID.match?(id.to_s)
+      end
+      present = ids.select { |id| store.get_session(id) }
+      present.each { |id| store.delete_session(id) }
+      present.size
+    end
+
+    # At least one bound is required to guard against erasing everything; the
+    # range is inclusive. Lists/deletes in capped batches (paging) until a scan
+    # is short, so one call erases every match regardless of count.
+    def erase_where(store, since: nil, until_time: nil)
+      raise ArgumentError, "provide since: and/or until_time:" if since.nil? && until_time.nil?
+      if since && until_time && since.to_f > until_time.to_f
+        raise ArgumentError, "since: must not be after until_time:"
+      end
+
+      cap = store.limits.analytics_max_scan_sessions
+      erased = 0
+
+      loop do
+        ids = store.list_sessions(
+          limit: cap,
+          since: since,
+          until_time: until_time
+        ).map { |summary| summary[:session_id] }
+
+        ids.each { |id| store.delete_session(id) }
+        erased += ids.size
+
+        # Each listed session matched and was deleted, so the set shrinks;
+        # a short batch means the matches are exhausted.
+        break if ids.size < cap
+      end
+
+      erased
+    end
+  end
+end

data/lib/sentiero/fingerprint.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Sentiero
+  # Computes the grouping fingerprint for an exception occurrence. The
+  # normalization regexes are deliberately linear-time (simple character classes
+  # with a single quantifier, no nesting) so untrusted backtraces cannot trigger
+  # catastrophic backtracking (ReDoS).
+  module Fingerprint
+    # Only the top frames drive grouping (deeper frames vary by call site).
+    MAX_FRAMES = 5
+    MAX_FRAME_LENGTH = 1000
+
+    module_function
+
+    def compute(exception_class:, backtrace:, project:)
+      frames = Array(backtrace).first(MAX_FRAMES).map { |frame| normalize_frame(frame.to_s) }
+      input = "#{project}\n#{exception_class}\n#{frames.join("\n")}"
+      Digest::SHA256.hexdigest(input)[0, 40]
+    end
+
+    # Strips per-occurrence noise (memory addresses, line numbers). Digits inside
+    # identifiers (e.g. `step_1`, `V2::Api`) are preserved so distinct methods do
+    # not collapse into one group.
+    def normalize_frame(frame)
+      frame = frame[0, MAX_FRAME_LENGTH].strip
+      frame
+        .gsub(/0x[0-9a-fA-F]+/, "0xHEX") # memory addresses
+        .gsub(/:[0-9]+(?=:in )/, ":N") # `path:LINE:in 'method'`
+        .gsub(/:[0-9]+\z/, ":N") # `path:LINE` (top-level frame, no method)
+    end
+  end
+end

data/lib/sentiero/ip_anonymizer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module Sentiero
+  # Truncates client IPs before they reach a store or log when
+  # +config.anonymize_ip+ is on. Standard practice for GDPR/CCPA "reasonable"
+  # anonymization: zero the last IPv4 octet (/24) and the last 80 IPv6 bits
+  # (/48). IPv4-mapped IPv6 collapses to its anonymized dotted-quad form.
+  #
+  # Anonymization is one-way and best-effort, not a re-identification guarantee.
+  module IpAnonymizer
+    module_function
+
+    def anonymize(ip)
+      return unless ip.is_a?(String)
+
+      stripped = ip.strip
+      return if stripped.empty?
+      return if stripped.include?("/") # a client IP is a bare host, not a CIDR
+
+      addr = IPAddr.new(stripped)
+      addr = addr.native if addr.ipv4_mapped?
+      addr.mask(addr.ipv4? ? 24 : 48).to_s
+    rescue IPAddr::Error
+      nil
+    end
+  end
+end