where_is_waldo 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96f9fb4253fa91bfaa947711aff7e9de6cf6511029c34fe4d24bcaa92be9958d
-  data.tar.gz: f441dacf17ca081d1974d08e3eb3460dce8ca5423772689c72e730c58746b8e9
+  metadata.gz: ce4ac18944bec996440772eed972216ff64975a1be13b4f7f3d0230e5cc0807f
+  data.tar.gz: 80e1f0ba820d24dc5f5d74f7ef4cc31e00ba3f183145d24de17dc24e5bd4b78b
 SHA512:
-  metadata.gz: df11e85496b2ae55c928695e1dad936a82b0d0b3abbcf8df7160932cf221f0ab4ab7c1cb8830cc5b710bbbab029cb82dfdb6d719292b0dc1863767151baf406c
-  data.tar.gz: 3412d9fd5475df5fe17a29c8dbd910f3c920db8260971492aa479ab23797d98d0c726549328aa27bdbef675646ae750f948c30ac810c96eaadddf6d8e1badcdf
+  metadata.gz: 877c8e0adf85cb7c8e75f992939c372690d1a928ab3ef4b6a4d64479ba9801ccd74820235db112d4efcab473a0589097165b62edf07824247a1a6be82d6ba32a
+  data.tar.gz: d91ec5e623c3a8e8b7b149d5d9a80d6110ab5f4a8c81cc71bdaa73608afc593efe534bc2dc53c71df067837fb56c1cac9479df52a421f7364d1b545cc7657018

data/CHANGELOG.md

@@ -3,6 +3,38 @@
 Notable changes to where_is_waldo. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## 0.1.10
+
+### Added
+
+- **Presence heartbeats are kept out of APM as their own transactions.**
+  `WhereIsWaldo::PresenceChannel#heartbeat` now runs inside
+  `WhereIsWaldo::Apm.ignoring_transaction`, so when a host app runs New Relic
+  the per-tab-per-interval heartbeat — the highest-volume, least-interesting
+  cable action — no longer surfaces as an APM transaction. Left unhandled it
+  inflates throughput and flatters average response time (heartbeats are
+  uniformly fast) while telling operators nothing the presence store can't
+  already answer.
+
+  - Guarded, no new dependency: `Apm` no-ops unless a supported agent
+    (New Relic today) is loaded, so consumers without APM pay nothing.
+  - Failures stay visible: an ignored New Relic transaction skips `commit!`,
+    where exceptions are normally harvested, so the wrapper hands any heartbeat
+    exception straight to the error collector and re-raises. Ignoring the
+    routine transaction never hides a heartbeat failure.
+  - Opt out with `config.ignore_heartbeat_apm = false` to report heartbeats
+    like any other action.
+  - Scope: New Relic only. The underlying exposure is agent-general — any APM
+    that opens a transaction per `perform_action` sees the same heartbeat
+    volume — but New Relic is the only agent seen in production so far.
+    Detection is isolated in `Apm.agent` so another vendor can be added there
+    without touching callers.
+
+  Note: the companion New Relic issue — the agent pinning the WebSocket upgrade
+  transaction onto pooled ActionCable worker threads — is a general
+  newrelic_rpm × ActionCable defect and stays a host-app shim; it is not
+  something the gem patches.
+
 ## 0.1.9
 
 Security/maintenance release — dependency bumps only, no library code changes.

data/README.md

@@ -113,6 +113,14 @@ WhereIsWaldo.configure do |config|
   config.timeout = 90                   # seconds until offline
   config.heartbeat_interval = 30
 
+  # Observability: when true (default) and the host app runs a supported APM
+  # agent (New Relic today), presence heartbeats are kept out of APM as their
+  # own transactions. Heartbeats are the highest-volume, least-interesting cable
+  # action, so reporting each one inflates throughput and flatters average
+  # response time without adding signal. Failures are still reported. Set false
+  # to report heartbeats like any other action.
+  config.ignore_heartbeat_apm = true
+
   # Optional: custom subject data in presence hash. NOTE: with the roster
   # enabled, these fields are broadcast to every member of the org — see
   # Security.

data/VERSION

@@ -1 +1 @@
-0.1.9
+0.1.10

data/app/channels/where_is_waldo/presence_channel.rb

@@ -32,7 +32,20 @@ module WhereIsWaldo
       publish_roster_change
     end
 
+    # Kept out of APM as its own transaction by default — heartbeats are the
+    # highest-volume, least-interesting cable action, so reporting each one
+    # distorts throughput and average response time without adding signal. The
+    # wrapper no-ops unless the host runs a supported agent; see
+    # WhereIsWaldo::Apm and config.ignore_heartbeat_apm. The real work lives in
+    # perform_heartbeat, which is private so a client can't invoke it directly
+    # as a channel action (only public methods are processable actions).
     def heartbeat(data)
+      WhereIsWaldo::Apm.ignoring_transaction { perform_heartbeat(data) }
+    end
+
+    private
+
+    def perform_heartbeat(data)
       return if presence_suppressed?
 
       data = data.with_indifferent_access
@@ -58,8 +71,6 @@ module WhereIsWaldo
       publish_roster_change
     end
 
-    private
-
     # Memoized per-subscription. Host apps configure suppress_presence_proc
     # to gate WHICH subscriptions register presence — e.g. a support-user
     # impersonation tab is a legitimate WS consumer but shouldn't count as

data/lib/where_is_waldo/apm.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  # APM (New Relic) integration seam.
+  #
+  # The gem takes NO hard dependency on newrelic_rpm. Every method here no-ops
+  # unless a supported agent is loaded in the host app, so a consumer without
+  # New Relic pays nothing and nothing breaks.
+  #
+  # Why this exists: ActionCable dispatches each client action through New
+  # Relic's ActionCableSubscriber, which starts one APM transaction per
+  # `perform_action`. Presence heartbeats are the highest-volume, least
+  # interesting action Waldo has — one per open tab per heartbeat interval,
+  # uniformly fast — so left alone they dominate transaction throughput and
+  # flatten the host app's average response time while telling operators nothing
+  # the presence store can't already answer. `ignoring_transaction` keeps them
+  # out of APM's headline numbers without hiding failures.
+  #
+  # (The companion half of this problem — the agent pinning the WebSocket
+  # upgrade transaction onto pooled ActionCable worker threads — is a general
+  # newrelic_rpm x ActionCable defect, not Waldo's to fix here. Host apps carry
+  # that shim until the agent resets pooled-thread state itself.)
+  #
+  # Scope: this handles New Relic ONLY. The underlying exposure is agent-general
+  # — any APM/tracer that opens a transaction per `perform_action` (Datadog,
+  # Scout, AppSignal, Skylight, Sentry, OpenTelemetry) sees the same heartbeat
+  # flood, and several share the same pooled-thread context-leak. Waldo doesn't
+  # cause that (it spawns no threads and patches nothing global); its heartbeat
+  # volume amplifies whatever the host's agent already does. Detection is
+  # isolated in `agent` so another vendor can be added there without touching
+  # callers.
+  module Apm
+    module_function
+
+    # The New Relic agent module, or nil when newrelic_rpm isn't loaded (or is
+    # too old to expose the API we use). Isolated behind one method so specs can
+    # drive both the present and absent paths without defining a global
+    # ::NewRelic constant.
+    def agent
+      return nil unless defined?(::NewRelic::Agent)
+      return nil unless ::NewRelic::Agent.respond_to?(:ignore_transaction)
+
+      ::NewRelic::Agent
+    end
+
+    # Run a unit of work without letting it surface as its own APM transaction,
+    # and return the block's value.
+    #
+    # A plain `yield` when there's no agent, or when the host has opted out via
+    # `config.ignore_heartbeat_apm = false` — in either case the transaction is
+    # reported normally.
+    #
+    # New Relic's `Transaction#ignore!` makes `#finish` skip `commit!`, and
+    # `commit!` is where transaction-attached exceptions are harvested
+    # (`record_exceptions`). So ignoring on its own would ALSO swallow a
+    # heartbeat failure. We hand any exception straight to the error collector —
+    # which reports immediately rather than at commit — and re-raise, so the
+    # caller's own error handling is unchanged.
+    def ignoring_transaction
+      nr = agent
+      return yield unless nr && WhereIsWaldo.config.ignore_heartbeat_apm
+
+      nr.ignore_transaction
+
+      begin
+        yield
+      rescue StandardError => e
+        nr.instance&.error_collector&.notice_error(e)
+        raise
+      end
+    end
+  end
+end

data/lib/where_is_waldo/configuration.rb

@@ -27,6 +27,15 @@ module WhereIsWaldo
     # :heartbeat_interval - expected heartbeat frequency (default: 30)
     attr_accessor :timeout, :heartbeat_interval
 
+    # Observability
+    # :ignore_heartbeat_apm - when true (default) and a supported APM agent
+    #   (New Relic) is loaded in the host app, presence heartbeats are kept out
+    #   of APM as their own transactions. Heartbeats are the highest-volume,
+    #   least-interesting cable action, so reporting each one distorts
+    #   throughput and average response time without adding signal. Set false
+    #   to report them like any other action. See WhereIsWaldo::Apm.
+    attr_accessor :ignore_heartbeat_apm
+
     # ActionCable settings
     # :channel_name - defaults to 'WhereIsWaldo::PresenceChannel'
     # :authenticate_proc - proc to authenticate connection, receives request
@@ -120,6 +129,9 @@ module WhereIsWaldo
       @timeout = 90
       @heartbeat_interval = 30
 
+      # Observability defaults
+      @ignore_heartbeat_apm = true
+
       # ActionCable defaults
       @channel_name = "WhereIsWaldo::PresenceChannel"
       @authenticate_proc = nil

data/lib/where_is_waldo.rb

@@ -2,6 +2,7 @@
 
 require "where_is_waldo/version"
 require "where_is_waldo/configuration"
+require "where_is_waldo/apm"
 require "where_is_waldo/engine" if defined?(Rails)
 
 module WhereIsWaldo

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: where_is_waldo
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.10
 platform: ruby
 authors:
 - Scott Gibson
@@ -215,6 +215,7 @@ files:
 - lib/generators/where_is_waldo/install/templates/migration.rb.tt
 - lib/generators/where_is_waldo/install/templates/presence_channel.rb.tt
 - lib/where_is_waldo.rb
+- lib/where_is_waldo/apm.rb
 - lib/where_is_waldo/configuration.rb
 - lib/where_is_waldo/engine.rb
 - lib/where_is_waldo/version.rb