safe_memoize 0.8.0 → 1.0.0

data/ROADMAP.md

@@ -4,34 +4,19 @@ This document tracks the planned evolution of SafeMemoize through v1.0.0 and bey
 
 ---
 
-## v0.9.0 — Observability & Ecosystem Integration
-
-*Goal: make SafeMemoize a first-class citizen in Rails/ActiveSupport stacks and in observability pipelines.*
-
-| Feature | Description | Status |
-|---|---|---|
-| ActiveSupport::Notifications integration | Emit `cache.hit`, `cache.miss`, `cache.evict`, and `cache.expire` events when ActiveSupport is available (opt-in via configuration) | Planned |
-| StatsD adapter | Thin optional module (`SafeMemoize::Adapters::StatsD`) that routes lifecycle hooks to a StatsD client with sensible metric names and tags | Planned |
-| OpenTelemetry spans | Optional adapter (`SafeMemoize::Adapters::OpenTelemetry`) wrapping computation time in a trace span for distributed tracing pipelines | Planned |
-| Rails request-scope helper | Guide + optional mixin for resetting instance memos at the end of each request (controller concern, middleware, or Active Model pattern) | Planned |
-| Formal benchmark suite | `benchmarks/` directory with comparisons against `memery`, `memo_wise`, and raw `||=`, covering single-threaded throughput and contention under concurrent load | Planned |
-| Concurrency stress tests | Dedicated spec suite hammering shared-cache paths and LRU eviction under high thread counts to surface race conditions | Planned |
-
----
-
 ## v1.0.0 — Stable API
 
 *Goal: declare a stable, semver-governed public API that downstream code can depend on with confidence.*
 
 | Feature | Description | Status |
 |---|---|---|
-| Semantic versioning guarantee | Document which constants, methods, and option keys are public API; breaking changes require a major bump henceforth | Planned |
-| Complete RBS + Sorbet signatures | Cover all public methods including overloads for optional keyword arguments; publish `.rbi` stubs as a companion package if demand warrants | Planned |
-| Full API reference | Generated documentation hosted on RubyDoc or a dedicated docs site; all public methods documented with parameter types, return values, and usage examples | Planned |
-| Ractor compatibility audit | Investigate and either support Ractor-compatible operation (Mutex replacement, shared-cache storage) or document the limitation clearly | Planned |
-| Ruby version policy | Formalise the supported Ruby version window and cadence for dropping EOL versions | Planned |
-| Deprecation sweep | Resolve or formally deprecate any unstable internal APIs before the stable release | Planned |
-| Upgrade guide | Document all breaking changes from 0.x and provide a migration path for users of deprecated behaviour | Planned |
+| Semantic versioning guarantee | Document which constants, methods, and option keys are public API; breaking changes require a major bump henceforth | Shipped |
+| Complete RBS + Sorbet signatures | Cover all public methods including overloads for optional keyword arguments; publish `.rbi` stubs as a companion package if demand warrants | Shipped |
+| Full API reference | Generated documentation hosted on RubyDoc or a dedicated docs site; all public methods documented with parameter types, return values, and usage examples | Shipped |
+| Ractor compatibility audit | Investigate and either support Ractor-compatible operation (Mutex replacement, shared-cache storage) or document the limitation clearly | Shipped |
+| Ruby version policy | Formalise the supported Ruby version window and cadence for dropping EOL versions | Shipped |
+| Deprecation sweep | Resolve or formally deprecate any unstable internal APIs before the stable release | Shipped |
+| Upgrade guide | Document all breaking changes from 0.x and provide a migration path for users of deprecated behaviour | Shipped |
 
 ---
 

data/Rakefile

@@ -7,4 +7,9 @@ RSpec::Core::RakeTask.new(:spec)
 
 require "standard/rake"
 
+require "yard"
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.options = ["--fail-on-warning"]
+end
+
 task default: %i[spec standard]

data/UPGRADING.md

@@ -0,0 +1,197 @@
+# Upgrading to SafeMemoize 1.0.0
+
+This guide covers every behavioral change introduced across the 0.x series that could affect code written against an earlier release. Work through the sections that apply to your starting version.
+
+---
+
+## Summary of breaking changes
+
+| Change | Introduced | Impact |
+|---|---|---|
+| Ruby 3.2 dropped | v0.5.0 | High if still on Ruby 3.2 |
+| TTL clock starts at first call, not definition | v0.6.0 | Medium — affects TTL precision |
+| `memo_keys`/`memo_values` shape for custom keys | v0.6.1 | Low — only if inspecting key metadata |
+| `memoize` raises at definition time for undefined methods | v0.8.0 | Medium — affects dynamic class construction |
+| Argument mutation no longer corrupts cache | v0.8.0 | Low — was silent bug; may surface latent test issues |
+| Hook exceptions no longer propagate | v0.8.0 | Medium — only if catching hook exceptions |
+| `memoized?` / introspection methods now respect custom keys | v1.0.0 | Low — bug fix; only if using custom keys |
+| `reset_memo` with args and `memo_refresh` respect custom keys | v1.0.0 | Low — bug fix; only if using custom keys |
+
+---
+
+## Upgrading from 0.1.x or 0.2.x
+
+Follow every section below in order.
+
+## Upgrading from 0.3.x – 0.4.x
+
+Follow sections starting from [Ruby 3.2 dropped](#ruby-32-dropped-v050).
+
+## Upgrading from 0.5.x
+
+Follow sections starting from [TTL clock fix](#ttl-clock-now-starts-at-first-call-v060).
+
+## Upgrading from 0.6.x
+
+Follow sections starting from [memoize on undefined methods](#memoize-on-an-undefined-method-raises-at-definition-time-v080).
+
+## Upgrading from 0.7.x – 0.9.x
+
+Follow sections starting from [custom key introspection fix](#introspection-methods-now-respect-custom-keys-v100).
+
+---
+
+## Ruby 3.2 dropped (v0.5.0)
+
+**Impact:** High — the gem will not install on Ruby 3.2.
+
+Ruby 3.2 reached end-of-life and was removed from the supported matrix in v0.5.0. The gemspec now enforces `ruby >= 3.3.0`.
+
+**Migration:** Upgrade to Ruby 3.3 or later before updating the gem.
+
+---
+
+## TTL clock now starts at first call, not definition (v0.6.0)
+
+**Impact:** Medium — affects how long entries actually live in the cache.
+
+Before v0.6.0, the TTL countdown began when `memoize :method, ttl: N` was evaluated (class load time). If a class was loaded 30 seconds before the first call, entries would expire 30 seconds earlier than expected.
+
+From v0.6.0 onwards, the clock starts on the first cache write — the entry lives for exactly `ttl` seconds after it is populated.
+
+**Migration:** No code change required. Entries now live for the duration you specified. If you intentionally set very short TTLs and relied on the early-start behaviour (unlikely), reduce your TTL value accordingly.
+
+---
+
+## `memo_keys`/`memo_values` shape change for custom-keyed entries (v0.6.1)
+
+**Impact:** Low — only affects code that reads the hashes returned by these methods.
+
+Before v0.6.1, entries stored via `memoize_with_custom_key` were surfaced in `memo_keys` and `memo_values` as:
+
+```ruby
+{ args: <the_custom_key>, kwargs: nil }
+```
+
+From v0.6.1 onwards they are correctly surfaced as:
+
+```ruby
+{ custom_key: <the_custom_key> }
+```
+
+**Migration:** If your code inspects the hash returned by `memo_keys` or `memo_values` and checks for an `:args` key to detect custom-keyed entries, update it to check for `:custom_key` instead:
+
+```ruby
+# Before
+entry[:args] # custom key was smuggled here
+
+# After
+entry[:custom_key] # explicit field
+entry[:args]       # only present for default-keyed entries
+```
+
+---
+
+## `memoize` on an undefined method raises at definition time (v0.8.0)
+
+**Impact:** Medium — affects any code that calls `memoize` before the method is defined,
+or that dynamically defines methods after `memoize` is called.
+
+Before v0.8.0, calling `memoize :missing_method` silently succeeded at class load time. The error only appeared at runtime when the memoized wrapper tried to call `super` and found nothing to call.
+
+From v0.8.0 onwards, `memoize` raises `ArgumentError` immediately if the named method does not exist at the time of the call.
+
+**Migration:** Ensure `memoize` is always called *after* the method it wraps:
+
+```ruby
+# Wrong — memoize called before def (raises ArgumentError in v0.8.0+)
+memoize :compute
+def compute = expensive_work
+
+# Correct
+def compute = expensive_work
+memoize :compute
+```
+
+If you use `Module#prepend` or `include` to add methods dynamically, make sure `memoize` is called after the module is prepended/included:
+
+```ruby
+include MyMethods   # defines :compute
+memoize :compute    # now safe
+```
+
+---
+
+## Argument mutation no longer corrupts the cache (v0.8.0)
+
+**Impact:** Low — this was a silent bug. Existing code is unlikely to rely on it, but test suites that mutate arguments after a call and expect a cache miss may need updating.
+
+Before v0.8.0, mutable cache keys (arrays, hashes, strings passed as arguments) were stored by reference. Mutating an argument after a call could cause the cache to behave unpredictably — sometimes missing on identical arguments, sometimes returning stale values.
+
+From v0.8.0 onwards, argument arrays, hashes, and strings are deep-frozen into an independent copy when the cache key is built. Callers can mutate their arguments after a call without affecting the cache.
+
+**Migration:** No migration required for production code. If a test mutates arguments after a memoized call and expects a cache miss, the test was relying on the buggy behaviour — update it to use distinct argument values instead.
+
+---
+
+## Hook exceptions no longer propagate to callers (v0.8.0)
+
+**Impact:** Medium — only affects code that wraps memoized calls in `rescue` to catch errors raised by hooks.
+
+Before v0.8.0, an exception raised inside an `on_memo_hit`, `on_memo_miss`, `on_memo_store`, `on_memo_expire`, or `on_memo_evict` hook would propagate through the memoized method call and be visible to the caller.
+
+From v0.8.0 onwards, hook exceptions are isolated. By default a `[SafeMemoize] Hook error in <type>: <message>` warning is written to `$stderr` and execution continues normally.
+
+**Migration:** If you need hook exceptions to propagate (e.g. in a strict test environment), configure `on_hook_error` to re-raise:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.on_hook_error = ->(error, hook_type, cache_key) { raise error }
+end
+```
+
+Or to route them to your error tracker without raising:
+
+```ruby
+SafeMemoize.configure do |c|
+  c.on_hook_error = ->(error, _type, _key) { Bugsnag.notify(error) }
+end
+```
+
+---
+
+## Introspection methods now respect custom keys (v1.0.0)
+
+**Impact:** Low — only affects code that uses `memoize_with_custom_key` or the `key:` option together with any of the introspection methods listed below.
+
+Before v1.0.0, the following methods looked up cache entries using the *default* key (derived from raw arguments) rather than the *custom* key generator. This meant they always returned incorrect results when a custom key was active:
+
+- `memoized?`
+- `memo_ttl_remaining`
+- `memo_touch`
+- `memo_age`
+- `memo_stale?`
+
+From v1.0.0 onwards, all five methods correctly call `compute_cache_key`, which checks for a custom key generator first.
+
+**Migration:** No code change required — the methods now return correct results. If your code had workarounds that bypassed these methods (e.g. manually inspecting `memo_keys` to determine if an entry existed), you can simplify them to use `memoized?` directly.
+
+---
+
+## `reset_memo` with args and `memo_refresh` respect custom keys (v1.0.0)
+
+**Impact:** Low — only affects code that uses custom keys and calls `reset_memo` with specific arguments, or calls `memo_refresh`.
+
+Before v1.0.0, `reset_memo(:method, *args)` with explicit arguments built a default key from raw args to match entries. When the method used a custom key generator, no entry was found and nothing was cleared. `memo_refresh` inherited the same flaw — the old entry survived and `refresh` returned the cached (stale) value instead of recomputing.
+
+From v1.0.0 onwards, both methods resolve the cache key through `compute_cache_key`.
+
+**Migration:** No code change required — the methods now behave correctly. Note that `reset_memo(:method)` with *no* arguments still clears all entries for the method regardless of key format; this behaviour is unchanged.
+
+---
+
+## New stable API
+
+All symbols listed in the README `## Public API and versioning guarantee` section are now covered by [Semantic Versioning](https://semver.org/) from v1.0.0 onwards. Breaking changes to any of those symbols require a major version bump.
+
+Opt-in extensions (`SafeMemoize::Rails`, `SafeMemoize::Adapters::StatsD`, `SafeMemoize::Adapters::OpenTelemetry`) are available but are *not* included in the v1.0.0 semver guarantee; they will be stabilised in a subsequent minor release.

data/benchmarks/README.md

@@ -0,0 +1,68 @@
+# SafeMemoize Benchmarks
+
+Measures throughput for cache hits, cache misses, argument-keyed lookups, and concurrent access. Optional comparison against `memery` and `memo_wise`.
+
+## Running
+
+```bash
+bundle exec ruby benchmarks/benchmark.rb
+```
+
+### With comparison gems
+
+```bash
+gem install memery memo_wise
+bundle exec ruby benchmarks/benchmark.rb
+```
+
+## Sections
+
+| # | Scenario | What it measures |
+|---|---|---|
+| 1 | Zero-arg cache hit | Steady-state throughput on a primed cache |
+| 2 | Zero-arg cache miss | First-call overhead (new instance per iteration) |
+| 3 | With-argument cache hit | Key construction + hash lookup with one positional arg |
+| 4 | Fast path vs locked path | Cost of `max_size:` (adds a Mutex for LRU promotion) |
+| 5 | Shared vs instance cache | Class-level vs per-instance cache throughput |
+| 6 | Concurrent cache hits | 8 threads × 50 000 iterations under contention |
+
+## Interpreting results
+
+**Cache hits are ~50–70× slower than raw `||=`** on a single thread — an expected trade-off. SafeMemoize does significantly more work per call: prepended-module dispatch, deep-frozen key construction, hook dispatch, and metrics tracking. The `||=` pattern is also incorrect for `nil`/`false` return values, which is the whole reason this gem exists.
+
+**The fast path vs locked path gap is ~1.3×.** The locked path (used when `max_size:`, `if:`, or `ttl_refresh:` is set) holds the Mutex for the full read-compute-write cycle; the fast path only acquires it for the write step.
+
+**Shared and instance caches are effectively identical in throughput.** Both paths go through the same Mutex; the class-level cache has one shared Mutex rather than one per instance.
+
+**Concurrent throughput is bounded by the Mutex.** Under 8-thread contention, all threads compete for the per-instance Mutex on every read, serialising access. This is the cost of correctness under concurrent writes; in read-heavy workloads where the cache is pre-warmed the contention is minimal.
+
+## Representative results (Apple M-series, Ruby 3.4, MRI)
+
+```
+1. Zero-arg cache HIT (primed cache)
+   raw safe ivar    ~22 M i/s
+   safe_memoize     ~335 K i/s  (65× slower than raw)
+
+2. Zero-arg cache MISS (new instance each iteration)
+   raw safe ivar    ~8 M i/s
+   safe_memoize     ~227 K i/s  (36× slower than raw)
+
+3. With-argument cache HIT
+   raw safe ivar    ~15 M i/s
+   safe_memoize     ~314 K i/s  (47× slower than raw)
+
+4. Fast path vs locked path
+   fast path        ~310 K i/s
+   max_size: 100    ~234 K i/s  (1.32× slower)
+
+5. Shared vs instance cache
+   instance cache   ~323 K i/s
+   shared cache     ~324 K i/s  (same-ish)
+
+6. Concurrent (8 threads × 50 000 iterations)
+   raw safe ivar         ~12 M i/s
+   safe_memoize (fast)  ~327 K i/s
+   safe_memoize (shared) ~323 K i/s
+```
+
+Results vary by hardware, Ruby version, and GVL scheduling. Run on your own hardware for authoritative numbers.

data/benchmarks/benchmark.rb

@@ -0,0 +1,225 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Run with: bundle exec ruby benchmarks/benchmark.rb
+#
+# Optional comparison gems (install separately if desired):
+#   gem install memery memo_wise
+#
+# Each section prints iterations/second and a comparison table.
+# Higher i/s is better.
+
+require "benchmark/ips"
+require_relative "../lib/safe_memoize"
+
+# ── Optional comparison gems ──────────────────────────────────────────────────
+
+HAS_MEMERY = begin
+  require "memery"
+  true
+rescue LoadError
+  warn "  [skip] memery not installed (gem install memery to include)"
+  false
+end
+
+HAS_MEMO_WISE = begin
+  require "memo_wise"
+  true
+rescue LoadError
+  warn "  [skip] memo_wise not installed (gem install memo_wise to include)"
+  false
+end
+
+# ── Subject classes ───────────────────────────────────────────────────────────
+
+# Raw patterns — no gem, for baseline reference
+class RawIvarUnsafe
+  # Classic ||= — fast but silently broken for nil/false return values
+  def compute = (@compute ||= 42)
+end
+
+class RawIvarSafe
+  # Safe raw pattern — correct but verbose
+  def compute
+    return @compute if defined?(@compute)
+    @compute = 42
+  end
+
+  def fetch(n)
+    @fetch ||= {}
+    return @fetch[n] if @fetch.key?(n)
+    @fetch[n] = n * 2
+  end
+end
+
+# SafeMemoize
+class SmZeroArg
+  prepend SafeMemoize
+  def compute = 42
+  memoize :compute
+end
+
+class SmWithArg
+  prepend SafeMemoize
+  def fetch(n) = n * 2
+  memoize :fetch
+end
+
+class SmLruPath
+  prepend SafeMemoize
+  def fetch(n) = n * 2
+  memoize :fetch, max_size: 100
+end
+
+class SmShared
+  prepend SafeMemoize
+  def compute = 42
+  memoize :compute, shared: true
+end
+
+# memery
+if HAS_MEMERY
+  class MemeryZeroArg
+    include Memery
+    memoize def compute = 42
+  end
+
+  class MemeryWithArg
+    include Memery
+    memoize def fetch(n) = n * 2
+  end
+end
+
+# memo_wise
+if HAS_MEMO_WISE
+  class MemoWiseZeroArg
+    prepend MemoWise
+    def compute = 42
+    memo_wise :compute
+  end
+
+  class MemoWiseWithArg
+    prepend MemoWise
+    def fetch(n) = n * 2
+    memo_wise :fetch
+  end
+end
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+IPS_CONFIG = {time: 5, warmup: 2}
+
+def section(title)
+  puts
+  puts "=" * 62
+  puts "  #{title}"
+  puts "=" * 62
+end
+
+# ── 1. Zero-arg cache HIT — steady-state throughput ──────────────────────────
+
+section "1. Zero-arg cache HIT  (steady-state, primed cache)"
+
+raw_unsafe = RawIvarUnsafe.new.tap(&:compute)
+raw_safe   = RawIvarSafe.new.tap(&:compute)
+sm_zero    = SmZeroArg.new.tap(&:compute)
+mem_zero   = MemeryZeroArg.new.tap(&:compute) if HAS_MEMERY
+mw_zero    = MemoWiseZeroArg.new.tap(&:compute) if HAS_MEMO_WISE
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("raw ||= (unsafe)")  { raw_unsafe.compute }
+  x.report("raw safe ivar")     { raw_safe.compute }
+  x.report("safe_memoize")      { sm_zero.compute }
+  x.report("memery")            { mem_zero.compute } if HAS_MEMERY
+  x.report("memo_wise")         { mw_zero.compute } if HAS_MEMO_WISE
+  x.compare!
+end
+
+# ── 2. Zero-arg cache MISS — first-call overhead ──────────────────────────────
+
+section "2. Zero-arg cache MISS  (new instance each iteration)"
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("raw safe ivar")  { RawIvarSafe.new.compute }
+  x.report("safe_memoize")   { SmZeroArg.new.compute }
+  x.report("memery")         { MemeryZeroArg.new.compute } if HAS_MEMERY
+  x.report("memo_wise")      { MemoWiseZeroArg.new.compute } if HAS_MEMO_WISE
+  x.compare!
+end
+
+# ── 3. With-argument cache HIT ────────────────────────────────────────────────
+
+section "3. With-argument cache HIT  (single fixed argument)"
+
+raw_arg  = RawIvarSafe.new.tap { |o| o.fetch(1) }
+sm_arg   = SmWithArg.new.tap { |o| o.fetch(1) }
+mem_arg  = MemeryWithArg.new.tap { |o| o.fetch(1) } if HAS_MEMERY
+mw_arg   = MemoWiseWithArg.new.tap { |o| o.fetch(1) } if HAS_MEMO_WISE
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("raw safe ivar")  { raw_arg.fetch(1) }
+  x.report("safe_memoize")   { sm_arg.fetch(1) }
+  x.report("memery")         { mem_arg.fetch(1) } if HAS_MEMERY
+  x.report("memo_wise")      { mw_arg.fetch(1) } if HAS_MEMO_WISE
+  x.compare!
+end
+
+# ── 4. Fast path vs locked path ───────────────────────────────────────────────
+
+section "4. Fast path vs locked path  (max_size: adds mutex for LRU)"
+
+sm_fast = SmWithArg.new.tap { |o| o.fetch(1) }
+sm_lru  = SmLruPath.new.tap { |o| o.fetch(1) }
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("fast path (no max_size)")   { sm_fast.fetch(1) }
+  x.report("locked path (max_size:100)") { sm_lru.fetch(1) }
+  x.compare!
+end
+
+# ── 5. Shared cache vs instance cache ────────────────────────────────────────
+
+section "5. Shared cache vs instance cache  (class-level vs instance-level)"
+
+sm_inst   = SmZeroArg.new.tap(&:compute)
+sm_shared = SmShared.new.tap(&:compute)
+
+Benchmark.ips do |x|
+  x.config(**IPS_CONFIG)
+  x.report("instance cache")  { sm_inst.compute }
+  x.report("shared cache")    { sm_shared.compute }
+  x.compare!
+end
+
+# ── 6. Concurrent cache hits under thread contention ─────────────────────────
+
+section "6. Concurrent cache hits  (8 threads × 50_000 iterations)"
+
+THREADS   = 8
+ITERS     = 50_000
+TOTAL     = THREADS * ITERS
+
+def bench_threaded(label, obj, method, *args)
+  ts = THREADS.times.map { Thread.new { ITERS.times { obj.public_send(method, *args) } } }
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  ts.each(&:join)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+  ips = TOTAL / elapsed
+  label_str = ips >= 1_000_000 ? format("%.2fM", ips / 1_000_000.0) : format("%.1fK", ips / 1_000.0)
+  printf "  %-34s %6.3fs  (%s i/s)\n", label, elapsed, label_str
+end
+
+puts
+
+bench_threaded("raw safe ivar",         raw_safe,   :compute)
+bench_threaded("safe_memoize (fast)",   sm_inst,    :compute)
+bench_threaded("safe_memoize (shared)", sm_shared,  :compute)
+bench_threaded("memery",                mem_zero,   :compute) if HAS_MEMERY
+bench_threaded("memo_wise",             mw_zero,    :compute) if HAS_MEMO_WISE
+
+puts
+puts "Done."

data/codecov.yml

@@ -0,0 +1,17 @@
+# Configure Pull Request Bot Comments
+comment:
+  layout: "reach, diff, flags, files"
+  behavior: default
+  # Only post or update the comment if the coverage drops
+  require_changes: "coverage_drop"
+
+# Configure Commit Status Checks (the green checkmark/red X list)
+coverage:
+  status:
+    project:
+      default:
+        # Prevent "Informational" mode so a drop causes an actual red failure check
+        informational: false
+    patch:
+      default:
+        informational: false

data/lib/safe_memoize/adapters/opentelemetry.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  # Optional adapters for external observability systems.
+  # None are auto-required; load them explicitly when needed.
+  module Adapters
+    # Optional OpenTelemetry adapter.
+    #
+    # Wraps each cache-miss computation in an OpenTelemetry span so the time
+    # spent computing uncached values is visible in distributed traces.
+    #
+    # Configure via {Configuration#opentelemetry_tracer}:
+    #
+    #   SafeMemoize.configure do |c|
+    #     c.opentelemetry_tracer = OpenTelemetry.tracer_provider.tracer("safe_memoize")
+    #   end
+    #
+    # Each span is named {SPAN_NAME} and carries the attributes
+    # +safe_memoize.method+, +safe_memoize.class+, and +safe_memoize.cache_hit+.
+    # Falls back to untraced execution when no tracer is configured or the tracer
+    # does not respond to +#in_span+.
+    module OpenTelemetry
+      # The name given to every span created by this adapter.
+      SPAN_NAME = "safe_memoize.compute"
+
+      # Wraps the block in a span if a tracer is available; otherwise yields directly.
+      #
+      # @param tracer [Object, nil] an object responding to +#in_span+
+      # @param method_name [Symbol, String]
+      # @param class_name [String, nil]
+      # @yield the computation block (cache-miss path)
+      # @return [Object] the result of the block
+      def self.trace(tracer, method_name, class_name)
+        return yield unless tracer&.respond_to?(:in_span)
+
+        tracer.in_span(SPAN_NAME, attributes: {
+          "safe_memoize.method" => method_name.to_s,
+          "safe_memoize.class" => class_name.to_s,
+          "safe_memoize.cache_hit" => false
+        }) { yield }
+      end
+    end
+  end
+end

data/lib/safe_memoize/adapters/statsd.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Adapters
+    # Optional StatsD adapter.
+    #
+    # Routes SafeMemoize lifecycle events to any StatsD-compatible client
+    # (any object that responds to +#increment+).
+    #
+    # Configure via {Configuration#statsd_client}:
+    #
+    #   SafeMemoize.configure do |c|
+    #     c.statsd_client = Datadog::Statsd.new
+    #   end
+    #
+    # Emitted metrics:
+    #
+    # | Metric | Fires on |
+    # |---|---|
+    # | +safe_memoize.hit+ | cache hit |
+    # | +safe_memoize.miss+ | cache miss |
+    # | +safe_memoize.store+ | value written |
+    # | +safe_memoize.evict+ | LRU eviction |
+    # | +safe_memoize.expire+ | TTL expiration |
+    #
+    # Every metric is tagged with +method:<name>+ and +class:<name>+.
+    # Client errors are rescued and warned rather than raised.
+    module StatsD
+      # @api private
+      METRIC_NAMES = {
+        on_hit: "safe_memoize.hit",
+        on_miss: "safe_memoize.miss",
+        on_evict: "safe_memoize.evict",
+        on_expire: "safe_memoize.expire",
+        on_store: "safe_memoize.store"
+      }.freeze
+
+      # Dispatches a lifecycle event to the StatsD client.
+      #
+      # @param client [Object] a StatsD-compatible client responding to +#increment+
+      # @param hook_type [Symbol] one of the keys in {METRIC_NAMES}
+      # @param cache_key [Array] the internal cache key (first element is the method name)
+      # @param class_name [String, nil]
+      # @return [void]
+      def self.dispatch(client, hook_type, cache_key, class_name)
+        metric = METRIC_NAMES[hook_type]
+        return unless metric
+
+        tags = ["method:#{cache_key[0]}", "class:#{class_name}"]
+        client.increment(metric, tags: tags)
+      rescue => error
+        warn "[SafeMemoize] StatsD dispatch error: #{error.message}"
+      end
+    end
+  end
+end

data/lib/safe_memoize/cache_metrics_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module CacheMetricsMethods
     private
 

data/lib/safe_memoize/cache_record_methods.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SafeMemoize
+  # @api private
   module CacheRecordMethods
     private