iugu_logger 0.10.0

data/lib/iugu_logger/pii.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module IuguLogger
+  # PII detection and redaction module.
+  #
+  # 3-layer defense:
+  #   - Layer 1 (ParamFilter): blocks values of keys whose names match a
+  #     sensitive blocklist (password, secret, token, etc.) BEFORE the deep
+  #     content scan
+  #   - Layer 2 (Scanner): regex-based deep content redaction in all string
+  #     fields, with strategy-based replacement (full_redact, last4,
+  #     detect_only, preserve)
+  #   - Layer 3 (Logger): emitted log payload always carries pii.scanned=true
+  #     populated by Scanner — handled in Logger, not here
+  #
+  # PII patterns reuse those validated in production by core/utils/sanitizer.py
+  # (iugu-agents).
+  #
+  # Decisions applied:
+  #   - ILS-002: iugu.account_id 32-hex preserved (SAFE_PATTERNS exclusion)
+  #   - ILS-003: email :detect_only by default (deferred — tech debt)
+  #
+  # Spec: IUGU_LOGGING_STANDARD.md §5
+  module Pii
+    PATTERNS = {
+      cpf:            /\b\d{3}\.?\d{3}\.?\d{3}-?\d{2}\b/,
+      cnpj:           /\b\d{2}\.\d{3}\.\d{3}\/\d{4}-\d{2}\b/,
+      email:          /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/,
+      # Lookarounds (?<![\w-]) and (?![\w-]) require the phone-shaped digit
+      # group to be flanked by non-identifier chars. Without them the regex
+      # matched the middle of dense identifiers (span_id, trace_id, jids,
+      # UUIDs without hyphens) and produced false positives that broke trace
+      # correlation in production. SAFE_KEY_PATHS is the primary defense;
+      # this is defense-in-depth for arbitrary user content.
+      phone:          /(?<![\w-])\(?\d{2}\)?\s?9?\d{4}-?\d{4}(?![\w-])/,
+      cc:             /\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{1,7}\b/,
+      aws_key:        /\bAKIA[0-9A-Z]{16}\b/,
+      bearer:         /Bearer\s+[A-Za-z0-9\-._~+\/]+=*\b/i,
+      url_with_creds: /https?:\/\/[^\/\s:]+:[^\/\s@]+@\S+/
+    }.freeze
+
+    # Strings matching SAFE_PATTERNS are excluded from redaction even when
+    # they incidentally match a PII pattern. Hex identifiers (trace_id 32,
+    # span_id 16, account_id 32, UUID v4) are structural identifiers that
+    # by definition never carry PII; pre-empting them at the value level
+    # avoids the regex coincidence that any 10+ consecutive digits look
+    # like a Brazilian phone number.
+    SAFE_PATTERNS = {
+      iugu_account_id: /\A[A-Fa-f0-9]{32}\z/, # 32-hex (case-insensitive: legacy uppercase + modern lowercase)
+      otel_trace_id:   /\A[a-fA-F0-9]{32}\z/, # OpenTelemetry trace_id (16 bytes hex)
+      otel_span_id:    /\A[a-fA-F0-9]{16}\z/, # OpenTelemetry span_id (8 bytes hex)
+      uuid:            /\A[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}\z/i # UUID v4 / v7
+    }.freeze
+
+    # Canonical schema paths whose values are skipped entirely by the scan.
+    # These fields hold structural identifiers / controlled metadata defined
+    # by IUGU_LOGGING_STANDARD §2 — never user-supplied content. Skipping
+    # them prevents false-positive PII detection on hex/UUID-shaped values
+    # AND saves CPU on the hot path.
+    #
+    # Path = dot-joined hash keys from the user_section root, e.g. a value
+    # at `payload['trace']['span_id']` has path "trace.span_id".
+    SAFE_KEY_PATHS = %w[
+      @timestamp
+      log.level
+      event.kind
+      event.action
+      service.name
+      service.version
+      service.environment
+      service.instance
+      trace.id
+      trace.span_id
+      trace.parent_id
+      request.id
+      http.status_code
+      http.duration_ms
+    ].freeze
+
+    # Default redaction strategies. Override via Configuration#pii_redaction.
+    #
+    # Strategies:
+    #   :full_redact  → "[<TYPE>_REDACTED]"
+    #   :last4        → "**** **** **** 1234" (CC only)
+    #   :detect_only  → unchanged content, but `detected` is recorded
+    #   :preserve     → neither detected nor redacted (escape hatch)
+    #
+    # Philosophy (data-completeness-first, since v0.7):
+    #
+    # Operational logs in iugu serve ops, support, fraud analysts,
+    # compliance, and ML pipelines — not just engineers. Redacting personal
+    # data at emission time breaks those downstream consumers; the legacy
+    # rails_semantic_logger output that they already rely on includes full
+    # CPF, CNPJ, phone, address, email, bank account details. We normalize
+    # that — `:detect_only` means we still RECORD that PII was found (so
+    # `pii.detected: [cpf, phone]` is queryable for audit) but we don't
+    # remove the values from the log. LGPD compliance is met via
+    # access-control on the log store and retention policies, not via
+    # redaction at the source.
+    #
+    # Things that DO stay redacted by default:
+    #   - Payment card numbers (`:cc` → `:last4`) — PCI-DSS hard rule
+    #   - Credentials (`aws_key`, `bearer`, `url_with_creds`) — these are
+    #     never user data, only ever leak risk
+    #
+    # Override per-app: any app needing stricter redaction (e.g. external
+    # log export targets) can set `:full_redact` for the types it needs
+    # via `IuguLogger.configure { |c| c.pii_redaction = ... }`.
+    DEFAULT_STRATEGIES = {
+      cpf:            :detect_only,  # personal data — detected, not redacted (v0.7+)
+      cnpj:           :detect_only,  # legal entity — detected, not redacted (v0.7+)
+      email:          :detect_only,  # personal data — detected, not redacted (was always)
+      phone:          :detect_only,  # personal data — detected, not redacted (v0.7+)
+      cc:             :last4,        # PCI-DSS — last 4 only (KEPT)
+      aws_key:        :full_redact,  # credential — never log (KEPT)
+      bearer:         :full_redact,  # credential — never log (KEPT)
+      url_with_creds: :full_redact   # credential — never log (KEPT)
+    }.freeze
+
+    # Layer 1: keys whose values are filtered before any scanning.
+    # Case-insensitive.
+    DEFAULT_PARAM_BLOCKLIST = %w[
+      password password_confirmation passwd
+      secret token api_key apikey
+      authorization auth bearer_token
+      credit_card cc_number ccnumber cvv cvc
+      ssn pin private_key
+    ].freeze
+
+    PARAM_FILTER_PLACEHOLDER = '[FILTERED]'
+
+    # Frozen result of a Pii scan. Logger uses this to populate the canonical
+    # pii.* block of the emitted payload.
+    class Result
+      attr_reader :payload, :detected, :redacted_count
+
+      def initialize(payload:, detected:, redacted_count:)
+        @payload        = payload
+        @detected       = detected.uniq.sort
+        @redacted_count = redacted_count
+        freeze
+      end
+
+      def to_pii_block
+        {
+          'scanned'  => true,
+          'detected' => @detected.map(&:to_s),
+          'redacted' => @redacted_count
+        }
+      end
+    end
+
+    # Stateful per-scan orchestrator (Layer 1 + Layer 2). NOT thread-safe —
+    # create a new Scanner per log event.
+    class Scanner
+      def initialize(strategies: DEFAULT_STRATEGIES, param_blocklist: DEFAULT_PARAM_BLOCKLIST)
+        @strategies      = strategies
+        @param_blocklist = param_blocklist.map { |k| k.to_s.downcase }
+        @detected        = []
+        @redacted_count  = 0
+      end
+
+      # Returns a Result with a sanitized deep copy of the payload + detection metadata.
+      def scan(payload)
+        sanitized = process(payload)
+        Result.new(payload: sanitized, detected: @detected, redacted_count: @redacted_count)
+      end
+
+      private
+
+      def process(value, path = nil)
+        return value if path && SAFE_KEY_PATHS.include?(path)
+
+        case value
+        when Hash   then process_hash(value, path)
+        when Array  then value.map { |item| process(item, path) }
+        when String then process_string(value)
+        else value
+        end
+      end
+
+      def process_hash(hash, parent_path = nil)
+        result = {}
+        hash.each do |key, value|
+          new_path = parent_path ? "#{parent_path}.#{key}" : key.to_s
+          result[key] = if blocked_key?(key)
+                          PARAM_FILTER_PLACEHOLDER
+                        else
+                          process(value, new_path)
+                        end
+        end
+        result
+      end
+
+      def blocked_key?(key)
+        @param_blocklist.include?(key.to_s.downcase)
+      end
+
+      def process_string(str)
+        return str if str.empty?
+
+        new_str = str
+        PATTERNS.each do |type, pattern|
+          strategy = @strategies[type] || :full_redact
+          next if strategy == :preserve # skip this type entirely
+          next unless new_str =~ pattern
+
+          new_str = apply_strategy(new_str, type, pattern, strategy)
+        end
+        new_str
+      end
+
+      def apply_strategy(str, type, pattern, strategy)
+        any_detected = false
+        redactions   = 0
+
+        new_str = str.gsub(pattern) do |match|
+          if safe_match?(match, type)
+            match
+          else
+            any_detected = true
+            replacement = redact(match, strategy, type)
+            redactions += 1 if replacement != match
+            replacement
+          end
+        end
+
+        @detected << type if any_detected && !@detected.include?(type)
+        @redacted_count += redactions
+        new_str
+      end
+
+      # A match is "safe" (skip detection + redaction) when:
+      #   1. type == :cc — Luhn alone decides. A Luhn-valid number is a real
+      #      PAN and is NEVER safe (always redacted), even if its digit shape
+      #      collides with a SAFE_PATTERN: a bare 16-digit card is 16 chars of
+      #      valid hex and otherwise matches the 16-hex otel_span_id pattern,
+      #      which previously shielded the full PAN from redaction (PCI-DSS
+      #      leak). A Luhn-INVALID cc-shaped match is card-like but actually a
+      #      CPF (11d), CNPJ (14d), or generic id → safe (v0.8.1 fix for
+      #      "54565372000194" being redacted as a card).
+      #   2. Any other type — it matches one of SAFE_PATTERNS (account_id
+      #      32-hex, OTel trace/span ids, UUID). Real span_ids live at
+      #      SAFE_KEY_PATHS (trace.span_id) and are skipped by path before
+      #      content scan, so this is only a content-level guard.
+      def safe_match?(match, type)
+        return !luhn_valid?(match) if type == :cc
+
+        SAFE_PATTERNS.values.any? { |sp| match.match?(sp) }
+      end
+
+      # Luhn / mod-10 checksum — the standard validator real credit card
+      # numbers pass and most fiscal codes / arbitrary digit strings
+      # don't. Stops the regex (which only validates digit count, 13-19)
+      # from over-matching numeric identifiers.
+      def luhn_valid?(value)
+        digits = value.to_s.scan(/\d/).map(&:to_i)
+        return false if digits.size < 13 || digits.size > 19
+
+        sum = 0
+        digits.reverse.each_with_index do |d, i|
+          d *= 2 if i.odd?
+          d -= 9 if d > 9
+          sum += d
+        end
+        (sum % 10).zero?
+      end
+
+      def redact(match, strategy, type)
+        case strategy
+        when :full_redact then redaction_marker(type)
+        when :last4       then mask_last4(match)
+        when :detect_only then match
+        when :preserve    then match
+        else                   redaction_marker(type)
+        end
+      end
+
+      def redaction_marker(type)
+        "[#{type.to_s.upcase}_REDACTED]"
+      end
+
+      def mask_last4(match)
+        digits = match.gsub(/\D/, '')
+        return match if digits.length < 4
+
+        "**** **** **** #{digits[-4, 4]}"
+      end
+    end
+  end
+end

data/lib/iugu_logger/railtie.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# Loaded conditionally from lib/iugu_logger.rb only when ::Rails::Railtie is
+# defined (i.e. Rails is on the load path). Apps without Rails ignore this file.
+
+module IuguLogger
+  # Rails Railtie — wires the SDK into a Rails application with zero config
+  # for the common case:
+  #
+  #   * inserts IuguLogger::RequestLogger after ActionDispatch::DebugExceptions
+  #     in the middleware stack
+  #   * registers IuguLogger::JobLogger::Sidekiq as a server-side middleware
+  #     when Sidekiq is loaded
+  #   * derives a sensible default service_name from the app class
+  #     (Rails.application.class.name → snake_case, dash-prefixed app name)
+  #
+  # Rails.logger is intentionally NOT replaced in this release. Callers
+  # migrate to IuguLogger.event(...) for schema-conforming events; existing
+  # Rails.logger.X calls keep working unchanged. A future release may
+  # introduce an opt-in adapter to route Rails.logger through the buffer.
+  #
+  # Spec: IUGU_LOGGING_STANDARD.md §6 (Railtie auto-config)
+  class Railtie < ::Rails::Railtie
+    config.before_configuration do |app|
+      next if IuguLogger.configuration.service_name
+
+      IuguLogger.configuration.service_name = derive_service_name(app)
+    end
+
+    initializer 'iugu_logger.insert_request_middleware', after: :load_config_initializers do |app|
+      app.middleware.insert_after(
+        ActionDispatch::DebugExceptions,
+        IuguLogger::RequestLogger
+      )
+    end
+
+    initializer 'iugu_logger.register_sidekiq_middleware', after: :load_config_initializers do
+      next unless defined?(::Sidekiq) && ::Sidekiq.respond_to?(:configure_server)
+
+      ::Sidekiq.configure_server do |config|
+        config.server_middleware do |chain|
+          chain.add IuguLogger::JobLogger::Sidekiq
+        end
+      end
+    end
+
+    # Captures Rails view/db runtime from the canonical ActiveSupport
+    # notification fired at the end of every controller action. For
+    # ActionController::API
+    # the legacy `action_dispatch.view_runtime` / `db_runtime` env keys
+    # aren't populated by Rails — but the `process_action.action_controller`
+    # notification payload always has both. We stash them in Buffer; the
+    # RequestLogger middleware reads from there when building the
+    # `rails.*` block.
+    initializer 'iugu_logger.subscribe_action_controller_runtime', after: :load_config_initializers do
+      next unless defined?(::ActiveSupport::Notifications)
+
+      ::ActiveSupport::Notifications.subscribe('process_action.action_controller') do |*args|
+        # `rescue` inside a do/end block needs explicit `begin/end` on
+        # Ruby 2.4 (the bare form was only added in 2.5). We support
+        # 2.4 as first-class per spec §13.7.
+        begin
+          # Rails 6+: ActiveSupport::Notifications::Event is the canonical type;
+          # the args splat works across the 5.0..8.x range we support.
+          payload = args.last.is_a?(Hash) ? args.last : args.last.payload
+          IuguLogger::Buffer.current.set_rails_runtime(
+            view_ms: payload[:view_runtime],
+            db_ms:   payload[:db_runtime]
+          )
+        rescue StandardError
+          # Never let instrumentation break the request.
+        end
+      end
+    end
+
+    rake_tasks do
+      load File.expand_path('tasks/iugu_logger.rake', __dir__)
+    end
+
+    class << self
+      # Best-effort service name from `MyApp::Application` → "my-app".
+      # Falls back to "rails-app" when the app class is unusual.
+      def derive_service_name(app)
+        klass = app.class.name.to_s
+        return 'rails-app' if klass.empty?
+
+        first = klass.split('::').first
+        first.gsub(/([A-Z]+)([A-Z][a-z])/, '\\1_\\2')
+             .gsub(/([a-z\d])([A-Z])/, '\\1_\\2')
+             .downcase
+             .tr('_', '-')
+      end
+    end
+  end
+end

data/lib/iugu_logger/request_logger.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module IuguLogger
+  # Rack middleware — emits ONE consolidated log per HTTP request:
+  #   event.action = http.request.completed (or http.request.failed on raise)
+  #
+  # Behavior:
+  #   1. On request start: resets thread-local Buffer, populates context with
+  #      trace + iugu (auto-extracted from env via TraceContext / TenantContext).
+  #   2. App / controllers call IuguLogger::Buffer.current.push(...) for in-app
+  #      logs throughout the request. (Once Railtie lands in v0.5,
+  #      Rails.logger.X also routes here.)
+  #   3. On request end: drains the buffer, emits a single event including
+  #      `logs: [...]` (the buffered entries) plus http status and duration.
+  #   4. Always resets the buffer afterward.
+  #
+  # Failures: when the downstream app raises, emits `http.request.failed` with
+  # the partial buffer + exception, then re-raises so other middleware sees
+  # the original error.
+  #
+  # Insertion: typically right after Rails' DebugExceptions and before
+  # ActionDispatch's logger so we capture exceptions but bypass Rails' own
+  # request logging.
+  #
+  # Spec: IUGU_LOGGING_STANDARD.md §6 (RequestLogger middleware)
+  class RequestLogger
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      Buffer.reset!
+      buffer = Buffer.current
+
+      trace = TraceContext.extract(rack_env: env)
+      req   = build_request_block(env)
+
+      # Tenant is best-effort here (covers Rack middleware upstream that may
+      # have populated env['iugu.current_*']). The canonical timing is after
+      # @app.call — host apps typically populate tenant in a controller
+      # before_action, which only runs once Rails has dispatched the action.
+      tenant = TenantContext.from_rack(env)
+      buffer.add_context(trace: trace, iugu: tenant, request: req)
+
+      start = monotonic_now
+      status, headers, body = @app.call(env)
+      duration_ms = elapsed_ms(start)
+
+      # Re-read tenant: controllers may have populated env['iugu.current_*']
+      # via before_actions during @app.call. The earlier extraction would
+      # have missed those — see spec §6.3 (RequestLogger / TenantContext).
+      tenant = TenantContext.from_rack(env)
+
+      # Enrich request with Rails dispatch info populated during @app.call
+      # (params, format). Pre-call build_request_block couldn't see these.
+      req = enrich_request_post_dispatch(req, env)
+
+      emit_completed(req: req, trace: trace, tenant: tenant,
+                     status: status, duration_ms: duration_ms,
+                     rails: extract_rails_info(env),
+                     logs: buffer.drain)
+
+      [status, headers, body]
+    rescue StandardError => e
+      duration_ms = elapsed_ms(start)
+      # Same re-read on failure path: if the controller populated tenant
+      # before raising, we should still report it.
+      tenant = TenantContext.from_rack(env)
+      req    = enrich_request_post_dispatch(req, env)
+      emit_failed(req: req, trace: trace, tenant: tenant, error: e,
+                  duration_ms: duration_ms,
+                  rails: extract_rails_info(env),
+                  logs: buffer&.drain || [])
+      raise
+    ensure
+      Buffer.reset!
+    end
+
+    private
+
+    def build_request_block(env)
+      {
+        'id'     => env['action_dispatch.request_id'] || env['HTTP_X_REQUEST_ID'],
+        'method' => env['REQUEST_METHOD'],
+        'path'   => env['PATH_INFO'],
+        'source' => 'api'
+      }.reject { |_, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }
+    end
+
+    # Adds `params` and `format` from the Rack env once the Rails dispatcher
+    # has had a chance to populate them during @app.call. Both keys are
+    # absent for pure Rack/Sinatra apps — the block stays unaltered then.
+    #
+    # Rails populates `action_dispatch.request.parameters` with
+    # `filter_parameters` already applied (passwords, credit cards, etc.
+    # arrive as "[FILTERED]"), so we don't need to re-filter here. PII
+    # detection (CPF, CNPJ, phone, email) is then handled by Pii::Scanner
+    # downstream — with v0.7's :detect_only defaults the content stays
+    # readable for ops/support/fraud while pii.detected is still populated.
+    def enrich_request_post_dispatch(req, env)
+      params = env['action_dispatch.request.parameters']
+      format = extract_request_format(env)
+
+      req = req.merge('params' => params) if params
+      req = req.merge('format' => format) if format
+      req
+    rescue StandardError
+      # Never let enrichment break the response — return what we had.
+      req
+    end
+
+    # Resolves the request format with a robust fallback chain:
+    # 1. Rails Mime#symbol (e.g. :json, :html) — empty/nil symbols are
+    #    discarded so we don't emit an empty string;
+    # 2. Rails Mime#to_s (e.g. "application/json") when no symbol exists;
+    # 3. HTTP_ACCEPT header's first segment;
+    # 4. nil — block is omitted by `compact`/`nilify_empty` downstream.
+    def extract_request_format(env)
+      formats = env['action_dispatch.request.formats']
+      if formats.respond_to?(:first) && formats.first
+        mime = formats.first
+        sym  = mime.respond_to?(:symbol) ? mime.symbol : nil
+        return sym.to_s if sym && !sym.to_s.empty?
+
+        str = mime.to_s
+        return str unless str.empty?
+      end
+
+      accept = env['HTTP_ACCEPT']&.split(',')&.first&.strip
+      accept if accept && !accept.empty?
+    rescue StandardError
+      nil
+    end
+
+    # Builds the `rails:` block when Rails dispatcher info is available.
+    # Sources, in order of preference:
+    #   - env['action_controller.instance']     → controller / action
+    #   - env['action_dispatch.view_runtime']   → view_runtime_ms (full-stack Rails)
+    #   - env['action_dispatch.db_runtime']     → db_runtime_ms   (full-stack Rails)
+    #   - Buffer.current.rails_runtime          → view_ms / db_ms captured by
+    #                                              process_action subscriber
+    #                                              (ActionController::API path)
+    def extract_rails_info(env)
+      controller = env['action_controller.instance']
+
+      view_ms = env['action_dispatch.view_runtime']
+      db_ms   = env['action_dispatch.db_runtime']
+
+      runtime  = Buffer.current.rails_runtime
+      view_ms ||= runtime['view_ms']
+      db_ms   ||= runtime['db_ms']
+
+      info = {}
+      info['controller']      = controller.class.name if controller
+      info['action']          = controller.action_name if controller&.respond_to?(:action_name)
+      info['view_runtime_ms'] = view_ms.to_f.round(2) if view_ms
+      info['db_runtime_ms']   = db_ms.to_f.round(2)   if db_ms
+      info.empty? ? nil : info
+    rescue StandardError
+      nil
+    end
+
+    def emit_completed(req:, trace:, tenant:, status:, duration_ms:, rails:, logs:)
+      IuguLogger.event(
+        'http.request.completed',
+        severity: severity_for(status),
+        message:  format_completed_message(req, status, duration_ms),
+        request:  req,
+        http:     {
+          'status_code'    => status,
+          'status_message' => http_status_message(status),
+          'duration_ms'    => duration_ms
+        }.compact,
+        trace:    nilify_empty(trace),
+        iugu:     nilify_empty(tenant),
+        rails:    nilify_empty(rails),
+        logs:     logs.empty? ? nil : logs
+      )
+    end
+
+    def emit_failed(req:, trace:, tenant:, error:, duration_ms:, rails:, logs:)
+      IuguLogger.event(
+        'http.request.failed',
+        severity: :error,
+        message:  format_failed_message(req, error, duration_ms),
+        request:  req,
+        http:     { 'duration_ms' => duration_ms },
+        trace:    nilify_empty(trace),
+        iugu:     nilify_empty(tenant),
+        rails:    nilify_empty(rails),
+        error:    {
+          'type'        => error.class.name,
+          'message'     => error.message.to_s,
+          'fingerprint' => fingerprint(error)
+        },
+        logs:     logs.empty? ? nil : logs
+      )
+    end
+
+    # HTTP status message ("OK", "Not Found", "Bad Request", etc) — matches
+    # the legacy rails_semantic_logger `payload.status_message` field, so
+    # operators / support / fraud teams keep the same readable signal in
+    # the canonical event.
+    def http_status_message(status)
+      require 'rack/utils'
+      Rack::Utils::HTTP_STATUS_CODES[status.to_i]
+    rescue StandardError
+      nil
+    end
+
+    # Human-readable summary mirroring Apache "Combined Log" intuition:
+    # `<METHOD> <PATH> <STATUS> [<duration_ms>ms]`. The canonical
+    # `event.action` lives in attributes for queries; this is for stream
+    # readability (humans + AI scanning a log viewer).
+    def format_completed_message(req, status, duration_ms)
+      [req['method'], req['path'], status, "[#{duration_ms}ms]"].compact.join(' ')
+    end
+
+    def format_failed_message(req, error, duration_ms)
+      [req['method'], req['path'], 'failed', "[#{duration_ms}ms]", error.class.name].compact.join(' ')
+    end
+
+    def severity_for(status_code)
+      return :info if status_code.to_i < 400
+      return :warn if status_code.to_i < 500
+
+      :error
+    end
+
+    def nilify_empty(value)
+      return nil if value.nil?
+      return nil if value.respond_to?(:empty?) && value.empty?
+
+      value
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def elapsed_ms(start)
+      return 0 if start.nil?
+
+      ((monotonic_now - start) * 1000).round
+    end
+
+    def fingerprint(error)
+      require 'digest'
+      Digest::SHA256.hexdigest("#{error.class.name}|#{normalized_message(error.message)}")
+    end
+
+    def normalized_message(msg)
+      # Strip variable parts (numbers, hex blobs) so similar errors group
+      msg.to_s.gsub(/\d+/, 'N').gsub(/[a-f0-9]{16,}/i, 'HEX')
+    end
+  end
+end