active_sanction 1.0.0 → 1.1.0

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

data/lib/active_sanction/matcher.rb

@@ -6,6 +6,7 @@ require "sorbet-runtime"
 require "time"
 require "active_sanction/error"
 require "active_sanction/index"
+require "active_sanction/instrumentation"
 require "active_sanction/match_result"
 require "active_sanction/query"
 require "active_sanction/scorer"
@@ -131,6 +132,14 @@ module ActiveSanction
     sig { returns(Symbol) }
     attr_reader :backend
 
+    # Where the `:screen` event goes, or nil for nothing listening. Read once
+    # at construction and frozen with everything else here, which is the rule
+    # the class comment states for the whole query path: a subscriber swapped
+    # halfway through a batch cannot make half of it instrumented. See
+    # Instrumentation.
+    sig { returns(T.untyped) }
+    attr_reader :instrumenter
+
     class << self
       extend T::Sig
 
@@ -152,14 +161,29 @@ module ActiveSanction
       # covers all three, and both report the name clear.
       sig do
         params(store: T.untyped, sources: T.untyped, weights: T.untyped, candidate_limit: T.untyped,
-               backend: T.untyped).returns(Matcher)
+               backend: T.untyped, instrumenter: T.untyped).returns(Matcher)
       end
       def build(store = nil, sources: nil, weights: nil, candidate_limit: nil,
-                backend: MatchResult::DEFAULT_BACKEND)
+                backend: MatchResult::DEFAULT_BACKEND, instrumenter: nil)
         store ||= ActiveSanction.config.storage
+        listening = instrumenter.nil? ? ActiveSanction.config.instrumenter : instrumenter
+        built = Instrumentation.instrument(listening, :"index.build", { store: store.class.name }) do |event|
+          index_over(store, sources, event)
+        end
+        new(index: built.fetch(:index), snapshots: built.fetch(:checksums), verified: built.fetch(:attested),
+            weights: weights, candidate_limit: candidate_limit, backend: backend, instrumenter: listening)
+      end
+
+      private
+
+      # Every list this matcher will hold, read one at a time and released
+      # before the next is opened, and what it cost.
+      sig { params(store: T.untyped, sources: T.untyped, event: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+      def index_over(store, sources, event)
         builder = Index::Builder.new
         checksums = T.let({}, T::Hash[Symbol, String])
         attested = T.let([], T::Array[Symbol])
+        entities = 0
         requested(store, sources).each do |key|
           snapshot = store.fetch_snapshot(key)
           checksums[key] = snapshot.checksum
@@ -168,12 +192,27 @@ module ActiveSanction
           # different list.
           attested << key if snapshot.trusted?
           snapshot.entities.each { |entity| builder.add(entity) }
+          entities += snapshot.record_count
         end
-        new(index: builder.build, snapshots: checksums, verified: attested, weights: weights,
-            candidate_limit: candidate_limit, backend: backend)
+        index = builder.build
+        measure(event, index, checksums, entities)
+        { index: index, checksums: checksums, attested: attested }
       end
 
-      private
+      # What a host watches at boot and after every sync: how long an index
+      # took to build, how much of it there is, and roughly what it weighs.
+      # `bytes` is an estimate and says so -- see Index#profile, which is
+      # where the assumptions behind the number are written down, and where
+      # the entity count deliberately does not come from.
+      sig do
+        params(event: T.untyped, index: Index, checksums: T::Hash[Symbol, String], entities: Integer).void
+      end
+      def measure(event, index, checksums, entities)
+        event[:sources] = checksums.keys
+        event[:snapshots] = checksums
+        event[:entities] = entities
+        index.profile.each { |name, value| event[name] = value }
+      end
 
       # The lists to index, in a deterministic order, or the exception that
       # says why there are none.
@@ -204,10 +243,10 @@ module ActiveSanction
     # one name against several list versions, or a spec.
     sig do
       params(index: Index, snapshots: T.untyped, weights: T.untyped, candidate_limit: T.untyped,
-             backend: T.untyped, verified: T.untyped).void
+             backend: T.untyped, verified: T.untyped, instrumenter: T.untyped).void
     end
     def initialize(index:, snapshots:, weights: nil, candidate_limit: nil, backend: MatchResult::DEFAULT_BACKEND,
-                   verified: nil)
+                   verified: nil, instrumenter: nil)
       @index = index
       @snapshots = T.let(snapshots!(snapshots), T::Hash[Symbol, String])
       @verified = T.let(verified!(verified), T::Array[Symbol])
@@ -216,6 +255,7 @@ module ActiveSanction
       @weights = T.let(Scorer::Weights.build(weights), Scorer::Weights)
       @candidate_limit = T.let(candidate_limit!(candidate_limit), Integer)
       @backend = T.let(backend.to_s.to_sym, Symbol)
+      @instrumenter = T.let(instrumenter.nil? ? ActiveSanction.config.instrumenter : instrumenter, T.untyped)
       freeze
     end
 
@@ -303,13 +343,31 @@ module ActiveSanction
       # weights, one instant, one backend. Only the snapshot checksum varies,
       # and only because a run may cover several lists.
       stamp = { query: query, weights: weights, backend: backend, screened_at: screened_at }
-      scored(query)
-        .sort_by { |result| [-result.score, result.source.to_s, result.entity.id] }
-        .first(query.limit)
-        .map do |result|
-          MatchResult.from_scorer(result, snapshot_id: snapshots.fetch(result.source),
-                                          verified: verified.include?(result.source), **stamp)
-        end
+      Instrumentation.instrument(instrumenter, :screen) do |event|
+        results = scored(query, event)
+                  .sort_by { |result| [-result.score, result.source.to_s, result.entity.id] }
+                  .first(query.limit)
+                  .map do |result|
+                    MatchResult.from_scorer(result, snapshot_id: snapshots.fetch(result.source),
+                                                    verified: verified.include?(result.source), **stamp)
+                  end
+        describe(event, query, results)
+        results
+      end
+    end
+
+    # What one query cost and what it consulted. `snapshots` is the whole
+    # checksum map rather than a count, because the question an audit asks of
+    # a screening event is which list *versions* answered it -- the same
+    # question every MatchResult is stamped with, and the only one a result
+    # set of zero cannot answer for itself.
+    sig { params(event: T.untyped, query: Query, results: T::Array[MatchResult]).void }
+    def describe(event, query, results)
+      event[:results] = results.size
+      event[:threshold] = query.threshold
+      event[:limit] = query.limit
+      event[:sources] = query.sources || sources
+      event[:snapshots] = snapshots
     end
 
     # Every entity the index retrieved, scored once.
@@ -321,10 +379,11 @@ module ActiveSanction
     # retrieves the same record under several spellings, and rescoring one
     # that has already failed the threshold is the most expensive way to
     # arrive at the same no.
-    sig { params(query: Query).returns(T::Array[Scorer::Result]) }
-    def scored(query)
+    sig { params(query: Query, event: T.untyped).returns(T::Array[Scorer::Result]) }
+    def scored(query, event)
       seen = T.let({}, T::Hash[[Symbol, String], T.nilable(Scorer::Result)])
-      index.candidates(query.form, limit: candidate_limit, sources: query.sources).each do |candidate|
+      retrieved = index.candidates(query.form, limit: candidate_limit, sources: query.sources)
+      retrieved.each do |candidate|
         # Keyed by list as well as id, because the same person really is two
         # records when two governments list them, and both belong in a report.
         key = [candidate.source, candidate.entity.id]
@@ -332,6 +391,12 @@ module ActiveSanction
 
         seen[key] = Scorer.call(query.subject, candidate, weights: weights, threshold: query.threshold)
       end
+      # Names retrieved, and the entities they came down to. The two differ by
+      # however many aliases of one record the query looked like, and a
+      # candidate cap is a cap on the first rather than the second -- which is
+      # the number to watch when tuning it.
+      event[:candidates] = retrieved.size
+      event[:scored] = seen.size
       seen.values.compact
     end