active_sanction 1.0.1 → 1.1.1

data/lib/active_sanction/index.rb

@@ -144,6 +144,28 @@ module ActiveSanction
     # numbers again on another machine.
     POSTINGS_BUDGET = T.let(5_000, Integer)
 
+    # One posting: an Integer in an Array slot, which on a 64-bit CRuby is a
+    # tagged immediate and costs the slot and nothing else. See #profile,
+    # which is where these three are used and where their crudeness is
+    # admitted.
+    #
+    # @api private
+    POSTING_BYTES = T.let(8, Integer)
+
+    # One distinct feature: a short String -- a token, a trigram, a metaphone
+    # key -- plus its slot in a posting Hash and the empty Array header the
+    # slot points at. Measured as an order of magnitude rather than counted.
+    #
+    # @api private
+    FEATURE_BYTES = T.let(120, Integer)
+
+    # One indexed name: an Entry and the Normalizer::Form it holds, both small
+    # objects of references. The Entity and Name they point at belong to the
+    # snapshot and are not counted here.
+    #
+    # @api private
+    ENTRY_BYTES = T.let(200, Integer)
+
     # Entries, in the order they were indexed. The posting lists hold
     # positions in this array.
     sig { returns(T::Array[Entry]).checked(:tests) }
@@ -247,6 +269,45 @@ module ActiveSanction
       }
     end
 
+    # How big this index is, as the `index.build` event reports it: names,
+    # distinct features, postings, and an estimate of what it all weighs.
+    #
+    # Deliberately not #stats, and the difference is the one number #stats
+    # carries that this does not. Counting distinct entities means walking
+    # every entry and uniquing 47,000 ids, which is a fine thing to do in a
+    # benchmark and not a thing to do at the end of every index build -- it
+    # allocates at exactly the moment the heap is already at its peak, with
+    # the snapshot, the builder and the finished index all still alive. The
+    # event reports entity count from the snapshots it read instead, where it
+    # is already known.
+    #
+    # **`bytes` is an estimate, and deliberately a crude one.** Ruby offers no
+    # way to ask what an object graph weighs that does not either walk every
+    # object in the heap or lie, and an index is tens of millions of small
+    # objects. What it counts is the three things that dominate: a posting is
+    # an Integer in an Array slot, a distinct feature is a String plus its
+    # slot in a Hash, and an entry is a small object holding references. What
+    # it deliberately does not count is the Entities and Names themselves --
+    # those are the snapshot's, shared with it rather than owned here, and
+    # counting them would report the same megabytes twice to a host watching
+    # both.
+    #
+    # Good to within a factor a dashboard cares about, which is what "is the
+    # index growing?" and "will another list fit?" actually need. Anything
+    # finer wants a real heap profiler.
+    sig { returns(T::Hash[Symbol, Integer]).checked(:tests) }
+    def profile
+      keys = @tokens.size + @trigrams.size + @phonetics.size
+      # `each_value` rather than a two-parameter block over the Hash: iterating
+      # a Hash as pairs allocates a two-element Array per distinct feature,
+      # which is twenty thousand short-lived objects at the exact moment the
+      # heap is at its peak -- the snapshot, the builder and the finished
+      # index all still alive. #stats can afford that and a build cannot.
+      postings = [@tokens, @trigrams, @phonetics].sum { |space| space.each_value.sum(&:size) }
+      { names: entries.size, keys: keys, postings: postings,
+        bytes: (postings * POSTING_BYTES) + (keys * FEATURE_BYTES) + (entries.size * ENTRY_BYTES) }
+    end
+
     sig { returns(String) }
     def inspect = "#<#{self.class} #{size} names>"
 

data/lib/active_sanction/instrumentation/event.rb

@@ -0,0 +1,122 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module ActiveSanction
+  module Instrumentation
+    # One thing this library did, after it finished doing it.
+    #
+    #   ActiveSanction.configure do |c|
+    #     c.instrumenter = ->(event) { StatsD.timing("sanctions.#{event.name}", event.duration_ms) }
+    #   end
+    #
+    #   event.name       # => :fetch
+    #   event.duration   # => 2.418, seconds
+    #   event[:source]   # => :ofac_sdn
+    #   event[:bytes]    # => 12_845_056
+    #
+    # A subscriber is handed a finished event and never a running one. That is
+    # the difference between this and a block-based instrumenter, and it is
+    # deliberate: a subscriber that cannot wrap the work cannot retry it,
+    # cannot swallow its exception, and cannot leave a `begin` half-entered if
+    # it raises. The cost is that nothing here can time a stage from the
+    # outside -- which nothing needs to, since every event already carries its
+    # own duration.
+    #
+    # ### Every event carries a duration and enough to correlate it
+    #
+    # There are no anonymous timings. `duration` is monotonic seconds, taken
+    # across the stage this event describes, and `started_at` is the wall
+    # clock at its start -- both, because one answers "how long did it take"
+    # and the other answers "when, in the log I am reading beside this". Every
+    # event but `screen` names a `source`; `screen` names the snapshot
+    # checksums it consulted, which is the same question asked of a query.
+    #
+    # ### An event is emitted for work that raised
+    #
+    # With `error` set to the exception, and with whichever payload keys the
+    # stage had filled in before it failed. A publisher that starts timing out
+    # is exactly what a host is watching for, and an instrumentation layer
+    # that only reports successes cannot see it. See Instrumentation.
+    #
+    # Frozen, and its payload with it, so a subscriber cannot edit what the
+    # next one is handed.
+    class Event
+      extend T::Sig
+
+      # The stage this event describes -- one of Instrumentation::EVENTS.
+      sig { returns(Symbol) }
+      attr_reader :name
+
+      # What the stage measured, keyed as documented for each event name in
+      # docs/api_stability.md. Frozen.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      attr_reader :payload
+
+      # The wall clock when the stage started, UTC. For lining an event up
+      # against a log; `duration` is what to measure with.
+      sig { returns(Time) }
+      attr_reader :started_at
+
+      # Seconds the stage took, from a monotonic clock, so it is not moved by
+      # a clock adjustment mid-stage.
+      sig { returns(Float) }
+      attr_reader :duration
+
+      sig do
+        params(name: Symbol, payload: T::Hash[Symbol, T.untyped], started_at: Time, duration: Float).void
+      end
+      def initialize(name:, payload:, started_at:, duration:)
+        @name = T.let(name, Symbol)
+        @payload = T.let(payload.freeze, T::Hash[Symbol, T.untyped])
+        @started_at = T.let(started_at, Time)
+        @duration = T.let(duration, Float)
+        freeze
+      end
+
+      # One payload key, or nil for one this event does not carry.
+      sig { params(key: Symbol).returns(T.untyped) }
+      def [](key) = payload[key]
+
+      # Which list this was about, or nil for an event that is not about one
+      # -- `screen`, which is about a query, and `sync`, which is about a run.
+      sig { returns(T.nilable(Symbol)) }
+      def source = payload[:source]
+
+      # The exception the stage raised, or nil for one that finished. An event
+      # carrying one is a partial measurement: the keys the stage had not
+      # reached are absent rather than zero.
+      sig { returns(T.nilable(StandardError)) }
+      def error = payload[:error]
+
+      sig { returns(T::Boolean) }
+      def failed? = !error.nil?
+
+      # The wall clock when the stage finished. Derived from `started_at` and
+      # the monotonic duration rather than read again, so the two cannot
+      # disagree about how long this took.
+      sig { returns(Time) }
+      def finished_at = started_at + duration
+
+      # Milliseconds, which is what a metrics backend usually wants.
+      sig { returns(Float) }
+      def duration_ms = (duration * 1_000).round(3).to_f
+
+      # The whole event as one Hash, for a subscriber that forwards it
+      # somewhere structured. The payload is spread in at the top level, and
+      # its keys win over nothing -- `name`, `started_at` and `duration` are
+      # not payload keys on any event this library emits.
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h
+        { name: name, started_at: started_at, duration: duration }.merge(payload)
+      end
+
+      sig { returns(String) }
+      def to_s = "#{name} #{format("%.3f", duration)}s#{" #{source}" if source}#{" failed" if failed?}"
+
+      sig { returns(String) }
+      def inspect = "#<#{self.class} #{name} #{payload.inspect} #{format("%.3f", duration)}s>"
+    end
+  end
+end

data/lib/active_sanction/instrumentation/notifications.rb

@@ -0,0 +1,122 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/error"
+
+module ActiveSanction
+  module Instrumentation
+    # Republishes every event into `ActiveSupport::Notifications`, for a host
+    # that already has subscribers, log tags and a dashboard pointed there.
+    #
+    #   # config/initializers/active_sanction.rb
+    #   ActiveSanction.configure do |c|
+    #     c.instrumenter = ActiveSanction::Instrumentation::Notifications.new
+    #   end
+    #
+    #   ActiveSupport::Notifications.subscribe("screen.active_sanction") do |event|
+    #     Rails.logger.info("screened in #{event.duration.round(1)}ms: #{event.payload[:results]} hits")
+    #   end
+    #
+    # Names are `<event>.active_sanction` -- `fetch.active_sanction`,
+    # `index.build.active_sanction`, and so on -- which is the namespacing
+    # convention every ActiveSupport subscriber already expects, so
+    # `subscribe(/\.active_sanction\z/)` picks up all six.
+    #
+    # ### It is an adapter, not a dependency
+    #
+    # **Nothing in this gem requires ActiveSupport**, and this file does not
+    # either -- it names `::ActiveSupport::Notifications` and never loads it.
+    # Zero required runtime dependencies is a promise this library keeps for
+    # the API container it is going to run in, and a notification adapter is
+    # not a reason to break it. Building one in a process that has not loaded
+    # ActiveSupport raises ConfigurationError rather than quietly instrumenting
+    # nothing, because a subscriber that is not recording is a dashboard that
+    # is wrong rather than missing.
+    #
+    # ### Events arrive finished
+    #
+    # `publish` rather than `instrument`: this library has already done the
+    # work and timed it, and re-wrapping a finished event in a block would put
+    # an ActiveSupport subscriber around a stage it cannot influence while
+    # reporting a duration measured somewhere else. Subscribers see a normal
+    # `ActiveSupport::Notifications::Event` with real start and finish times.
+    #
+    # A stage that raised carries the two keys ActiveSupport's own subscribers
+    # look for -- `:exception`, the `[class, message]` pair, and
+    # `:exception_object` -- beside this library's `:error`, so a Rails host's
+    # existing error reporting sees it without being taught anything.
+    class Notifications
+      extend T::Sig
+
+      # The suffix every published name carries.
+      NAMESPACE = T.let("active_sanction", String)
+
+      sig { returns(String) }
+      attr_reader :namespace
+
+      # Whatever the events are published through -- `ActiveSupport::Notifications`
+      # itself unless a host named its own notifier.
+      sig { returns(T.untyped) }
+      attr_reader :notifier
+
+      # @param namespace [String] the suffix published names carry. Change it
+      #   only to keep two installations of this gem apart in one process.
+      # @param notifier [#publish, nil] defaults to `ActiveSupport::Notifications`,
+      #   resolved now rather than per event so that a process without it
+      #   fails here, at the line that configured it.
+      sig { params(namespace: String, notifier: T.untyped).void }
+      def initialize(namespace: NAMESPACE, notifier: nil)
+        @namespace = T.let(namespace.to_s, String)
+        @notifier = T.let(notifier || default_notifier, T.untyped)
+        return if @notifier.respond_to?(:publish)
+
+        raise ConfigurationError, "an ActiveSupport::Notifications adapter needs a notifier answering " \
+                                  "#publish, got #{@notifier.class}"
+      end
+
+      # Publishes one finished event. Called by Instrumentation, which has
+      # already isolated it: an exception raised in here is reported and
+      # dropped rather than reaching the sync that emitted the event.
+      sig { params(event: Event).returns(T.untyped) }
+      def call(event)
+        notifier.publish("#{event.name}.#{namespace}", event.started_at, event.finished_at, event_id,
+                         payload_for(event))
+      end
+
+      sig { returns(String) }
+      def inspect = "#<#{self.class} #{notifier.class} *.#{namespace}>"
+
+      private
+
+      sig { returns(T.untyped) }
+      def default_notifier
+        unless defined?(::ActiveSupport::Notifications)
+          raise ConfigurationError,
+                "ActiveSupport::Notifications is not loaded. This gem does not depend on ActiveSupport and " \
+                "will not require it -- load it yourself, or set c.instrumenter to any object answering " \
+                "#call(event)."
+        end
+
+        ::ActiveSupport::Notifications
+      end
+
+      # ActiveSupport's own per-thread instrumenter id, so an event published
+      # here is correlated with the ones a host's own `instrument` calls
+      # publish on the same thread.
+      sig { returns(String) }
+      def event_id
+        notifier.respond_to?(:instrumenter) ? notifier.instrumenter.id : "#{Process.pid}-#{Thread.current.object_id}"
+      end
+
+      sig { params(event: Event).returns(T::Hash[Symbol, T.untyped]) }
+      def payload_for(event)
+        error = event.error
+        return event.payload if error.nil?
+
+        event.payload.merge(exception: [error.class.name, error.message], exception_object: error)
+      end
+    end
+  end
+end

data/lib/active_sanction/instrumentation.rb

@@ -0,0 +1,245 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "active_sanction/error"
+require "active_sanction/instrumentation/event"
+require "active_sanction/instrumentation/notifications"
+
+module ActiveSanction
+  # Structured events from every stage, so a host can measure this library
+  # without monkeypatching it.
+  #
+  #   ActiveSanction.configure do |c|
+  #     c.instrumenter = ->(event) do
+  #       StatsD.timing("sanctions.#{event.name}", event.duration_ms, tags: ["source:#{event.source}"])
+  #     end
+  #   end
+  #
+  # Six events, and they are the operational questions a compliance
+  # installation is actually asked: is the data fresh, did a fetch fail, how
+  # long did screening take, which source is degrading.
+  #
+  # | Event | Emitted by | Asks |
+  # |---|---|---|
+  # | `:fetch` | Fetcher | Did bytes move, and what did the publisher answer? |
+  # | `:parse` | Sources::Base | How many records came out, and how many rows could not be read? |
+  # | `:store` | Sync, Client#import | Which list version was written, and how big is it? |
+  # | `:"index.build"` | Matcher.build | What did building the index cost, and how much is resident? |
+  # | `:screen` | Matcher | How long did a query take, and what did it consult? |
+  # | `:sync` | Sync | What did a whole run do? |
+  #
+  # The payload keys of each are enumerated in
+  # [`docs/api_stability.md`](../../docs/api_stability.md) and are public API:
+  # a dashboard built on them is held to the same promise as a method call, and
+  # a key is not removed or repurposed without the deprecation path. Keys may
+  # be **added** to an event, so a subscriber reads the keys it knows and
+  # ignores the rest.
+  #
+  # ### A subscriber is anything answering `#call(event)`
+  #
+  # A lambda, a Method, an object with a `call`. There is no registry and no
+  # base class to inherit, because the whole interface is one method and a
+  # registry would be a second thing to configure. A host wanting several
+  # subscribers composes them itself -- `->(event) { subscribers.each { |s| s.call(event) } }` --
+  # which is one line and is exactly what a fan-out registry here would be.
+  #
+  # Rails hosts have one already: see Notifications, which republishes every
+  # event into `ActiveSupport::Notifications` under `<name>.active_sanction`.
+  # It is an adapter rather than a dependency -- nothing here requires
+  # ActiveSupport, and the class refuses to build in a process that has not
+  # loaded it.
+  #
+  # ### Nothing is listening by default, and that costs nothing
+  #
+  # `instrumenter` defaults to nil, and a nil instrumenter is not a no-op
+  # object that gets called and returns -- it is a branch taken before
+  # anything is allocated. `.instrument` with no instrumenter calls the block
+  # with a payload that discards writes and returns, so a stage that fills in
+  # fifteen fields allocates no Hash and builds no Event. This is what keeps
+  # the #37 benchmarks where they were.
+  #
+  # ### A subscriber must be safe to call from several threads
+  #
+  # `sync!(concurrency: 3)` fetches from three publishers at once, and the
+  # `:fetch`, `:parse` and `:store` events of those three arrive on three
+  # threads. Nothing here serializes them -- a lock around a subscriber would
+  # make instrumentation a source of contention in the one place this library
+  # deliberately fans out. A subscriber that appends to a plain Array wants a
+  # Mutex of its own; one that hands an event to a metrics client is already
+  # fine, because those are.
+  #
+  # The `:screen` event is the same statement from the other direction: a
+  # Matcher is screened from every thread a host has, so a subscriber counting
+  # queries is counting them concurrently.
+  #
+  # ### A raising subscriber cannot break a sync
+  #
+  # Instrumentation is a measurement of the work and is never part of it.
+  # A subscriber that raises has its exception caught, reported once, and
+  # dropped; the stage it was measuring carries on and returns what it was
+  # going to return. The converse is equally deliberate: **instrumentation
+  # never swallows the library's own exceptions**. An event is emitted for a
+  # stage that raised, carrying `error:`, and then the exception continues
+  # exactly as if nothing were listening.
+  #
+  # @see Event
+  # @see Notifications
+  module Instrumentation
+    extend T::Sig
+
+    # Every event name this library emits. Enumerated so a host can assert
+    # against the list rather than discovering a name in production, and
+    # frozen because it is the published vocabulary -- see the class comment
+    # on what may and may not change about it.
+    EVENTS = T.let(%i[fetch parse store index.build screen sync].freeze, T::Array[Symbol])
+
+    # What a stage's block is handed when nothing is listening.
+    #
+    # A stage writes its measurements into the payload as it goes --
+    # `event[:records] = parsed.size` -- and those writes have to go
+    # somewhere even when there is no subscriber to read them. Somewhere is
+    # here, and it is one frozen object shared by every call rather than a
+    # Hash allocated per stage, which is what makes an uninstrumented
+    # screening call cost a branch.
+    #
+    # @api private
+    class Discard
+      extend T::Sig
+
+      sig { params(_key: Symbol, value: T.untyped).returns(T.untyped) }
+      def []=(_key, value)
+        value
+      end
+
+      sig { params(_key: Symbol).returns(NilClass) }
+      def [](_key) = nil
+
+      sig { returns(T::Hash[Symbol, T.untyped]) }
+      def to_h = {}
+    end
+    private_constant :Discard
+
+    DISCARD = T.let(Discard.new.freeze, Discard)
+    private_constant :DISCARD
+
+    @failures = T.let({}, T::Hash[String, TrueClass])
+    @mutex = T.let(Mutex.new, Mutex)
+
+    class << self
+      extend T::Sig
+
+      # Times a stage, hands the finished Event to `instrumenter`, and returns
+      # whatever the stage returned.
+      #
+      #   Instrumentation.instrument(instrumenter, :parse, { source: :ofac_sdn }) do |event|
+      #     entities = parse(raw)
+      #     event[:records] = entities.size
+      #     entities
+      #   end
+      #
+      # The block is handed the payload so it can record what is only known
+      # once the work is done, which is most of what is worth recording. What
+      # it is handed when nobody is listening discards those writes -- so the
+      # block reads the same either way and the uninstrumented path allocates
+      # nothing.
+      #
+      # A stage that raises still emits, with `error:` set, and then the
+      # exception goes on. A subscriber that raises does not.
+      #
+      # @param instrumenter [#call, nil] nil means nothing is listening
+      # @param name [Symbol] one of EVENTS
+      # @param payload [Hash, nil] what is known before the stage runs
+      # @api private
+      sig do
+        params(instrumenter: T.untyped, name: Symbol, payload: T.nilable(T::Hash[Symbol, T.untyped]),
+               block: T.proc.params(payload: T.untyped).returns(T.untyped)).returns(T.untyped)
+      end
+      def instrument(instrumenter, name, payload = nil, &block)
+        return block.call(DISCARD) if instrumenter.nil?
+
+        fields = payload.nil? ? {} : payload.dup
+        started_at = Time.now.utc
+        began = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          block.call(fields)
+        rescue StandardError => e
+          fields[:error] = e
+          raise
+        ensure
+          emit(instrumenter, name, fields, started_at,
+               (Process.clock_gettime(Process::CLOCK_MONOTONIC) - began).to_f)
+        end
+      end
+
+      # Publishes one already-measured event. For a stage whose duration is
+      # known without wrapping it -- Sync measures each source itself, because
+      # a run is several sources deep and the timings have to agree with the
+      # Report it returns.
+      #
+      # @api private
+      sig do
+        params(instrumenter: T.untyped, name: Symbol, payload: T::Hash[Symbol, T.untyped], started_at: Time,
+               duration: Float).void
+      end
+      def emit(instrumenter, name, payload, started_at, duration)
+        return if instrumenter.nil?
+
+        deliver(instrumenter, Event.new(name: name, payload: payload, started_at: started_at, duration: duration))
+      end
+
+      # Forget which subscriber failures have already been reported, so the
+      # next one is reported again. For a spec that asserts a broken
+      # subscriber is reported; nothing in a running application should call
+      # it.
+      sig { void }
+      def reset!
+        @mutex.synchronize { @failures.clear }
+      end
+
+      private
+
+      # The isolation. A subscriber is a host's code running inside our stack,
+      # and a metrics client with a full queue or a typo in a tag must not be
+      # able to fail a sanctions sync.
+      sig { params(instrumenter: T.untyped, event: Event).void }
+      def deliver(instrumenter, event)
+        instrumenter.call(event)
+      rescue StandardError => e
+        report(instrumenter, event, e)
+      end
+
+      # Dropped, but never silently: a subscriber that is not recording
+      # anything is a dashboard that is quietly wrong, which is worse than one
+      # that is visibly missing.
+      #
+      # Reported once per subscriber, event name and exception class, the way
+      # Deprecation reports once per call site and for the same reason -- a
+      # subscriber that raises on `:screen` raises on every query, and a
+      # service at any volume would spend more of its log on this than on its
+      # own work. Call .reset! to hear about it again.
+      sig { params(instrumenter: T.untyped, event: Event, error: StandardError).void }
+      def report(instrumenter, event, error)
+        return unless first_time?("#{instrumenter.class}/#{event.name}/#{error.class}")
+
+        message = "[active_sanction] instrumenter #{instrumenter.class} raised on the #{event.name} event " \
+                  "(#{error.class}: #{error.message}); the event was dropped and the work carried on. " \
+                  "Further failures of this shape are not reported."
+        logger = ActiveSanction.config.logger
+        return Kernel.warn(message) if logger.nil?
+
+        logger.respond_to?(:warn) ? logger.warn(message) : logger.info(message)
+      end
+
+      sig { params(key: String).returns(T::Boolean) }
+      def first_time?(key)
+        @mutex.synchronize do
+          next false if @failures.key?(key)
+
+          @failures[key] = true
+        end
+      end
+    end
+  end
+end