idempotency 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79c1c3a64979f50848f56726163b1210fef91763d50b77fd31f7ed87629a14df
-  data.tar.gz: 45305008439d1db703c550a4a684c44771329a7d2189faba567b94ec673d21d0
+  metadata.gz: b90e384bed1ce0ef7d2e3aeb46f4e2f7d6f822e584d805234762e42d05500ef0
+  data.tar.gz: 61d0164bd2b498d160b486082298382d6d3ceef04aca2eca7b61c620ae9e0e6c
 SHA512:
-  metadata.gz: 9e9db8c50c5abccf8985e813cd096f4b6ea6198a2ad363877d962f0d9703cce77661415eb949e1216803e053dceff5ae8f943a3f66161ea95da02d5f774e15ff
-  data.tar.gz: 1d3c09a3f939065bc09a5fcc556fbc724c409335824ef92456148541a31b9b50d49139db6049299a4669f8fc7c8d41d9923602132d4cdd97a9431ce16fdf9b19
+  metadata.gz: e3e0d18d788ef5a769450e741fecc05a496cecc829034047d3595b8b667b14bee0cac210c94d815058f95382996075c4e6b95d2f5c8856edcb3748ddf97f715f
+  data.tar.gz: ee15500014c64c54c7bb6746c6d4c4ee28bf4a6d69d9a47682514fc4d2bc6e48275a7c759907eb625a6a7f0b36baf99e59b5991a1442fdde2ddec4ad1cd6216f

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Change Log]
 
+## [0.3.0] - 2025-11-14
+
+- Add AppSignal integration for transaction tracking in trace stacks
+- Add Sentry integration for transaction tracking in trace stacks
+- Add observability configuration options (appsignal_enabled, sentry_enabled)
+
 ## [0.2.0] - 2025-07-28
 
 - Enforce explicit monkey-patch requirement

data/Gemfile

@@ -13,3 +13,6 @@ gem 'dry-monitor'
 gem 'hanami-controller', '~> 1.3'
 gem 'pry-byebug'
 gem 'rubocop', '~> 1.21'
+
+# Optional observability integrations for testing
+gem 'appsignal', '>= 1.3.0'

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    idempotency (0.2.0)
+    idempotency (0.3.0)
+      appsignal (>= 1.3.0)
       base64
       dry-configurable
       dry-monitor
@@ -11,6 +12,8 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    appsignal (3.13.1)
+      rack
     ast (2.4.2)
     base64 (0.2.0)
     byebug (11.1.3)
@@ -97,6 +100,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  appsignal (>= 1.3.0)
   connection_pool
   dry-monitor
   hanami-controller (~> 1.3)

data/README.md

@@ -34,6 +34,11 @@ Idempotency.configure do |config|
   config.metrics.statsd_client = statsd_client # Your StatsD client instance
   config.metrics.namespace = 'my_service_name' # Optional namespace for metrics
 
+  # APM/Observability configuration (optional) - adds method to trace stacks
+  # You can enable one or both observability tools simultaneously
+  config.observability.appsignal_enabled = true  # Enable AppSignal transaction tracking
+  config.observability.sentry_enabled = true     # Enable Sentry transaction tracking
+
   # Custom instrumentation listeners (optional)
   config.instrumentation_listeners = [my_custom_listener] # Array of custom listeners
 end
@@ -110,7 +115,11 @@ end
 
 ### Instrumentation
 
-The gem supports instrumentation through StatsD out of the box. When you configure a StatsD client in the configuration, the StatsdListener will be automatically set up. It tracks the following metrics:
+The gem supports instrumentation through multiple observability platforms:
+
+#### StatsD
+
+When you configure a StatsD client in the configuration, the StatsdListener will be automatically set up. It tracks the following metrics:
 
 - `idempotency_cache_hit_count` - Incremented when a cached response is found
 - `idempotency_cache_miss_count` - Incremented when no cached response exists
@@ -122,7 +131,7 @@ Each metric includes tags:
 - `namespace` - Your configured namespace (if provided)
 - `metric` - The metric name (for duration histogram only)
 
-To enable StatsD instrumentation, simply configure the metrics settings:
+To enable StatsD instrumentation:
 
 ```ruby
 Idempotency.configure do |config|
@@ -130,3 +139,30 @@ Idempotency.configure do |config|
   config.metrics.namespace = 'my_service_name'
 end
 ```
+
+#### AppSignal
+
+The gem can add the `use_cache` method to AppSignal transaction traces when enabled. This allows you to see the idempotency check as part of your request traces and helps identify performance bottlenecks.
+
+To enable AppSignal transaction tracking:
+
+```ruby
+Idempotency.configure do |config|
+  config.observability.appsignal_enabled = true
+end
+```
+
+Note: The AppSignal gem must be installed and configured in your application.
+
+#### Using Both AppSignal and Sentry
+
+You can enable both observability tools simultaneously. When both are enabled, the `use_cache` method will be instrumented in both APM systems with nested transactions:
+
+```ruby
+Idempotency.configure do |config|
+  config.observability.appsignal_enabled = true
+  config.observability.sentry_enabled = true
+end
+```
+
+This allows you to see the idempotency check in both your AppSignal and Sentry dashboards, providing comprehensive observability across your monitoring stack.

data/idempotency.gemspec

@@ -39,4 +39,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'dry-monitor'
   spec.add_dependency 'msgpack'
   spec.add_dependency 'redis'
+
+  spec.add_dependency 'appsignal', '>= 1.3.0'
 end

data/lib/idempotency/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Idempotency
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/idempotency.rb

@@ -8,7 +8,7 @@ require_relative 'idempotency/constants'
 require_relative 'idempotency/instrumentation/statsd_listener'
 require 'dry-monitor'
 
-class Idempotency
+class Idempotency # rubocop:disable Metrics/ClassLength
   extend Dry::Configurable
   @monitor = Monitor.new
 
@@ -28,6 +28,10 @@ class Idempotency
     setting :statsd_client
   end
 
+  setting :observability do
+    setting :appsignal_enabled, default: false
+  end
+
   setting :default_lock_expiry, default: 300 # 5 minutes
   setting :idempotent_methods, default: %w[POST PUT PATCH DELETE]
   setting :idempotent_statuses, default: (200..299).to_a + (400..499).to_a
@@ -60,41 +64,46 @@ class Idempotency
     new.use_cache(request, request_identifiers, lock_duration:, action:, &blk)
   end
 
-  def use_cache(request, request_identifiers, lock_duration: nil, action: nil) # rubocop:disable Metrics/AbcSize
+  # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+  def use_cache(request, request_identifiers, lock_duration: nil, action: nil)
     duration_start = Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+    action_name = action || "#{request.request_method}:#{request.path}"
 
-    return yield unless cache_request?(request)
+    with_apm_instrumentation('idempotency.use_cache', action_name) do
+      return yield unless cache_request?(request)
 
-    request_headers = request.env
-    idempotency_key = unquote(request_headers[Constants::RACK_HEADER_KEY] || SecureRandom.hex)
+      request_headers = request.env
+      idempotency_key = unquote(request_headers[Constants::RACK_HEADER_KEY] || SecureRandom.hex)
 
-    fingerprint = calculate_fingerprint(request, idempotency_key, request_identifiers)
+      fingerprint = calculate_fingerprint(request, idempotency_key, request_identifiers)
 
-    cached_response = cache.get(fingerprint)
+      cached_response = cache.get(fingerprint)
 
-    if (cached_status, cached_headers, cached_body = cached_response)
-      cached_headers.merge!(Constants::HEADER_KEY => idempotency_key)
-      instrument(Events::CACHE_HIT, request:, action:, duration: calculate_duration(duration_start))
+      if (cached_status, cached_headers, cached_body = cached_response)
+        cached_headers.merge!(Constants::HEADER_KEY => idempotency_key)
+        instrument(Events::CACHE_HIT, request:, action:, duration: calculate_duration(duration_start))
 
-      return [cached_status, cached_headers, cached_body]
-    end
+        return [cached_status, cached_headers, cached_body]
+      end
 
-    lock_duration ||= config.default_lock_expiry
-    response_status, response_headers, response_body = cache.with_lock(fingerprint, lock_duration) do
-      yield
-    end
+      lock_duration ||= config.default_lock_expiry
+      response_status, response_headers, response_body = cache.with_lock(fingerprint, lock_duration) do
+        yield
+      end
 
-    if cache_response?(response_status)
-      cache.set(fingerprint, response_status, response_headers, response_body)
-      response_headers.merge!({ Constants::HEADER_KEY => idempotency_key })
-    end
+      if cache_response?(response_status)
+        cache.set(fingerprint, response_status, response_headers, response_body)
+        response_headers.merge!({ Constants::HEADER_KEY => idempotency_key })
+      end
 
-    instrument(Events::CACHE_MISS, request:, action:, duration: calculate_duration(duration_start))
-    [response_status, response_headers, response_body]
+      instrument(Events::CACHE_MISS, request:, action:, duration: calculate_duration(duration_start))
+      [response_status, response_headers, response_body]
+    end
   rescue Idempotency::Cache::LockConflict
     instrument(Events::LOCK_CONFLICT, request:, action:, duration: calculate_duration(duration_start))
     [409, {}, config.response_body.concurrent_error]
   end
+  # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
 
   private
 
@@ -137,4 +146,14 @@ class Idempotency
       str
     end
   end
+
+  def with_apm_instrumentation(name, action, &)
+    if config.observability.appsignal_enabled
+      Appsignal.instrument(name, action) do
+        yield
+      end
+    else
+      yield
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: idempotency
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Vu Hoang
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-28 00:00:00.000000000 Z
+date: 2025-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: appsignal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.0
 description: Caching requests for idempotency purpose
 email: vu.hoang@ascenda.com
 executables: []