goodsorcery 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1413354a65863f49ea7822ea12cf89b824a71ccec864719ed8dcb0443a54fb48
-  data.tar.gz: e5f2d0445ba8261748f55dd09d15e2ae100bfa8349cf76a55d778fe13ebe51e2
+  metadata.gz: 7c757cad1765947ffa3b03990f995e418f676ff2a2385d23b9576bb4aec1462c
+  data.tar.gz: be2c7da80aa622f3d8aedf18ce6db47d0427f3740bce87b743dde3ff41117d7d
 SHA512:
-  metadata.gz: b7df0121fdb191079e323cb6b6242134c21735aa461aa8c6a9bbed04572c50a820a863d90957a3e7fa57cb9d9b241ea6c9399d7ce71a5974c6c93cde833d956d
-  data.tar.gz: 4533d8744e3d5b8b1b93402b02cd18d6b6c8468222a5945cfb98c417b33a752a43ac72289e4beccf1a0915605d844e4e16656970cdc06a132406ff8bfae3fcf2
+  metadata.gz: 675c74e11fff3d79ff4c4ab47f78f131174b75b98f09a441cce26b274325541f3ce97c630644879de598367f863b4ea93c01719850b1ce46aac782479844a7c3
+  data.tar.gz: 65c4954e28c02247c4b9d00123957827625516a3b218d56773d44b36315de74d9841622d96573d7cd026afcd218949708ca93cb44510d408932b4d8d28aeb81c

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.0 (2026-11-07)
+
+- **Performance monitoring** (opt-in, `config.performance_monitoring = true` or `GOODSORCERY_PERFORMANCE_MONITORING=1`). Records every Rails request and every Active Job and Sidekiq job: count, failures, total time and a shared log-scale histogram (`gs-v1`) with database, external HTTP, view and Ruby time per bucket, plus queue wait for jobs. Metrics are aggregated per transaction per minute in process and sent once a minute to `POST /api/v1/apm/metrics` from a background thread (`goodsorcery-apm`).
+- **Traces** of the slowest request per transaction per minute (`config.performance_traces`, default on), sent to `POST /api/v1/apm/traces`: SQL, `Net::HTTP`, render and enqueue spans; repeated queries grouped with their count, total and app call site (with code context under `send_code_context`); SQL normalised so no literal values leave the process; HTTP spans and the request path without query strings; GC, allocations, host and process; the id of the error reported during the request.
+- `config.performance_ignore_transactions` (default `["Rails::HealthController#show"]`). `GoodSorcery::DeliveryJob` is never recorded.
+- `GoodSorcery.flush_performance` and, with the `:test` delivery, `GoodSorcery.test_performance_payloads`.
+- The gem's own HTTP requests are never measured. Payloads keep their `batch_id` across retries; `429`, `5xx`, `404` (server without performance endpoints: monitoring turns off) and rejected payloads are handled as documented; data is bounded to five minutes and flushed at exit; fork-safe.
+- `bundle exec rake bench:performance` measures the per-request cost.
+
 ## 0.1.1 (2026-10-11)
 
 - `Sidekiq::JobRetry::Handled` and `Sidekiq::JobRetry::Skip` are ignored by default. Sidekiq raises them internally after its retry handling, so reporting them only duplicated the original error.

data/README.md

@@ -7,6 +7,7 @@ The Ruby client for the [Good Sorcery](https://app.goodsorcery.com) error tracke
 - The queue is bounded and **drops rather than blocks** when it is full. Rate limits (`429` + `Retry-After`) and server errors are retried with backoff.
 - It has no runtime dependencies (standard library only). It needs Ruby 3.2 or newer and works with or without Rails.
 - Rails, Rack/Sinatra, Active Job, Action Mailer, Action Cable, Sidekiq and Rake are covered out of the box (see [Integrations](#integrations)).
+- Optional, opt-in [performance monitoring](#performance-monitoring) for Rails apps: response times of every request and job, and timelines of the slowest ones.
 
 ## Installation
 
@@ -106,6 +107,9 @@ Change settings inside `GoodSorcery.configure`: it recompiles the filters and re
 | `shutdown_timeout` | `5` s | How long the exit hook waits for the queue to drain. |
 | `open_timeout` / `read_timeout` | `2` s / `5` s | HTTP timeouts (writes use `read_timeout`). |
 | `active_job_queue` | `"default"` | Queue for `delivery = :active_job`. |
+| `performance_monitoring` | `false` (or `ENV["GOODSORCERY_PERFORMANCE_MONITORING"]` `1`/`0`) | Records every request and job and sends metrics once a minute; see [Performance monitoring](#performance-monitoring). Read when the app boots. |
+| `performance_traces` | `true` | Also sends the timeline of the slowest request per transaction per minute. `false` sends metrics only. |
+| `performance_ignore_transactions` | `["Rails::HealthController#show"]` | Transaction names (exact strings) or regexps never recorded. |
 
 ### Delivery
 
@@ -230,6 +234,30 @@ Hooked in automatically when Sidekiq is loaded before `goodsorcery` or in a Rail
 
 Rails apps get this automatically; elsewhere `require "goodsorcery/tasks"` in your Rakefile. An exception that ends a rake run is reported with `transaction = "rake <tasks>"` (task arguments stay out of the name and go, filtered, to `context.rake`), and the queue is flushed, for up to `shutdown_timeout`, before rake exits.
 
+## Performance monitoring
+
+Off by default. Turn it on in the initializer (or with `GOODSORCERY_PERFORMANCE_MONITORING=1`) and restart:
+
+```ruby
+GoodSorcery.configure do |config|
+  config.performance_monitoring = true
+  # config.performance_traces = true                  # false = metrics only
+  # config.performance_ignore_transactions += ["HealthController#show", /\AAdmin::/]
+end
+```
+
+It follows the same environment rules as error reporting and needs an API key: in a disabled environment nothing is subscribed, no thread starts and a request costs one boolean check.
+
+**What is measured.** Each controller action (`CheckoutsController#create`, with the HTTP method and the route pattern such as `/checkout`, never the real path) and each job (Active Job with any adapter, and Sidekiq jobs not wrapped by Active Job; with the adapter, queue and queue wait). A request or job counts as failed when an exception escapes it (for a request, one Rails answers with a 5xx: a `RecordNotFound` is recorded as a 404, not a failure), when a request answers with a 5xx status, or when Active Job's `retry_on`/`discard_on` handles a job's exception. Time is split into database (`sql.active_record`, without `SCHEMA` and cached queries), external HTTP (`Net::HTTP` calls), views (template renders, without the queries and HTTP calls made from them) and Ruby (the rest). Requests that never reach a controller (routing 404s, assets) and a job run inline inside a request are not separate transactions.
+
+**How it is sent.** Numbers are aggregated in your process per transaction per minute (count, failures, total time and a log-scale histogram with the time per layer) and sent once a minute from one background thread (`goodsorcery-apm`) as a small gzip'd request. The slowest request per transaction per minute also sends its **trace** (built after the response has been sent, on servers such as Puma that allow it): a timeline of its SQL queries, HTTP calls, template renders and job enqueues. Identical queries are grouped with their count, total time and the line of your code that ran them, so N+1 queries stand out. Unsent data is kept for at most five minutes; the payloads are retried with the same batch id.
+
+**What a trace never contains.** No params, headers, cookies, session, request or response bodies, query strings, job arguments or user data. SQL is normalised before it leaves the process: string and number literals become `?`, `IN (…)` lists and `VALUES` rows collapse, comments are removed; bind placeholders such as `$1` stay. Quotes are read the way your database reads them (from the connection's adapter), and when that cannot be told, everything after a string holding a backslash becomes `?`. HTTP calls are method, host and path only (never credentials, even when the app passes a whole URL). Code lines around a repeated query's call site are sent only with `send_code_context` (the default). `before_send` and `filter_params` don't apply, because there is nothing key/value-shaped to filter.
+
+**Cost.** Per request, a few microseconds of bookkeeping plus about 2 µs per query (`bundle exec rake bench:performance` measures it on your machine). Memory is bounded: at most 2,000 spans and 4 MiB of SQL text per running request, 500 transaction names per minute and kind (the rest are counted as `(other)`), five minutes of metrics and 30 traces per minute.
+
+Outside Rails, call `GoodSorcery::Performance.install` after `GoodSorcery.configure`; jobs and `Net::HTTP` are then measured, but web requests need Rails to get their names. In your test suite, the `:test` delivery keeps the payloads in memory: `GoodSorcery.flush_performance` builds them into `GoodSorcery.test_performance_payloads` (`[{ "path" => "/api/v1/apm/metrics", "body" => {...} }]`).
+
 ## Install check
 
 `bin/rails goodsorcery:verify` (or `rake goodsorcery:verify`) checks your setup on demand; see the end of this section.
@@ -270,7 +298,7 @@ event = GoodSorcery.test_events.last
 assert_equal "Payments::DeclinedError", event["exception"]["class"]
 ```
 
-The `:test` delivery ignores the environment check, stores the filtered event hashes exactly as they would be sent, and never touches the network.
+The `:test` delivery ignores the environment check, stores the filtered event hashes exactly as they would be sent, and never touches the network. With performance monitoring started (`GoodSorcery::Performance.install` after setting `config.performance_monitoring = true`), `GoodSorcery.flush_performance` stores the performance payloads in `GoodSorcery.test_performance_payloads`; `clear_test_events` clears both.
 
 ## Self-hosted servers
 
@@ -291,6 +319,7 @@ These are for integrations and advanced setups:
 bin/setup              # bundle install, then the whole test suite
 bundle exec rake test  # core, then Rack/Sidekiq/Rake, then Rails tests, each in its own process
 bundle exec rubocop
+bundle exec rake bench:performance  # cost of performance monitoring per request (not run in CI)
 bin/console
 ```
 

data/lib/generators/goodsorcery/install/templates/initializer.rb

@@ -48,6 +48,13 @@ GoodSorcery.configure do |config|
   # config.breadcrumbs = true
   # config.max_breadcrumbs = 40
 
+  # --- Performance monitoring --------------------------------------------------
+  # Off by default. Records every request and job and sends the slowest
+  # requests' timelines once a minute (also ENV["GOODSORCERY_PERFORMANCE_MONITORING"]=1).
+  # config.performance_monitoring = true
+  # config.performance_traces = true                     # false = metrics only, no traces
+  # config.performance_ignore_transactions += ["HealthController#show", /\AAdmin::/]
+
   # --- Development -----------------------------------------------------------
   # config.install_check = :verify                       # after bundle install: :verify, :test_event or false
   # config.logger = Rails.logger

data/lib/goodsorcery/client.rb

@@ -69,9 +69,21 @@ module GoodSorcery
     end
 
     def shutdown(timeout = config.shutdown_timeout)
+      Performance.shutdown(timeout)
       @delivery ? @delivery.shutdown(timeout) : true
     end
 
+    # Whether performance monitoring may run (DESIGN.md 8.1): with the :test
+    # delivery, or a network delivery in an enabled environment with a key.
+    def performance_allowed?
+      return true if test_delivery?
+      return @gate.enabled? && !config.api_key.to_s.empty? if NETWORK_DELIVERIES.include?(config.delivery)
+
+      log.warn_once(:apm_custom_delivery,
+                    "performance monitoring needs the :async, :sync or :active_job delivery; it is off")
+      false
+    end
+
     def verify
       Verification.run(config, transport)
     end
@@ -123,7 +135,9 @@ module GoodSorcery
       event = prepare_event(exception, options)
       return nil unless event
 
-      delivery.deliver(event) == false ? nil : event["event_id"]
+      event_id = delivery.deliver(event) == false ? nil : event["event_id"]
+      Performance.note_error(event_id)
+      event_id
     rescue StandardError => e
       log.error("notify failed with #{e.class}; the error was not reported")
       nil

data/lib/goodsorcery/configuration/performance_settings.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  class Configuration
+    # The performance monitoring settings (DESIGN.md 8.1). Monitoring is off
+    # unless set here or with GOODSORCERY_PERFORMANCE_MONITORING=1.
+    module PerformanceSettings
+      def self.included(base)
+        base.attr_accessor :performance_ignore_transactions
+        base.attr_reader :performance_traces
+        base.boolean_setting :performance_traces
+      end
+
+      def performance_monitoring
+        return @performance_monitoring unless @performance_monitoring.nil?
+
+        EnvFlag.parse(ENV.fetch("GOODSORCERY_PERFORMANCE_MONITORING", nil)) || false
+      end
+
+      def performance_monitoring=(value)
+        unless [true, false, nil].include?(value)
+          raise ArgumentError, "performance_monitoring must be true, false or nil (got #{value.inspect})"
+        end
+
+        @performance_monitoring = value
+      end
+
+      private
+
+      def assign_performance_defaults
+        @performance_monitoring = nil
+        @performance_traces = true
+        @performance_ignore_transactions = Defaults::PERFORMANCE_IGNORE_TRANSACTIONS.dup
+      end
+    end
+  end
+end

data/lib/goodsorcery/configuration/validation.rb

@@ -44,6 +44,16 @@ module GoodSorcery
         false
       end
 
+      def boolean_setting(name)
+        define_method(:"#{name}=") do |value|
+          unless [true, false].include?(value)
+            raise ArgumentError, "#{name} must be true or false (got #{value.inspect})"
+          end
+
+          instance_variable_set(:"@#{name}", value)
+        end
+      end
+
       def choice_setting(name, choices)
         define_method(:"#{name}=") do |value|
           normalized = value.is_a?(String) ? value.to_sym : value

data/lib/goodsorcery/configuration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "configuration/validation"
+require_relative "configuration/performance_settings"
 
 module GoodSorcery
   # Every setting the gem reads (DESIGN.md 2 and 3). Unset credentials,
@@ -8,6 +9,7 @@ module GoodSorcery
   # environment variables (and Rails) when they are read.
   class Configuration
     extend Validation
+    include PerformanceSettings
 
     DELIVERIES = %i[async sync active_job test].freeze
     DELIVERY_SETTINGS = %i[
@@ -156,6 +158,7 @@ module GoodSorcery
       @install_check = :verify
       @report_handled_errors = true
       assign_capture_defaults
+      assign_performance_defaults
     end
 
     def assign_capture_defaults

data/lib/goodsorcery/defaults.rb

@@ -36,6 +36,10 @@ module GoodSorcery
       SystemExit
     ].freeze
 
+    # Transactions (exact names or regexps) that performance monitoring
+    # never records. GoodSorcery::DeliveryJob is always skipped as well.
+    PERFORMANCE_IGNORE_TRANSACTIONS = ["Rails::HealthController#show"].freeze
+
     DISABLED_ENVIRONMENTS = %w[development test].freeze
     ENDPOINT = "https://app.goodsorcery.com"
   end

data/lib/goodsorcery/integrations/active_job.rb

@@ -26,8 +26,11 @@ module GoodSorcery
 
         def perform_now
           return super if Integrations.delivery_job?(self)
+          return Integrations.run_unit_of_work(JobDetails.new(self)) { super } unless Performance.active?
 
-          Integrations.run_unit_of_work(JobDetails.new(self)) { super }
+          Performance.measure_job(Performance::ActiveJobTiming.new(self)) do
+            Integrations.run_unit_of_work(JobDetails.new(self)) { super }
+          end
         end
       end
 

data/lib/goodsorcery/integrations/rails.rb

@@ -31,13 +31,14 @@ module GoodSorcery
       end
 
       # After the app's initializers ran: subscribe to Rails.error and to
-      # notifications, hook Sidekiq, and recompile the filters so the final
-      # filter_parameters apply.
+      # notifications, hook Sidekiq, recompile the filters so the final
+      # filter_parameters apply, and start performance monitoring if it is on.
       def after_initialize
         subscribe_to_error_reporter
         NotificationBreadcrumbs.subscribe if GoodSorcery.configuration.breadcrumbs
         install_sidekiq if defined?(::Sidekiq)
         GoodSorcery.client.reconfigure(rebuild_delivery: false)
+        GoodSorcery::Performance.install if GoodSorcery.configuration.performance_monitoring
       end
 
       def subscribe_to_error_reporter

data/lib/goodsorcery/integrations/sidekiq.rb

@@ -30,9 +30,25 @@ module GoodSorcery
         attr_accessor :config
 
         def call(worker, job, queue, &)
-          return yield if Sidekiq.active_job_wrapper?(job)
+          return wrapped(job, &) if Sidekiq.active_job_wrapper?(job)
 
-          Integrations.run_unit_of_work(JobDetails.new(job, queue: queue, worker: worker), &)
+          details = JobDetails.new(job, queue: queue, worker: worker)
+          return Integrations.run_unit_of_work(details, &) unless Performance.active?
+
+          Performance.measure_job(Performance::SidekiqTiming.new(job, queue, worker)) do
+            Integrations.run_unit_of_work(details, &)
+          end
+        end
+
+        private
+
+        # A Sidekiq retry runs an Active Job with its original job data, so
+        # its enqueued_at is the first enqueue; Sidekiq's own enqueued_at is
+        # when the retry was queued, which the queue wait is measured from.
+        def wrapped(job, &)
+          return yield unless Performance.active? && job.key?("retry_count")
+
+          Performance::ActiveJobTiming.requeued_at(job["enqueued_at"], &)
         end
       end
 

data/lib/goodsorcery/performance/agent.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Performance
+    # The per-process state: metrics, traces and the flusher. A forked child
+    # gets a fresh, empty agent (the parent keeps and sends what it
+    # recorded), and its flusher thread starts on the child's first record.
+    class Agent
+      attr_reader :pid, :aggregator, :trace_buffer, :flusher, :context
+
+      def initialize(config, log)
+        @pid = Process.pid
+        @aggregator = Aggregator.new
+        @trace_buffer = TraceBuffer.new
+        @context = TraceContext.new(config)
+        @flusher = Flusher.new(agent: self, log: log)
+      end
+
+      def current?
+        @pid == Process.pid
+      end
+
+      def record(recorder, background:)
+        minute = (recorder.finished_wall / 60).floor
+        @aggregator.record(minute, Sample.from(recorder))
+        offer_trace(minute, recorder) if recorder.traces?
+        @flusher.ensure_started if background
+      end
+
+      private
+
+      # A request's trace is built once the response has gone out, when the
+      # server offers a hook for that, so the slowest requests are not kept
+      # waiting for it.
+      def offer_trace(minute, recorder)
+        key = [recorder.kind, recorder.name]
+        return unless @trace_buffer.candidate?(minute, key, recorder.duration_ms)
+
+        hooks = AfterReply.hooks(recorder.env)
+        return build_trace(minute, key, recorder) unless hooks
+
+        hooks << AfterReply.callback { build_trace(minute, key, recorder) }
+      end
+
+      def build_trace(minute, key, recorder)
+        return unless @trace_buffer.candidate?(minute, key, recorder.duration_ms)
+
+        trace = TraceBuilder.new(recorder, minute, @context).build
+        @trace_buffer.offer(minute, key, recorder.duration_ms, trace)
+      end
+    end
+
+    # The Rack server's hooks run after the response is sent: Rack 3's
+    # rack.response_finished (callables get env, status, headers, error)
+    # or Puma's rack.after_reply (no arguments).
+    module AfterReply
+      KEYS = %w[rack.response_finished rack.after_reply].freeze
+
+      def self.hooks(env)
+        return nil unless env.is_a?(Hash)
+
+        KEYS.each do |key|
+          hooks = env[key]
+          return hooks if hooks.is_a?(Array) && !hooks.frozen?
+        end
+        nil
+      end
+
+      # A hook that never raises into the server.
+      def self.callback(&work)
+        proc do |*|
+          work.call
+        rescue StandardError => e
+          GoodSorcery.log.warn_every(:apm_trace_error, 60, "could not build a performance trace (#{e.class})")
+        end
+      end
+    end
+
+    # performance_ignore_transactions: exact names or regexps, plus the gem's
+    # own delivery job. Answers are cached per name.
+    class IgnoreMatcher
+      ALWAYS = ["GoodSorcery::DeliveryJob"].freeze
+      MAX_CACHED = 1_000
+
+      def initialize(list)
+        entries = Array(list)
+        @names = (entries.grep_v(Regexp).map(&:to_s) + ALWAYS).to_h { |name| [name, true] }
+        @patterns = entries.grep(Regexp)
+        @cache = {}
+      end
+
+      def ignored?(name)
+        return true if @names.key?(name)
+        return false if @patterns.empty?
+
+        cached = @cache[name]
+        return cached unless cached.nil?
+
+        @cache.clear if @cache.size >= MAX_CACHED
+        @cache[name] = @patterns.any? { |pattern| pattern.match?(name) }
+      end
+    end
+  end
+end

data/lib/goodsorcery/performance/aggregator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Performance
+    # Per-process, per-minute metrics (DESIGN.md 8.4). Keyed by the minute in
+    # which a unit of work finished (integer Unix minutes), then kind, then
+    # name. At most MAX_TRANSACTIONS names per kind per minute (the rest are
+    # counted under "(other)") and MAX_PENDING_MINUTES minutes are held.
+    class Aggregator
+      MAX_TRANSACTIONS = 500
+      MAX_PENDING_MINUTES = 5
+      OTHER = "(other)"
+
+      attr_reader :dropped_minutes
+
+      def initialize
+        @lock = Mutex.new
+        @minutes = {}
+        @dropped_minutes = 0
+      end
+
+      def record(minute, sample)
+        @lock.synchronize do
+          names = (minute_table(minute)[sample.kind] ||= {})
+          name = names.key?(sample.name) || names.size < MAX_TRANSACTIONS ? sample.name : OTHER
+          (names[name] ||= TransactionStats.new).add(sample, keep_labels: name != OTHER)
+        end
+      end
+
+      # Removes and returns the minutes up to and including +last_minute+
+      # (all of them when nil), oldest first: [[minute, {kind => {name => stats}}]].
+      def take(last_minute = nil)
+        @lock.synchronize do
+          taken = @minutes.keys.sort.select { |minute| last_minute.nil? || minute <= last_minute }
+          taken.map { |minute| [minute, @minutes.delete(minute)] }
+        end
+      end
+
+      def minutes
+        @lock.synchronize { @minutes.keys.sort }
+      end
+
+      def empty?
+        @lock.synchronize { @minutes.empty? }
+      end
+
+      private
+
+      def minute_table(minute)
+        table = @minutes[minute]
+        return table if table
+
+        drop_oldest while @minutes.size >= MAX_PENDING_MINUTES
+        @minutes[minute] = {}
+      end
+
+      def drop_oldest
+        @minutes.delete(@minutes.keys.min)
+        @dropped_minutes += 1
+      end
+    end
+  end
+end

data/lib/goodsorcery/performance/call_site.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Performance
+    # Where the app ran a repeated query: the first stack frame that is the
+    # app's own code (not a gem, not this library). Captured inside the
+    # sql.active_record callback; the code lines are read only when a trace
+    # is built.
+    class CallSite
+      GEM_LIB = "#{File.expand_path("../..", __dir__)}/".freeze
+      CONTEXT_BEFORE = 2
+      CONTEXT_AFTER = 2
+      MAX_LINE_LENGTH = 200
+      MAX_PATH_LENGTH = 1_024
+      MAX_METHOD_LENGTH = 255
+
+      attr_reader :path, :line, :label
+
+      # => a CallSite, or nil when no app frame is on the stack.
+      def self.capture(paths)
+        Thread.each_caller_location do |location|
+          path = location.absolute_path || location.path
+          next if path.nil? || path.start_with?(GEM_LIB) || !paths.in_app?(path)
+
+          return new(path, location.lineno, location.base_label)
+        end
+        nil
+      end
+
+      def initialize(path, line, label)
+        @path = path
+        @line = line
+        @label = label
+      end
+
+      def to_h(paths, line_cache: nil)
+        hash = { "file" => Text.limit(paths.relative(path), MAX_PATH_LENGTH), "line" => line,
+                 "method" => label && Text.limit(label, MAX_METHOD_LENGTH) }.compact
+        context = line_cache && code_context(line_cache)
+        hash["context"] = context if context
+        hash
+      end
+
+      private
+
+      # Two lines before and after the call (5 lines of up to 200 chars).
+      def code_context(line_cache)
+        lines = line_cache.lines(path)
+        return nil unless lines && line.between?(1, lines.size)
+
+        first = [line - CONTEXT_BEFORE, 1].max
+        last = [line + CONTEXT_AFTER, lines.size].min
+        { "start_line" => first, "lines" => limited(lines[(first - 1)..(last - 1)]) }
+      end
+
+      def limited(lines)
+        lines.map { |text| Text.limit(text, MAX_LINE_LENGTH) }
+      end
+    end
+  end
+end