scryer 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2d73db1916cc56075446233dfaa8e88d449bd77218e85fa41fe96e11d56df14
-  data.tar.gz: b4a5c41ff1f7132c4ba4807177ee31629614376b2cb0228e24231f44ab3c25e0
+  metadata.gz: 3d7873062d73beb49e505138b100a9507d676b2d5a13838ba382fedb9ac31a2e
+  data.tar.gz: 6f9168a62835d3aba9a583720fcfea45c5271ddb24d16773023a298566522ad0
 SHA512:
-  metadata.gz: 6f9cac00b59b7f44d5939ec66bd4a63280acf60c2b011f7a0f5977c323a28595a85bf9f1a6a622dc9e6c55704bd664c6df85428b189b5e74edc4990785c1af76
-  data.tar.gz: f56d186dfcae4d6344a7d03a8e43dcc2508f68e4276d7df3c9bffaa46fe8cf1d2591edd078ccc8627258d45a1d6649d5ae391ee225e7a88886afff0f3b912f10
+  metadata.gz: 784555c1e3b96c43ec90f3151fc1beeb2abe90d1905dd897b4a40b33c44a63d00173a07705f44fbefbfb98c53342f328fffb57d1f2d5c196002ee30c3037b9c1
+  data.tar.gz: cf1e78fa3112a1ad8cf28a8686ec59a8ce5e221945ef0b0eb3d26a9ea5c8b943bc36e49547de6bf6e5770623c5e57f1377c603a8d50401585a88a00eedb0d3ad

data/CHANGELOG.md

@@ -3,8 +3,60 @@
 All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [1.3.0] - 2026-09-21
 
+- **Added: `Scryer::APM`, runtime method-level tracing with New Relic and OpenTelemetry
+  integration** (see README's "Runtime method tracing (APM)" section in
+  `docs/rails-integration.md`). Wraps configured classes' own methods (`Module#prepend`, the same
+  technique `QueryWatcher` already uses — no `TracePoint`) and, when a supported provider's SDK is
+  loaded, creates a real nested span per call via *that SDK's own* public API: New Relic via
+  `NewRelic::Agent::Tracer.start_segment`, OpenTelemetry via
+  `OpenTelemetry.tracer_provider.tracer(...).start_span` with `OpenTelemetry::Context.attach`/
+  `.detach` for correct parent/child nesting. Only `instrumentation: :selective` is implemented
+  (`:discovery`/`:deep_trace` raise a clear "not implemented yet" error rather than silently
+  no-opping); only `provider: :new_relic` and `provider: :opentelemetry` are implemented (no
+  Datadog, no other vendor SDK). Zero new gem dependencies — both providers are soft-detected
+  (`defined?(NewRelic::Agent::Tracer)` / `defined?(OpenTelemetry::Trace)`), never required; a host
+  app adds whichever SDK it wants to its own Gemfile. 29 tests in `test/apm_test.rb` (nesting/
+  parent-child spans for both providers, exception handling, kwargs/blocks/visibility
+  preservation, inherited-method exclusion, duplicate-instrumentation guard, sampling, redaction,
+  thread isolation, New Relic segment creation + exporter-failure safety, OpenTelemetry span
+  creation + start-failure safety, Rack middleware, config flow-through) plus a new
+  `benchmark/apm_overhead.rb` with measured (not estimated) per-call overhead numbers — see the
+  doc section for actual figures and what they do/don't cover. `Scryer::Railtie` now also
+  auto-wires APM (`require`/`Scryer::APM.enable!`/middleware installation) whenever
+  `c.apm.enabled = true`, so that flag plus `c.apm.include` is genuinely sufficient in an
+  initializer — no separate manual wiring needed. This boot-time path is held to a stricter safety
+  bar than the rest of the public API: any failure while auto-enabling (a bad `include` entry, an
+  unimplemented `instrumentation` mode, a `require` failure) is caught — `rescue Exception`, not
+  just `StandardError`, deliberately, since a packaging-related `LoadError` is a `ScriptError` —
+  logged, and leaves APM cleanly disabled rather than ever failing app boot. Likewise, a single
+  method that fails to instrument (an internal error, not a config typo) no longer aborts the rest
+  of that class or `include` list. `Scryer::APM.enable!` called directly (console, tests) is
+  unchanged and still raises loudly for an unimplemented mode — only the automatic Railtie path
+  degrades gracefully. 5 more tests in `test/railtie_apm_test.rb` cover that boot-time path
+  directly (34 new tests total).
+
+## [1.2.2] - 2026-09-12
+
+- HTML report redesign: the top-of-report score panel is now a card (soft shadow, rounded
+  corners) instead of a flat box, the four grade badges are gradient-filled rounded squares
+  instead of plain circles, and the severity bars use a CSS grid for consistent label/track/count
+  alignment instead of flexbox eyeballing. Purely visual — no change to report content or data.
+- Fixed: `Scryer::CLI#git` shelled out via backtick interpolation
+  (`` `git -C #{Shellwords.escape(root)} #{cmd}` ``) — flagged by Scryer's own `command_injection`
+  rule on a self-scan. Replaced with `Open3.capture3("git", "-C", root, *cmd)`, an argv array with
+  no shell involved at all, so there's nothing to escape or inject regardless of what `root`
+  contains. `cmd` callers now pass argv words instead of a pre-joined string.
+- Added the `# frozen_string_literal: true` magic comment to every file under `lib/` that was
+  missing it (66 files) — this gem's own `frozen_string_literal` rule fired on itself.
+- Fixed: `unbounded_table_scan` and `n_plus_one_query` false-positived on any bare
+  `Const.all`/`.where`/`.order`-shaped call, even when `Const` was a plain Ruby module/class with
+  no ActiveRecord ancestry (e.g. this gem's own `RuleSet.all.each`) — neither rule consulted
+  `known_models`/`known_non_models` at all. Both now gate their match through
+  `Ast.likely_model_name?`, same as `IdorRule` already did. `Scanner#collect_class_declarations`
+  also now records every `module X` declaration as a "definitely not a model" signal (a bare
+  module can never be `< ActiveRecord::Base`), alongside the existing no-superclass-class signal.
 - **Breaking (report shape): one blended `Security Score` replaced with four independent
   scores** — `security_score`, `performance_score`, `style_score`, and `dependency_score`
   (`ReportRenderer#category_score` runs the same severity+confidence-weighted formula for each,

data/README.md

@@ -120,7 +120,9 @@ each one longer-form than a single section here, cross-linked from wherever it's
   performance numbers, the security model, false-positive handling, the accuracy benchmark, and
   the full Scryer vs RuboCop vs Brakeman vs bundler-audit comparison.
 - [**Rails Integration**](docs/rails-integration.md) — the runtime query/authorization watchers,
-  the `scryer:install` generator, and testing Scryer's own results in your app's test suite.
+  runtime method-level tracing (New Relic or OpenTelemetry, for finding what an APM tool's own
+  "Other"/"Application Code" time actually is), the `scryer:install` generator, and testing
+  Scryer's own results in your app's test suite.
 - [**Contributing & Releasing**](docs/contributing.md) — how to add a new rule, and how this
   gem's own release process works.
 

data/docs/rails-integration.md

@@ -91,6 +91,187 @@ Two honesty points worth being precise about:
   this class doesn't attempt.
 
 
+## Runtime method tracing (APM)
+
+The problem `QueryWatcher` and `AuthorizationWatcher` don't touch: once a request lands inside
+application code — a service object, a repository, a background-job method — most APM tools
+(New Relic included) can only see it as one undifferentiated block of "Application Code" or
+"Other" time. `Scryer::APM` answers "which method inside that block actually took the time" by
+wrapping configured classes' own methods (the same `Module#prepend` technique `QueryWatcher` uses
+on `ActiveRecord::QueryMethods`, not `TracePoint`) and, when a supported APM agent/SDK is loaded,
+creating a real nested span per call via *that agent's own* public API — never an undocumented
+endpoint or a separate exporter of Scryer's own. **Two providers are implemented:**
+
+- **`:new_relic`** — a real nested segment per call via
+  `NewRelic::Agent::Tracer.start_segment`/`Segment#finish`, the same mechanism `add_method_tracer`
+  itself uses internally.
+- **`:opentelemetry`** — a real nested span per call via
+  `OpenTelemetry.tracer_provider.tracer(...).start_span`, with
+  `OpenTelemetry::Context.attach`/`.detach` used to make each span the "current" one so the next
+  nested instrumented call picks it up as its parent automatically — the SDK's own documented
+  manual-span API (the one used whenever the block form, `Tracer#in_span`, doesn't fit).
+
+Neither SDK is a hard dependency of this gem (see the gemspec: zero runtime deps beyond stdlib) —
+both are soft-detected via `defined?(...)`. If you set `c.apm.provider = :opentelemetry`, add
+`opentelemetry-sdk` (plus whatever exporter you want, e.g. `opentelemetry-exporter-otlp`) to your
+own app's `Gemfile`, exactly the way you already add `newrelic_rpm` yourself to use `:new_relic`.
+If the configured provider's SDK isn't loaded, spans are still traced (available via
+`Scryer::APM.on_span`) but nothing is exported anywhere — a warning is logged once, the
+instrumented methods keep working normally either way.
+
+```ruby
+# config/initializers/scryer.rb
+Scryer.configure do |c|
+  c.apm.enabled = true
+  c.apm.provider = :opentelemetry       # or :new_relic
+  c.apm.instrumentation = :selective   # only mode implemented so far — see Limitations below
+  c.apm.include = %w[BookingService PaymentService InventoryService]
+  c.apm.exclude = %w[]                 # Scryer:: / ActiveRecord:: / ActionController:: / ActionDispatch:: / Rails::
+                                        # are always excluded regardless of this list
+  c.apm.sampling_rate = 0.10           # 0.0–1.0, decided once per request, not per span
+  c.apm.capture_exception_messages = false # class name only by default; see Redaction below
+end
+```
+
+That's genuinely the whole thing — `c.apm.enabled = true` is sufficient by itself, no separate
+`require`/`.enable!`/`middleware.use` calls needed. `Scryer::Railtie` (loaded automatically as
+soon as the gem is in your `Gemfile`) checks `c.apm.enabled` in a Rails initializer that runs
+*after* every file in `config/initializers/` — including this one — has already run, and does the
+`require "scryer/apm"` / `Scryer::APM.enable!` / `Rails.application.config.middleware.use
+Scryer::APM::Middleware` sequence for you (`Scryer::Railtie.maybe_enable_apm`, tested directly in
+`test/railtie_apm_test.rb`) if and only if that flag is true. Leaving `c.apm.enabled` at its
+default (`false`) — or omitting the `c.apm` block entirely — means none of this runs and there is
+no measurable overhead, same as never having required this file at all.
+
+**The one thing that genuinely can't be defaulted: `c.apm.include` must still be populated.**
+There is no "trace every method automatically" mode — an empty `include` (the default) means
+`enabled = true` turns the machinery on but instruments nothing, by design (see Production safety
+below for why "instrument every method in the app" is deliberately not offered).
+
+Outside a request (a Sidekiq job, a rake task), open a trace scope yourself the same way
+`QueryWatcher.watch` works for queries:
+
+```ruby
+Scryer::APM.trace { SomeJob.new.perform }
+```
+
+### What gets instrumented, precisely
+
+`c.apm.include` takes class/module name strings. For each one, **only methods defined directly on
+that class** (`instance_methods(false)` + private/protected equivalents) are wrapped — methods
+*inherited* from a superclass or module are never touched, even if the named class itself has none
+of its own. This is deliberate, not a current limitation: instrumenting inherited methods via a
+bare class-name entry is exactly how `include: ["SomeModel"]` would end up silently wrapping
+`ActiveRecord::Base` internals, which is the "sensitive framework internals" risk a production
+instrumentation tool has to avoid by construction, not by asking users to get their `exclude` list
+right. Method visibility (public/private/protected) is preserved exactly. Positional args, keyword
+args, blocks, and return values all pass through `super` unchanged; exceptions of every class
+(not just `StandardError`) are recorded on the span and always re-raised, never swallowed.
+
+### What each span records
+
+`class_name`, `method_name`, `file`/`line` (captured once when the method is wrapped, not per
+call), `trace_id`/`span_id`/`parent_span_id` (nested calls get correct parent/child relationships
+via a thread-local span stack — see the "nested calls" test in `test/apm_test.rb`), `duration_ms`,
+`status` (`:ok`/`:error`), `exception_class`, `thread_id`. **Method argument values, local
+variables, and return values are never recorded, under any configuration** — there is no opt-in
+that changes this. `exception_message` is `nil` unless `capture_exception_messages: true`, and even
+then passes through a best-effort (not exhaustive — see Limitations) redaction pass that masks
+long token/hash-shaped substrings and email addresses before being kept.
+
+### Production safety
+
+- **`instrumentation: :off`** installs no hooks at all — measured overhead is within noise of not
+  requiring the file (see `benchmark/apm_overhead.rb`).
+- **Sampling is per-trace, not per-span**: the decision is made once when `Scryer::APM.trace` opens
+  (or on the first instrumented call if a request somehow reaches one without a scope), so a
+  sampled request gets a complete, connected trace rather than a random scatter of orphaned spans.
+- **Provider failures never break the traced method.** New Relic's `start_segment`/`finish`/
+  `notice_error` and OpenTelemetry's `start_span`/`finish`/`record_exception` are each wrapped in
+  their own `rescue StandardError` — see `test_new_relic_segment_start_failure_does_not_break_the_traced_method`
+  and `test_open_telemetry_span_start_failure_does_not_break_the_traced_method` in
+  `test/apm_test.rb`, which stub a failing `Tracer.start_segment`/`Tracer#start_span` and confirm
+  the real method's return value still comes through unaffected.
+- **No custom export queue, batching, or retry/backoff exists in this module, and none is needed**:
+  spans are handed directly to the already-async, already-batched, already-retried agent/SDK
+  transport via its own span API — Scryer::APM never talks to a network endpoint itself. The one
+  thing this means: if your configured provider isn't loaded but you keep `Scryer::APM.on_span`
+  wired to your own sink, *that* sink is your responsibility to make non-blocking/bounded — nothing
+  here queues or batches on your behalf.
+- **Calling `.instrument_by_name`/`.instrument_method` more than once for the same class/method is a
+  no-op** (a process-wide dedupe guard), so re-running an initializer (e.g., Rails' `to_prepare` in
+  development) can't double-wrap a method into two nested spans for one call.
+- **A misconfiguration can never fail app boot, even in production.** This is the specific
+  guarantee `test/railtie_apm_test.rb` exists to prove, not just assert: a bad class name in
+  `include`, `instrumentation` set to an unimplemented mode, or any other failure while
+  `Scryer::Railtie` auto-enables APM (see "That's genuinely the whole thing" above) is caught —
+  broadly, `rescue Exception` rather than just `StandardError`, since a `require` failure from a
+  packaging issue would raise `LoadError`, a `ScriptError` — logged once, and leaves APM cleanly
+  disabled for that process; the rest of the app boots and runs normally. One method failing to
+  instrument (an internal error, not a bad config value) is scoped even tighter: only that method
+  is skipped, not the rest of its class or the rest of `include`. **This graceful-degradation bar
+  is specific to the automatic Railtie path** — `Scryer::APM.enable!` called directly (a console, a
+  test, a non-Rails script) still raises immediately for an unimplemented mode, which is the
+  correct behavior when a developer is watching and wants fast feedback rather than a silently
+  disabled feature.
+
+### Measured overhead
+
+From `benchmark/apm_overhead.rb` (Apple silicon dev machine, Ruby 3.4.8, 200,000 calls per
+scenario — re-run this yourself before trusting these numbers for capacity planning on different
+hardware):
+
+| scenario | ns/call | vs. uninstrumented |
+|---|---|---|
+| baseline (no Scryer::APM at all) | ~28 ns | 1.0x |
+| `instrumentation: :off` | ~28 ns | ~1.0x (no measurable difference) |
+| `:selective`, inside a trace, `sampling_rate: 0.0` | ~172 ns | ~6.3x |
+| `:selective`, inside a trace, `sampling_rate: 1.0` (full span) | ~1771 ns | ~64x |
+
+The `:off` vs. unsampled-but-wrapped gap (~6x) is the fixed cost of the `prepend`/`define_method`
+dispatch layer itself, before any span is even considered — this is the floor cost paid by every
+call to a wrapped method regardless of sampling, which is why `include` should name specific
+service/business-logic classes, not broad namespaces. Full span creation (~1771 ns, ~1.8 µs) is
+still small in absolute terms next to typical service-method bodies (a DB query alone is usually
+1–20+ ms), but at high call volume with `sampling_rate: 1.0` it is not free — this is exactly what
+`sampling_rate` exists to bound. Retained-memory cost: 50,000 held `Span` objects (worst case — a
+consumer that doesn't drain them) measured ~53 MB RSS growth, roughly ~1 KB/span.
+
+### Limitations — implemented vs. not yet
+
+**Implemented and tested** (see `test/apm_test.rb`, 29 examples, and `test/railtie_apm_test.rb`, 5
+more): `:off` and `:selective` modes; nested parent/child spans; exception recording + re-raise;
+keyword args/blocks/return values; method visibility preservation; inherited-method exclusion;
+duplicate-instrumentation guard; per-class `exclude`; trace-scoped sampling; thread isolation
+(concurrent requests on different threads never share trace/span state); New Relic segment
+creation, error notification, and exporter-failure safety; OpenTelemetry span creation
+(with correct parent/child nesting via `Context.attach`/`.detach`), exception recording, and
+start-failure safety; the Rack middleware; reading config through `Scryer.configure`;
+`c.apm.enabled = true` alone (no manual `require`/`.enable!`/`middleware.use`) genuinely
+triggering tracing via the Railtie; a bad `include` entry or an unimplemented mode failing to
+crash boot (see "Production safety" above); a single method's instrumentation failure not taking
+out the rest of its class.
+
+**Not implemented** — raises a clear `ArgumentError` naming this doc rather than silently
+no-opping if configured:
+- `instrumentation: :discovery` and `:deep_trace` modes (low-overhead profiling to *find* expensive
+  methods automatically, and extra detail captured only for slow/failed requests, respectively).
+- Any provider other than `:new_relic` and `:opentelemetry` — no Datadog, no vendor-specific SDK
+  beyond those two.
+- Singleton (class) method instrumentation — only instance methods.
+- Distributed trace-context propagation across a process boundary (an outgoing HTTP call to
+  another service, or an inbound request that already carries a W3C `traceparent` header). This
+  module's own `trace_id`/`span_id` fields are local-process only. The `:opentelemetry` provider's
+  *spans* do still nest correctly with each other within one process via `Context.attach`/`.detach`
+  — what's missing is reading/writing the `traceparent` header itself to connect that local trace
+  to one already in progress elsewhere.
+
+**Known caveat, not a bug**: `Scryer::APM.disable!` (test-only) clears configuration/dedupe state
+but cannot un-`prepend` an already-instrumented class — Ruby has no supported way to do that. Tests
+that need a clean slate instrument a freshly-defined, uniquely-named class per example rather than
+reusing one across examples; a host app calling `.enable!` more than once in a running process
+should expect the same constraint.
+
 ## Generators
 
 Scryer ships one generator: `scryer:install`. Run `bin/rails generate scryer:install --help`

data/lib/generators/scryer/templates/scryer_initializer.rb

@@ -42,3 +42,24 @@ end
 #   Scryer::QueryWatcher.enable!
 #   Rails.application.config.middleware.use Scryer::QueryWatcher::Middleware
 # end
+
+# Runtime method-level tracing (see README's "Runtime method tracing (APM)")
+# — finds which method inside a request is actually responsible for time
+# an APM tool would otherwise lump into "Other"/"Application Code". Providers
+# :new_relic and :opentelemetry (each soft-detected; no hard dependency added
+# by enabling this — add whichever SDK you pick to your own Gemfile) and
+# instrumentation :selective (named classes only) are implemented so far.
+# `c.apm.enabled = true` below is genuinely sufficient on its own —
+# Scryer::Railtie wires up the require/.enable!/middleware for you once this
+# flag is true, after this file has already run. Safe to leave on in
+# production — leaving `include` empty (or `enabled` false) has no
+# measurable overhead, and sampling_rate bounds the cost of the classes you
+# do name:
+#
+# Scryer.configure do |c|
+#   c.apm.enabled = true
+#   c.apm.provider = :opentelemetry # or :new_relic
+#   c.apm.instrumentation = :selective
+#   c.apm.include = %w[] # e.g. %w[BookingService PaymentService] — required, see README
+#   c.apm.sampling_rate = 0.10
+# end

data/lib/scryer/apm.rb

@@ -0,0 +1,458 @@
+# frozen_string_literal: true
+require "securerandom"
+
+module Scryer
+  # Runtime method-level tracing — answers "which method actually ate the
+  # time this New Relic (or any other APM) lumps into Others/Application
+  # Code". Built the same way Scryer::QueryWatcher already is: a
+  # `Module#prepend` generated per instrumented class, state kept in
+  # `Thread.current` (never a global mutable collection — concurrent
+  # requests on a multi-threaded server must never see each other's spans,
+  # the same lesson QueryWatcher's own docs call out), and zero new gem
+  # dependencies. No custom HTTP exporter of its own: when a supported APM
+  # agent/SDK is loaded (currently: the New Relic Ruby agent, or the
+  # opentelemetry-ruby SDK), spans are created through *that agent's own*
+  # public, documented API — `NewRelic::Agent::Tracer.start_segment` for
+  # New Relic, `OpenTelemetry.tracer_provider.tracer(...).start_span` for
+  # OpenTelemetry — so they nest inside that agent's own trace/transaction
+  # and ride its own already-async, already-batched, already-retried export
+  # pipeline. Either SDK is soft-detected (`defined?(...)`), never a hard
+  # gem dependency of Scryer itself — a host app that wants the
+  # `:opentelemetry` provider adds `opentelemetry-sdk` (and an exporter, e.g.
+  # `opentelemetry-exporter-otlp`) to its own Gemfile, same as it already
+  # does for `newrelic_rpm` today. This module doesn't need to (and
+  # doesn't) implement its own export queue, batching, or backoff, because
+  # it never talks to a network endpoint itself.
+  #
+  # Three things this deliberately does NOT do, all by design, not omission:
+  #   - Capture method argument values, local variables, or return values.
+  #     Only class name, method name, file:line (captured once at wrap
+  #     time, not per call), timing, and exception *class* are recorded.
+  #     See `capture_exception_messages` below for the one opt-in exception
+  #     to "no payload data ever".
+  #   - Instrument methods *inherited* from a superclass/module. Only
+  #     methods defined directly on the named class/module
+  #     (`instance_methods(false)`) are wrapped — instrumenting inherited
+  #     framework methods (ActiveRecord::Base, etc.) via a plain class-name
+  #     entry in `include` would be exactly the "sensitive framework
+  #     internals" this module is required to avoid.
+  #   - Implement :discovery or :deep_trace modes. Only :off and :selective
+  #     exist so far — see README's "Runtime method tracing" section for
+  #     what's planned vs. implemented.
+  class APM
+    # One method call. `parent_span_id` is nil for the outermost traced
+    # call in a given `.trace` block. `exception_message` is nil unless
+    # `capture_exception_messages: true` was configured AND `redact_exception_message`
+    # didn't blank it out.
+    Span = Struct.new(
+      :trace_id,
+      :span_id,
+      :parent_span_id,
+      :class_name,
+      :method_name,
+      :file,
+      :line,
+      :started_at,      # Float, Process.clock_gettime(Process::CLOCK_MONOTONIC) — for duration math
+      :wall_time,        # Time — for correlating against logs/other tools
+      :duration_ms,
+      :status,           # :ok | :error
+      :exception_class,
+      :exception_message,
+      :thread_id,
+      keyword_init: true
+    ) do
+      def to_h
+        super.transform_keys(&:to_s)
+      end
+    end
+
+    class << self
+      # Turns tracing on for the life of the process. Idempotent (later
+      # calls are no-ops) — same contract as QueryWatcher.enable!. Reads
+      # unset keyword args from Scryer.configuration.apm so
+      # `Scryer.configure { |c| c.apm.foo = ... }; Scryer::APM.enable!`
+      # works without repeating every option.
+      def enable!(
+        provider: nil,
+        instrumentation: nil,
+        include: nil,
+        exclude: nil,
+        sampling_rate: nil,
+        capture_exception_messages: nil,
+        logger: nil
+      )
+        return if @enabled
+
+        cfg = Scryer.configuration.apm
+        @provider = provider || cfg.provider || :new_relic
+        @instrumentation = instrumentation || cfg.instrumentation || :selective
+        @include = Array(include || cfg.include).map(&:to_s)
+        @exclude = Array(exclude || cfg.exclude).map(&:to_s) + DEFAULT_EXCLUDE
+        @sampling_rate = (sampling_rate || cfg.sampling_rate || 1.0).to_f.clamp(0.0, 1.0)
+        @capture_exception_messages = capture_exception_messages.nil? ? !!cfg.capture_exception_messages : capture_exception_messages
+        @logger = logger || default_logger
+        @instrumented = {} # {[class_name, method_name] => true} — dedupe guard
+        @enabled = true
+
+        case @instrumentation
+        when :off
+          # Nothing to install — enabled? is true (so .trace/.instrument
+          # calls don't raise) but no method is ever wrapped, so overhead
+          # is the cost of one `if` per call site that checks this mode,
+          # nothing more.
+        when :selective
+          @include.each { |name| instrument_by_name(name) }
+        when :discovery, :deep_trace
+          raise ArgumentError,
+                "Scryer::APM instrumentation: #{@instrumentation.inspect} is not implemented yet " \
+                "(only :off and :selective are). See README's \"Runtime method tracing\" section."
+        else
+          raise ArgumentError, "Scryer::APM instrumentation: unknown mode #{@instrumentation.inspect}"
+        end
+
+        warn_if_provider_unavailable
+      end
+
+      def enabled?
+        !!@enabled
+      end
+
+      # Test-only: undoes .enable! bookkeeping. Does NOT un-prepend already
+      #-installed modules (Ruby has no supported way to do that) — tests
+      # that need a truly clean slate use a fresh, disposable class per
+      # example instead of instrumenting a shared one twice.
+      def disable!
+        @enabled = false
+        @instrumented = {}
+        @on_span = nil
+      end
+
+      def instrumentation_mode
+        @instrumentation
+      end
+
+      # Opens a new trace scope — call this once per unit of work (an HTTP
+      # request, a Sidekiq job, a rake task). Every span created by an
+      # instrumented method call inside the block shares this trace_id and
+      # nests under whatever span is currently open on this thread, via a
+      # thread-local stack (so nested `.trace` calls — a job that itself
+      # calls another instrumented method — behave correctly: the inner
+      # scope's spans still get the outer trace_id if one is already open,
+      # rather than starting a disconnected new trace).
+      def trace(trace_id: nil)
+        return yield unless enabled? && @instrumentation != :off
+
+        already_in_trace = Thread.current[TRACE_ID_KEY]
+        Thread.current[TRACE_ID_KEY] ||= trace_id || SecureRandom.hex(16)
+        Thread.current[SAMPLED_KEY] = rand < @sampling_rate if Thread.current[SAMPLED_KEY].nil?
+        Thread.current[SPAN_STACK_KEY] ||= []
+        yield
+      ensure
+        unless already_in_trace
+          Thread.current[TRACE_ID_KEY] = nil
+          Thread.current[SAMPLED_KEY] = nil
+          Thread.current[SPAN_STACK_KEY] = nil
+        end
+      end
+
+      def current_trace_id
+        Thread.current[TRACE_ID_KEY]
+      end
+
+      def sampled?
+        !!Thread.current[SAMPLED_KEY]
+      end
+
+      # Resolves a "ClassName" or "Module::ClassName" string to a constant
+      # and instruments every method defined directly on it (public,
+      # protected, and private — visibility is preserved, see
+      # build_instrumentation_module). Silently skips (with a logged
+      # warning, not an exception — a typo in `include` shouldn't crash
+      # boot) names that don't resolve or that match `exclude`.
+      def instrument_by_name(name)
+        return if excluded?(name)
+
+        klass = Object.const_get(name)
+        methods = klass.instance_methods(false) + klass.private_instance_methods(false) +
+                  klass.protected_instance_methods(false)
+        methods.uniq.each { |m| instrument_method(klass, m) }
+      rescue NameError => e
+        @logger.warn("[Scryer::APM] include: #{name.inspect} did not resolve to a constant (#{e.message}) — skipped")
+      end
+
+      # One bad method must never take out the rest of `include` — this is
+      # the boundary between "a typo/edge case in config" and "the app
+      # fails to boot", so it catches broadly (StandardError, not just the
+      # NameError instrument_by_name's own constant-resolution guards for)
+      # and skips just this one method, logged, rather than propagating.
+      def instrument_method(klass, method_name)
+        key = [klass.name, method_name]
+        return if @instrumented[key]
+
+        original = klass.instance_method(method_name)
+        location = original.source_location
+        visibility = method_visibility(klass, method_name)
+        mod = build_instrumentation_module(klass, method_name, location, visibility)
+        klass.prepend(mod)
+        @instrumented[key] = true
+      rescue StandardError => e
+        @logger.warn("[Scryer::APM] failed to instrument #{klass}##{method_name} (#{e.class}: #{e.message}) — skipped")
+      end
+
+      def instrumented?(klass, method_name)
+        !!@instrumented[[klass.name, method_name]]
+      end
+
+      private
+
+      TRACE_ID_KEY = :scryer_apm_trace_id
+      SAMPLED_KEY = :scryer_apm_sampled
+      SPAN_STACK_KEY = :scryer_apm_span_stack
+
+      # Never instrumented even if named explicitly in `include` — Scryer's
+      # own code (would recurse into itself the moment .enable! ran), and
+      # the framework namespaces most likely to be typo'd into `include`
+      # by mistake (each is *also* excludable/addable by the host app via
+      # its own `exclude`/`include`, this is just a safe floor).
+      DEFAULT_EXCLUDE = %w[Scryer:: ActiveRecord:: ActionController:: ActionDispatch:: Rails::].freeze
+
+      def excluded?(name)
+        @exclude.any? { |pattern| name.start_with?(pattern) || name == pattern.sub(/::\z/, "") }
+      end
+
+      def method_visibility(klass, method_name)
+        return :private if klass.private_method_defined?(method_name)
+        return :protected if klass.protected_method_defined?(method_name)
+
+        :public
+      end
+
+      # One freshly-built anonymous module per (class, method) pair,
+      # `prepend`ed onto the class — the same mechanism QueryWatcher uses
+      # on ActiveRecord::QueryMethods. `*args, **kwargs, &block` + `super`
+      # forwards positional args, keyword args, and blocks correctly on
+      # every Ruby version this gem supports (>= 2.7); the wrapped method's
+      # return value and any exception it raises both pass through
+      # unchanged. `send(:private, ...)`/`protected` after `define_method`
+      # restores the original visibility, since `define_method` always
+      # defines a public method by default.
+      def build_instrumentation_module(klass, method_name, location, visibility)
+        file, line = location
+        Module.new do
+          define_method(method_name) do |*args, **kwargs, &block|
+            unless Scryer::APM.enabled? && Scryer::APM.instrumentation_mode == :selective && Scryer::APM.sampled?
+              next super(*args, **kwargs, &block)
+            end
+
+            Scryer::APM.send(:call_instrumented, self.class, method_name, file, line) do
+              super(*args, **kwargs, &block)
+            end
+          end
+          send(visibility, method_name) unless visibility == :public
+        end
+      end
+
+      # The actual per-call work: build the Span, open a New Relic segment
+      # if one's available, run the real method, close everything out
+      # (success or exception) and push/pop the thread-local span stack so
+      # nested instrumented calls get the right parent_span_id.
+      def call_instrumented(klass, method_name, file, line)
+        stack = (Thread.current[SPAN_STACK_KEY] ||= [])
+        span = Span.new(
+          trace_id: current_trace_id || (Thread.current[TRACE_ID_KEY] = SecureRandom.hex(16)),
+          span_id: SecureRandom.hex(8),
+          parent_span_id: stack.last&.span_id,
+          class_name: klass.name,
+          method_name: method_name.to_s,
+          file: file,
+          line: line,
+          started_at: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+          wall_time: Time.now,
+          thread_id: Thread.current.object_id,
+          status: :ok
+        )
+        stack.push(span)
+        provider_segment = start_provider_segment(klass, method_name)
+
+        begin
+          yield
+        rescue Exception => e # rubocop-equivalent: intentional — must record then re-raise every exception class, not just StandardError
+          span.status = :error
+          span.exception_class = e.class.name
+          span.exception_message = redact_exception_message(e.message) if @capture_exception_messages
+          raise
+        ensure
+          span.duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - span.started_at) * 1000).round(3)
+          finish_provider_segment(provider_segment, span)
+          stack.pop
+          @on_span&.call(span)
+        end
+      end
+
+      # Dispatches to whichever provider is configured — only one provider
+      # is active per process (set once at .enable! time), so this is a
+      # simple case, not a fan-out to every provider at once.
+      def start_provider_segment(klass, method_name)
+        case @provider
+        when :new_relic then start_new_relic_segment(klass, method_name)
+        when :opentelemetry then start_open_telemetry_span(klass, method_name)
+        end
+      end
+
+      def finish_provider_segment(segment, span)
+        case @provider
+        when :new_relic then finish_new_relic_segment(segment, span)
+        when :opentelemetry then finish_open_telemetry_span(segment, span)
+        end
+      end
+
+      # `NewRelic::Agent::Tracer.start_segment`/`Segment#finish` is the
+      # agent's own public, documented API for creating a custom segment
+      # that nests under whatever transaction/segment is already open —
+      # this is how the agent's own instrumentation (and `add_method_tracer`
+      # under the hood) creates segments, so it's the supported integration
+      # path, not an undocumented mechanism. Soft-detected: if newrelic_rpm
+      # isn't loaded, or isn't inside an active transaction, this is a
+      # no-op and the instrumented method still runs normally — APM
+      # visibility is never allowed to break the app it's watching.
+      def start_new_relic_segment(klass, method_name)
+        return nil unless @provider == :new_relic && defined?(NewRelic::Agent::Tracer)
+
+        NewRelic::Agent::Tracer.start_segment(name: "Custom/#{klass.name}/#{method_name}")
+      rescue StandardError => e
+        @logger.warn("[Scryer::APM] New Relic segment start failed: #{e.message}") if @logger
+        nil
+      end
+
+      def finish_new_relic_segment(segment, span)
+        return unless segment
+
+        segment.notice_error(build_reportable_exception(span)) if span.status == :error && span.exception_class
+        segment.finish
+      rescue StandardError => e
+        @logger&.warn("[Scryer::APM] New Relic segment finish failed: #{e.message}")
+      end
+
+      # `OpenTelemetry.tracer_provider.tracer(...).start_span` + explicit
+      # `OpenTelemetry::Context.attach`/`.detach` is the SDK's own public,
+      # documented manual-span API (used whenever the block form,
+      # `Tracer#in_span`, doesn't fit — exactly this case, since
+      # call_instrumented's own begin/rescue/ensure already owns the
+      # start/finish lifecycle). `Context.attach` makes this span the
+      # "current" one so the *next* nested instrumented call's
+      # `tracer.start_span` — which defaults `with_parent:` to
+      # `Context.current` — picks it up as its parent automatically; no
+      # manual parent bookkeeping needed beyond attach/detach being
+      # correctly paired, same shape as the thread-local span stack this
+      # module already keeps for its own Span struct. Soft-detected: if
+      # the opentelemetry-sdk gem isn't loaded, this is a no-op and the
+      # instrumented method still runs normally, same contract as the New
+      # Relic path.
+      def start_open_telemetry_span(klass, method_name)
+        return nil unless @provider == :opentelemetry && defined?(OpenTelemetry::Trace)
+
+        tracer = OpenTelemetry.tracer_provider.tracer("scryer", Scryer::VERSION)
+        otel_span = tracer.start_span("#{klass.name}##{method_name}", kind: :internal)
+        token = OpenTelemetry::Context.attach(OpenTelemetry::Trace.context_with_span(otel_span))
+        [otel_span, token]
+      rescue StandardError => e
+        @logger.warn("[Scryer::APM] OpenTelemetry span start failed: #{e.message}") if @logger
+        nil
+      end
+
+      def finish_open_telemetry_span(segment, span)
+        return unless segment
+
+        otel_span, token = segment
+        if span.status == :error && span.exception_class
+          otel_span.record_exception(build_reportable_exception(span))
+          otel_span.status = OpenTelemetry::Trace::Status.error("#{span.exception_class}: #{span.exception_message || 'error'}")
+        end
+        otel_span.finish
+      rescue StandardError => e
+        @logger&.warn("[Scryer::APM] OpenTelemetry span finish failed: #{e.message}")
+      ensure
+        OpenTelemetry::Context.detach(token) if token
+      end
+
+      # NewRelic::Agent::Segment#notice_error wants a real exception object,
+      # not just a class name string — this reconstructs a minimal one
+      # carrying only what Span itself already decided to keep (never the
+      # original exception object, which could hold references to whatever
+      # arguments/state the traced method closed over).
+      def build_reportable_exception(span)
+        klass = Object.const_get(span.exception_class)
+        klass.exception(span.exception_message || span.exception_class)
+      rescue StandardError
+        StandardError.new(span.exception_class)
+      end
+
+      # Best-effort only, not exhaustive (see README limitations): masks
+      # substrings that look like tokens/secrets (long hex/base64-ish
+      # runs, email addresses) before an exception message is ever kept.
+      # Off entirely unless capture_exception_messages: true — the safer
+      # default is to keep the exception *class* only.
+      def redact_exception_message(message)
+        return nil unless message
+
+        message
+          .gsub(/[A-Za-z0-9_\-]{24,}/, "[REDACTED]")
+          .gsub(/[\w.+-]+@[\w-]+\.[a-zA-Z]{2,}/, "[REDACTED_EMAIL]")
+      end
+
+      def warn_if_provider_unavailable
+        return unless @instrumentation == :selective
+
+        case @provider
+        when :new_relic
+          return if defined?(NewRelic::Agent::Tracer)
+
+          @logger.warn(
+            "[Scryer::APM] provider: :new_relic but NewRelic::Agent isn't loaded — spans will be " \
+            "traced (available via Scryer::APM.on_span) but not exported anywhere."
+          )
+        when :opentelemetry
+          return if defined?(OpenTelemetry::Trace)
+
+          @logger.warn(
+            "[Scryer::APM] provider: :opentelemetry but the opentelemetry-sdk gem isn't loaded — " \
+            "spans will be traced (available via Scryer::APM.on_span) but not exported anywhere."
+          )
+        end
+      end
+
+      def default_logger
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger
+        else
+          require "logger"
+          Logger.new($stdout)
+        end
+      end
+
+      public
+
+      # Registers a callback invoked with every completed Span, regardless
+      # of provider — the hook the test suite uses to assert on spans
+      # directly, and available to any host app that wants its own
+      # sink (a log line, a metrics counter) alongside/instead of New Relic.
+      def on_span(&block)
+        @on_span = block
+      end
+    end
+
+    # `use Scryer::APM::Middleware` opens one trace per request, same
+    # per-request-scoping rationale as Scryer::QueryWatcher::Middleware.
+    class Middleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        result = nil
+        Scryer::APM.trace { result = @app.call(env) }
+        result
+      end
+    end
+  end
+end

data/lib/scryer/railtie.rb

@@ -1,13 +1,72 @@
 # frozen_string_literal: true
 module Scryer
-  # This gem runs on-demand via a rake task, not as request-cycle
-  # instrumentation — so the Railtie doesn't need to hook into the
-  # middleware stack or boot process at all. Its only job is to make sure
-  # requiring this gem inside a Rails app never raises, and to load the
+  # The static scan runs on-demand via a rake task, not as request-cycle
+  # instrumentation — that part of the Railtie's job is just making sure
+  # requiring this gem inside a Rails app never raises, and loading the
   # rake tasks into the host app's Rails console/`rake -T` listing.
+  #
+  # Scryer::APM (runtime method tracing) is the one exception: it *is*
+  # request-cycle instrumentation, and unlike QueryWatcher/AuthorizationWatcher
+  # (which the README has host apps wire up by hand — see
+  # docs/rails-integration.md) this one auto-wires itself when
+  # `Scryer.configuration.apm.enabled` is true, so setting that flag (plus
+  # `c.apm.include`) in an initializer is genuinely sufficient — no separate
+  # `require "scryer/apm"` / `Scryer::APM.enable!` / `middleware.use` calls
+  # needed. `after: :load_config_initializers` guarantees this runs after
+  # every file in config/initializers/ (including the host app's own
+  # scryer.rb) has already set that flag, regardless of alphabetical
+  # filename ordering.
   class Railtie < Rails::Railtie
     rake_tasks do
       load File.expand_path("../tasks/scryer.rake", __dir__)
     end
+
+    initializer "scryer.apm", after: :load_config_initializers do |app|
+      Scryer::Railtie.maybe_enable_apm(app)
+    end
+
+    # Plain Ruby, no Rails::Railtie API surface — pulled out of the
+    # `initializer` block above specifically so it's directly unit-testable
+    # (test/railtie_apm_test.rb) with a fake `app` (anything responding to
+    # `middleware.use`), without needing a real Rails app to boot. What this
+    # test *cannot* verify: that `after: :load_config_initializers` above
+    # actually fires at the right point in a real Rails boot sequence —
+    # that would need a real Rails app, which this gem's test suite doesn't
+    # depend on (see gemspec: zero runtime deps, Rails-optional).
+    #
+    # This method runs unattended during every boot of every host app that
+    # sets `c.apm.enabled = true` — a misconfigured `include` entry, an
+    # unimplemented `instrumentation` mode set by mistake, a `require`
+    # failure, anything — must degrade to "APM is off, logged once" rather
+    # than fail app boot. That's a materially different bar than the rest
+    # of Scryer::APM's public API (Scryer::APM.enable! called directly, in
+    # a console or test, DOES still raise for an unimplemented mode — fast,
+    # loud feedback is correct there, where a developer is watching).
+    # `rescue Exception` (not just StandardError) is deliberate here for
+    # the same reason: a boot-time LoadError from a packaging issue is a
+    # ScriptError, not a StandardError, and must be caught by this specific
+    # boundary too — re-raising SystemExit/NoMemoryError/SignalException
+    # keeps this from swallowing the handful of cases where propagating is
+    # still correct even at boot.
+    def self.maybe_enable_apm(app)
+      return unless Scryer.configuration.apm.enabled
+
+      require "scryer/apm"
+      Scryer::APM.enable!
+      app.middleware.use Scryer::APM::Middleware
+    rescue SystemExit, NoMemoryError, SignalException
+      raise
+    rescue Exception => e # rubocop-equivalent: intentional, see comment above
+      logger = (defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger) || begin
+        require "logger"
+        Logger.new($stderr)
+      end
+      logger.error(
+        "[Scryer::APM] enabling APM via c.apm.enabled failed (#{e.class}: #{e.message}) — " \
+        "APM is disabled for this process; the rest of the app boots normally. " \
+        "#{e.backtrace&.first(5)&.join("\n")}"
+      )
+      Scryer::APM.disable! if defined?(Scryer::APM)
+    end
   end
 end

data/lib/scryer/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Scryer
-  VERSION = "1.2.2"
+  VERSION = "1.3.0"
 end

data/lib/scryer.rb

@@ -55,6 +55,50 @@ module Scryer
     # configured default) if it's too noisy or too slow for a given project.
     attr_accessor :project_name, :dirs, :branch, :ai_client, :skip_rules, :detect_duplicates
 
+    # Runtime method-level tracing config (see Scryer::APM) — a separate
+    # nested config object, not flat attrs on Configuration itself, so
+    # `Scryer.configure { |c| c.apm.include = [...] }` reads the same way
+    # section 7 of this feature's own design doc illustrates it, and so
+    # APM's many options don't crowd the static-scan options above into a
+    # single flat namespace.
+    class APMConfiguration
+      # `provider` — :new_relic (soft-detected via
+      # `defined?(NewRelic::Agent::Tracer)`) and :opentelemetry (soft-detected
+      # via `defined?(OpenTelemetry::Trace)`) are implemented; spans just
+      # aren't exported anywhere if the configured provider's SDK isn't
+      # loaded. `instrumentation` — only
+      # :off and :selective exist; :discovery/:deep_trace raise from
+      # Scryer::APM.enable! (not implemented yet, see README). `include`/
+      # `exclude` — arrays of "ClassName"/"Module::ClassName" strings;
+      # `exclude` always additionally contains Scryer's own namespace plus
+      # a small framework-internals floor regardless of what's set here
+      # (see Scryer::APM::DEFAULT_EXCLUDE). `sampling_rate` — 0.0..1.0,
+      # applied once per Scryer::APM.trace scope (a whole request/job is
+      # either sampled or not, not decided span-by-span).
+      # `capture_exception_messages` — false by default: only the
+      # exception *class* is ever recorded unless explicitly opted in,
+      # and even then the message passes through a best-effort redaction
+      # pass (see Scryer::APM#redact_exception_message).
+      attr_accessor :enabled, :provider, :instrumentation, :include, :exclude, :sampling_rate,
+                    :capture_exception_messages
+
+      def initialize
+        @enabled = false
+        @provider = :new_relic
+        @instrumentation = :selective
+        @include = []
+        @exclude = []
+        @sampling_rate = 1.0
+        @capture_exception_messages = false
+      end
+    end
+
+    attr_writer :apm
+
+    def apm
+      @apm ||= APMConfiguration.new
+    end
+
     def initialize
       @dirs = Scryer::Scanner::DEFAULT_GLOB_DIRS
       @skip_rules = []
@@ -92,5 +136,9 @@ end
 # isn't required eagerly here to avoid loading active_support/notifications
 # machinery for the (default) case where nobody asked for it. Require it
 # yourself where you call .enable! (see README's "Runtime query watcher").
+#
+# Scryer::APM (runtime method-level tracing, see lib/scryer/apm.rb) is the
+# same story — opt-in, requires it yourself where you call .enable! (see
+# README's "Runtime method tracing").
 
 require "scryer/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: scryer
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Ram Laxman Yadav
@@ -76,6 +76,7 @@ files:
 - lib/scryer.rb
 - lib/scryer/ai_client.rb
 - lib/scryer/ai_fix_suggester.rb
+- lib/scryer/apm.rb
 - lib/scryer/ast.rb
 - lib/scryer/authorization_watcher.rb
 - lib/scryer/baseline.rb