koderift-rails 1.3.4 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e49d9d7f56f87dde732a6465a3ced955d8960b692408f6818cf686e30965c8c
-  data.tar.gz: 299cb7491b8211baa559aebbca51b7759929891caefe5048d562791431759202
+  metadata.gz: a9c83f5ae85e74957769db72695555fbdd39aebef940ecb97b7cf1dda72d75c0
+  data.tar.gz: d27d1449f36d00606d187eed46783a6cbcd6df03ad1f2ee8cf515f834d294735
 SHA512:
-  metadata.gz: e01be29d2c18193b54c04d93ae80ce6bca85d58b8c3c57e92227d5e706c4e033d8d13cb103c285a61d90a19e14431f80eec95e2ace8ed38fe2bbb8f92cd9fabf
-  data.tar.gz: b620b59cbe817e063ef7f862be7ed1fc0a36390b6465b4f52b20d59afe51f34de53a47dc72371f7ba14a0079c579a3946c16dbfa1bb3d7cd316c7ad381afe53f
+  metadata.gz: 43e553f25047fc9501be705793df7e7d9b82ec5ecd17850ca8b45b07baacb4e52dd954611a11b580284aedfb6abc070a9ad139482aba6210b63432ceee3c6c11
+  data.tar.gz: e55b1666a9e531b7a4ca9e1f02acaeb4086ef17b65cd0aee6750fd3d641106b248e5027fa083d0f11f95797409688fff9618ed09d8a886e20b6e12ac71e98009

data/CHANGELOG.md

@@ -6,6 +6,41 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 Releases before 1.3.4 were installed from git and were never published to
 RubyGems; they are listed for continuity.
 
+## [2.0.0] - 2026-11-04
+
+Manual error reporting, with a Sentry-compatible API.
+
+Requires koderift-agent >= 1.4.0. Against an older agent, captures still reach
+Raw Logs but not the Log Explorer or the Errors page.
+
+### Added
+- `Koderift.capture_exception` and `Koderift.capture_message` for reporting
+  errors your code already handles. `capture_exception` returns an event with an
+  `event_id`, or nil when nothing was emitted.
+- Scope (`configure_scope`, `with_scope`, `set_user`, `set_tags`, `set_tag`,
+  `set_extras`, `set_extra`, `set_context`), breadcrumbs
+  (`add_breadcrumb`, `Koderift::Breadcrumb`), and `exception_captured?`.
+- Custom instrumentation: `with_child_span` records a span that renders in the
+  APM trace beside the SQL and HTTP spans, and `start_transaction` traces work
+  that is neither a request nor a Sidekiq job — a rake task or cron script.
+- Uncaught rake task failures are now captured automatically. Previously a task
+  that raised wrote only to STDERR, which under cron is never in the Rails log,
+  so those failures were invisible.
+- Configuration: `max_captures_per_minute` (default 100), `sample_rate`,
+  `before_send` and `excluded_exceptions`.
+
+### Fixed
+- Sidekiq jobs enqueued through ActiveJob are reported under their own class
+  (`job["wrapped"]`, as Sidekiq logs them) instead of the adapter's wrapper,
+  which filed every ActiveJob under one `Sidekiq::ActiveJob::Wrapper` row.
+
+### Notes
+- Captures appear under a new `manual` log source, and are excluded from the
+  APM request aggregates by it, so they cannot skew throughput, p95 or Apdex.
+- The gem does not define `Sentry`. Migration is a namespace find-and-replace;
+  see the README for the full mapping and the short list of Sentry APIs with no
+  Koderift equivalent.
+
 ## [1.3.4] - 2026-08-27
 
 First release published to RubyGems.

data/README.md

@@ -12,7 +12,7 @@ Requires Ruby >= 2.7 and Rails 7.1-8.x.
 Add to your `Gemfile`:
 
 ```ruby
-gem 'koderift-rails', '~> 1.3'
+gem 'koderift-rails', '~> 2.0'
 ```
 
 Run `bundle install`. Lograge is a dependency of this gem and is installed
@@ -47,8 +47,158 @@ project's Log Analytics settings page in Koderift.
 * Exception class, message, and cause chain
 * Stack traces (requires `keep_original_rails_log: true`)
 
+## Reporting handled errors
+
+Automatic instrumentation only sees what reaches Rails: a request, a Sidekiq
+job, or something logged at ERROR. An error your code *handles* — rescued,
+retried, degraded gracefully, returned as a 200 — is exactly the kind worth
+knowing about, and nothing reports it for you.
+
+```ruby
+begin
+  sync_contractors
+rescue StandardError => e
+  Rails.logger.error "contractor sync failed: #{e.class} - #{e.message}"
+  Koderift.capture_exception(e)
+end
+```
+
+`capture_exception` returns an event, or `nil` when nothing was emitted:
+
+```ruby
+event_id = Koderift.capture_exception(error)&.event_id
+```
+
+Paste that id into the Log Explorer search box to find the event.
+
+### Errors vs. messages
+
+`capture_exception` produces a tracked Error — grouped by exception class and
+`component#action`, counted, and resolvable. `capture_message` produces a
+searchable log line, and *also* a tracked Error at `:error` or `:fatal`:
+
+```ruby
+Koderift.capture_message("cache warm skipped", level: :info)   # Log Explorer only
+Koderift.capture_message("panel schema drifted",               # a tracked Error
+                         level: :error, name: "PanelSchemaDrift")
+```
+
+`name:` is what separates one message group from another. Without it, every
+unnamed error-level message from the same place groups together — deliberately,
+because grouping on the message text itself would either mint a new Error per
+interpolated value or collapse unrelated messages into one bucket.
+
+`:warn` and `:info` messages never become tracked Errors; they are searchable in
+the Log Explorer.
+
+### Context
+
+```ruby
+Koderift.capture_exception(e,
+  tags:  { region: "eu-west" },
+  extra: { order_id: order.id },
+  user:  { id: current_user.id, email: current_user.email })
+```
+
+Anything matching `config.filter_params` is stripped at every depth, as are the
+keys `controller`, `method` and `job_class` (they collide with how the log agent
+identifies request and job lines).
+
+### Scope, breadcrumbs and custom spans
+
+```ruby
+Koderift.set_user(id: current_user.id)
+Koderift.set_tag(:tenant, current_tenant.slug)
+Koderift.with_scope { |scope| scope.set_tag(:step, "import") }
+
+Koderift.add_breadcrumb(Koderift::Breadcrumb.new(category: "payment",
+                                                 message: "charging card"))
+
+Koderift.with_child_span(op: "stripe", description: "charge") do |span|
+  span.set_data(:amount, 500)
+  gateway.charge!
+end
+```
+
+Scope is per-thread and reset at the end of every request and job. Breadcrumbs
+interleave with the SQL and render crumbs the gem already collects. A child span
+becomes a `custom` span in the APM trace, next to the SQL and HTTP spans.
+
+### Rake tasks and cron
+
+Uncaught rake failures are captured automatically — no task changes needed. This
+matters because a task that raises writes to STDERR, which under cron goes to a
+mail spool or `/dev/null`, so it was previously invisible.
+
+To trace a task as a unit of work, wrap it:
+
+```ruby
+Koderift.start_transaction(name: "ringley_panel:sync_recent_contractors", op: "rake") do
+  sync_contractors
+end
+```
+
+Its queries, outbound HTTP calls and custom spans then render as one trace.
+Prefer this block form: `start_transaction` without a block returns a
+transaction you must `finish` yourself, and an abandoned one leaves notification
+subscribers attached to the process.
+
+### Configuration
+
+```ruby
+Koderift::Rails.configure do |config|
+  config.max_captures_per_minute = 100          # nil to disable the cap
+  config.sample_rate             = 1.0
+  config.excluded_exceptions     = %w[ActiveRecord::RecordNotFound]
+  config.before_send             = ->(payload, hint) { payload }   # nil to drop
+end
+```
+
+A capture never raises, and drops are never silent — the rate limiter says on
+the log when it starts dropping and how many it dropped.
+
+## Migrating from Sentry
+
+Replace the `Sentry` namespace with `Koderift`; the call sites keep working.
+
+| Sentry | Koderift |
+| --- | --- |
+| `Sentry.capture_exception(e, **opts, &blk)` | `Koderift.capture_exception` |
+| `Sentry.capture_message(msg, **opts, &blk)` | `Koderift.capture_message` |
+| `Sentry.capture_event(event)` | `Koderift.capture_event` |
+| `Sentry.last_event_id` / `initialized?` | same |
+| `Sentry.configure_scope` / `with_scope` | same |
+| `Sentry.set_user` / `set_tags` / `set_tag` / `set_extras` / `set_extra` / `set_context` | same |
+| `Sentry.get_current_scope` | same |
+| `Sentry.add_breadcrumb` / `Sentry::Breadcrumb` | `Koderift.add_breadcrumb` / `Koderift::Breadcrumb` |
+| `Sentry.start_transaction` / `with_child_span` | same |
+| `Sentry.exception_captured?` | same |
+| `Sentry.init { |c| ... }` | `Koderift::Rails.configure { |c| ... }` |
+| `config.before_send` / `sample_rate` / `excluded_exceptions` | same |
+
+Capture options are the same: `level:`, `tags:`, `extra:`, `user:`, `contexts:`,
+`fingerprint:`, `backtrace:`, `hint:`, and `message:` on `capture_exception`.
+Levels accept Sentry's names — `:warning` and `:debug` fold to `warn` and `info`.
+
+`fingerprint:` is honoured by synthesising a grouping class, so
+`fingerprint: %w[stripe timeout]` reports as `StripeTimeout: Net::ReadTimeout: ...`.
+
+### Not provided
+
+These have no stub: a method either does something real or is absent, so you
+find out at migration time rather than from a silent no-op.
+
+| Sentry | Why |
+| --- | --- |
+| `capture_check_in` | Cron *monitors* — alerting when a job never runs. Cron errors and slowness are covered (above); detecting an absence needs schedule definitions Koderift does not have yet. |
+| `close`, `clone_hub_to_current_thread`, `with_session_tracking` | Nothing to do behind them: captures are written synchronously with no in-process buffer, and all state is already thread-local. |
+| `get_traceparent`, `get_baggage` | Distributed tracing works, via the `X-Koderift-Trace-ID` header this gem already propagates. |
+| Profiling, release health | Configured inside `Sentry.init` with no call sites, so nothing to replace. Release comparison is on the Koderift deploy-impact view, keyed by the agent's `app_version`. |
+
 ## Requirements
 
 * Ruby >= 2.7
-* Rails >= 6.1
+* Rails 7.1-8.x
 * lograge >= 0.11
+* koderift-agent >= 1.4.0 for manual captures to reach the Log Explorer
+  (older agents ship them as raw log lines only)

data/lib/koderift/rails/breadcrumb.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Koderift
+  module Rails
+    # A manually recorded breadcrumb. Serialises to the same shape
+    # Instrumentation already emits for SQL and partial renders, so manual and
+    # automatic crumbs interleave in one ordered trail rather than living in
+    # two lists the UI would have to merge.
+    class Breadcrumb
+      attr_reader :category, :message, :level, :data, :timestamp
+
+      def initialize(category: nil, message: nil, level: nil, data: nil, timestamp: nil)
+        @category  = category.to_s.empty? ? 'manual' : category.to_s
+        @message   = message.to_s
+        @level     = level&.to_s
+        @data      = data
+        @timestamp = timestamp || Time.now.utc.iso8601
+      end
+
+      def to_h
+        {
+          type:      @category,
+          message:   @message,
+          level:     @level,
+          data:      @data,
+          timestamp: @timestamp
+        }.compact
+      end
+    end
+
+    # The live breadcrumb trail for the current thread.
+    #
+    # Instrumentation.capture publishes ITS OWN array here for the duration of a
+    # request or job, so a manual crumb lands in the same list as the automatic
+    # SQL/render ones and ships with that unit's log line. Outside a captured
+    # unit the trail is a plain thread-local that captures still read, which is
+    # what makes breadcrumbs work in a rake task.
+    module Breadcrumbs
+      KEY = :koderift_breadcrumbs
+
+      class << self
+        def add(crumb)
+          crumb = Breadcrumb.new(message: crumb.to_s) unless crumb.is_a?(Breadcrumb)
+          buffer = (Thread.current[KEY] ||= [])
+          buffer << crumb.to_h
+
+          # Trim here rather than only at the end of Instrumentation.capture:
+          # outside a captured unit nothing else ever bounds this array, and a
+          # rake task adding crumbs in a loop would grow it without limit.
+          max = Koderift::Rails.configuration.max_breadcrumbs.to_i
+          buffer.shift(buffer.size - max) if max.positive? && buffer.size > max
+
+          crumb
+        rescue StandardError
+          nil
+        end
+
+        def current
+          (Thread.current[KEY] || []).dup
+        end
+
+        def clear
+          Thread.current[KEY] = nil
+        end
+      end
+    end
+  end
+end