active_sanction 1.0.0 → 1.1.0

data/lib/active_sanction/sources/base.rb

@@ -8,6 +8,7 @@ require "active_sanction/error"
 require "active_sanction/entity"
 require "active_sanction/snapshot"
 require "active_sanction/fetcher"
+require "active_sanction/instrumentation"
 require "active_sanction/parsers"
 require "active_sanction/payload_cache"
 require "active_sanction/sources"
@@ -82,17 +83,25 @@ module ActiveSanction
       sig { returns(T.untyped) }
       attr_reader :logger
 
+      # Where this adapter's `:parse` event goes, or nil for nothing
+      # listening. See Instrumentation.
+      sig { returns(T.untyped) }
+      attr_reader :instrumenter
+
       # `cache: nil` turns off payload caching, which costs one thing worth
       # knowing: a multi-file source can no longer answer a sync where some of
       # its files changed and others came back 304, so the unchanged ones are
       # downloaded again in full.
       sig do
-        params(fetcher: Fetcher, cache: T.nilable(PayloadCache), logger: T.untyped).void
+        params(fetcher: Fetcher, cache: T.nilable(PayloadCache), logger: T.untyped,
+               instrumenter: T.untyped).void
       end
-      def initialize(fetcher: Fetcher.new, cache: PayloadCache.new, logger: ActiveSanction.config.logger)
+      def initialize(fetcher: Fetcher.new, cache: PayloadCache.new, logger: ActiveSanction.config.logger,
+                     instrumenter: ActiveSanction.config.instrumenter)
         @fetcher = T.let(fetcher, Fetcher)
         @cache = T.let(cache, T.nilable(PayloadCache))
         @logger = T.let(logger, T.untyped)
+        @instrumenter = T.let(instrumenter, T.untyped)
         @results = T.let({}, T::Hash[Symbol, Fetcher::Result])
       end
 
@@ -137,6 +146,20 @@ module ActiveSanction
               "#{self.class} must implement #parse(raw) and return an Array of ActiveSanction::Entity"
       end
 
+      # What the last #parse could not read: a Parsers::Warning per row that
+      # was skipped or could not be mapped, kept rather than raised. Every
+      # shipped adapter overrides this with the parser's own warnings plus
+      # whatever it noticed itself, which is what the adapter rules require of
+      # a new one.
+      #
+      # Empty here rather than abstract, because an adapter that genuinely
+      # cannot fail to read a row should not have to say so, and because the
+      # `:parse` event counts these for every source and a count that is
+      # sometimes a NoMethodError is not a metric. See Doctor, which reads the
+      # warnings themselves rather than the count.
+      sig { returns(T::Array[Parsers::Warning]) }
+      def warnings = []
+
       # Fetches, parses, and checksums -- or returns nil when the publisher
       # says nothing has changed, which is the outcome to expect on most runs
       # and the reason conditional GET exists.
@@ -157,8 +180,15 @@ module ActiveSanction
       # or, for a source that declares a single file, as the bytes themselves.
       sig { params(payloads: T.untyped, files: T.untyped).returns(Snapshot) }
       def snapshot(payloads = nil, **files)
-        Snapshot.new(source: key, entities: parse(parse_argument(payloads || files)),
-                     fetched_at: Time.now.utc, source_version: source_version)
+        raw = parse_argument(payloads || files)
+        entities = Instrumentation.instrument(instrumenter, :parse,
+                                              { source: declared_key, bytes: byte_count(raw) }) do |event|
+          parsed = parse(raw)
+          event[:records] = parsed.size
+          event[:warnings] = warnings.size
+          parsed
+        end
+        Snapshot.new(source: key, entities: entities, fetched_at: Time.now.utc, source_version: source_version)
       rescue ActiveSanction::Error => e
         raise e.in_source(declared_key)
       end
@@ -250,7 +280,19 @@ module ActiveSanction
 
       sig { params(name: Symbol, address: String, force: T::Boolean).returns(Fetcher::Result) }
       def fetch_file(name, address, force)
-        fetcher.fetch(address, key: file_key(name), force: force).success!
+        fetcher.fetch(address, key: file_key(name), force: force, source: declared_key).success!
+      end
+
+      # How many bytes #parse was handed, across every file of a multi-file
+      # source. Taken before the parse rather than after, so the `:parse`
+      # event still says how large the document was when the parse is what
+      # raised.
+      sig { params(raw: T.untyped).returns(Integer) }
+      def byte_count(raw)
+        return raw.bytesize if raw.is_a?(String)
+        return raw.to_h.each_value.sum { |payload| payload.to_s.bytesize } if raw.respond_to?(:to_h)
+
+        raw.to_s.bytesize
       end
 
       sig { params(name: Symbol).returns(T.untyped) }
@@ -283,7 +325,7 @@ module ActiveSanction
       sig { params(name: Symbol).returns(Fetcher::Result) }
       def refetch(name)
         logger&.info("[active_sanction] #{key} #{name} unchanged but not cached; fetching in full")
-        result = fetcher.fetch(url(name), key: file_key(name), force: true).success!
+        result = fetcher.fetch(url(name), key: file_key(name), force: true, source: declared_key).success!
         return result if result.changed?
 
         raise MissingPayload,

data/lib/active_sanction/storage/meta.rb

@@ -110,6 +110,24 @@ module ActiveSanction
       # per source: a list that failed to refresh keeps its previous snapshot,
       # which is the right call and only safe if the age of what is being
       # screened against is visible.
+      #
+      # **Accurate to a second, and never fewer than the seconds that have
+      # passed.** `fetched_at` is stored to the second -- Snapshot#time!
+      # truncates it, so that a stored snapshot reloads equal to the one that
+      # was written -- so the instant of the fetch is known only to lie
+      # somewhere inside the second this names. What comes back is therefore
+      # the largest age consistent with what was recorded, which is the
+      # direction a staleness measure has to err in: an answer that is at most
+      # a second pessimistic is a report that nobody acts on, and one that is
+      # optimistic is a list being screened against that is older than it
+      # claims.
+      #
+      # The practical consequence, and the reason it is written down: a list
+      # fetched microseconds ago reports 0 or 1, according to whether the run
+      # crossed a second boundary on its way here. Both mean "just fetched" --
+      # see Sync::Result#age_in_words, which is what a summary table shows --
+      # and nothing should assert on the exact number of a fresh sync, because
+      # that is a fact about the clock rather than about this library.
       sig { params(now: Time).returns(Integer) }
       def age(now = Time.now) = now.to_i - fetched_at.to_i
 

data/lib/active_sanction/sync.rb

@@ -5,6 +5,7 @@ require "sorbet-runtime"
 
 require "uri"
 require "active_sanction/error"
+require "active_sanction/instrumentation"
 require "active_sanction/sources"
 require "active_sanction/storage"
 require "active_sanction/sync/result"
@@ -149,6 +150,17 @@ module ActiveSanction
     sig { returns(T.untyped) }
     attr_reader :logger
 
+    # Where the `:sync` and `:store` events go, or nil for nothing listening.
+    #
+    # The `:fetch` and `:parse` events of the sources this run covers do not
+    # come from here: an adapter is constructed by the run and reads the
+    # configuration, exactly as it does for its logger and its User-Agent. So
+    # a host that instruments through `ActiveSanction.configure` sees all six
+    # events, and one that hands a run its own instrumenter sees the two this
+    # class emits. See Instrumentation.
+    sig { returns(T.untyped) }
+    attr_reader :instrumenter
+
     sig { params(options: T.untyped, block: T.untyped).returns(Report) }
     def self.call(**options, &block) = T.unsafe(self).new(**options).call(&block)
 
@@ -157,9 +169,10 @@ module ActiveSanction
     # raises here, before the first list is downloaded, rather than after.
     sig do
       params(sources: T.untyped, store: T.untyped, force: T::Boolean, concurrency: T.untyped,
-             logger: T.untyped).void
+             logger: T.untyped, instrumenter: T.untyped).void
     end
-    def initialize(sources: nil, store: nil, force: false, concurrency: nil, logger: ActiveSanction.config.logger)
+    def initialize(sources: nil, store: nil, force: false, concurrency: nil, logger: ActiveSanction.config.logger,
+                   instrumenter: ActiveSanction.config.instrumenter)
       @sources = T.let(resolve(sources), T::Array[T.untyped])
       @keys = T.let(@sources.map { |source| Sources::Definition.key!(source.key) }, T::Array[Symbol])
       @store = T.let(store || ActiveSanction.storage, T.untyped)
@@ -168,6 +181,7 @@ module ActiveSanction
         Configuration.sync_concurrency!(concurrency || ActiveSanction.config.sync_concurrency), Integer
       )
       @logger = T.let(logger, T.untyped)
+      @instrumenter = T.let(instrumenter, T.untyped)
       @lock = T.let(Mutex.new, Mutex)
       # The settings this run was started under, so a worker thread reads them
       # rather than the default client's. A configuration is fiber-local and a
@@ -195,9 +209,17 @@ module ActiveSanction
       started_at = Time.now.utc
       began = monotonic
       log_start
-      work = keys.each_with_index.map { |key, at| [at, key, sources.fetch(at)] }
-      results = run(work, &block).sort_by(&:first).map(&:last)
-      report = Report.new(results: results, started_at: started_at, duration: elapsed(began))
+      # The run's own duration is the Report's, taken from the same clock
+      # reading, so an event and the report a caller is holding never disagree
+      # about how long a run took.
+      report = Instrumentation.instrument(instrumenter, :sync,
+                                          { sources: keys, forced: force, concurrency: concurrency }) do |event|
+        work = keys.each_with_index.map { |key, at| [at, key, sources.fetch(at)] }
+        results = run(work, &block).sort_by(&:first).map(&:last)
+        finished = Report.new(results: results, started_at: started_at, duration: elapsed(began))
+        summarize(event, finished)
+        finished
+      end
       log_finish(report)
       report
     end
@@ -285,13 +307,39 @@ module ActiveSanction
         snapshot = adapter.sync(force: force || previous.nil?)
         return complete(key, :unchanged, previous, started) if unchanged?(previous, snapshot)
 
-        store.write_snapshot(snapshot)
+        write(key, snapshot)
         complete(key, :updated, Storage::Meta.from_snapshot(snapshot), started)
       rescue StandardError => e
         complete(key, :failed, previous, started, stamp(key, e))
       end
     end
 
+    # Writes one list, and says what it cost. Separate from the rest of
+    # #sync_source so the `:store` event times the write and nothing else --
+    # a store that takes eleven seconds to persist 19,321 entities is a
+    # different operational problem from a publisher that takes eleven seconds
+    # to serve them, and a timing that covered both could not tell a host
+    # which one it had.
+    sig { params(key: Symbol, snapshot: T.untyped).void }
+    def write(key, snapshot)
+      fields = { source: key, snapshot_id: snapshot.checksum, entities: snapshot.record_count,
+                 store: store.class.name }
+      Instrumentation.instrument(instrumenter, :store, fields) { store.write_snapshot(snapshot) }
+    end
+
+    # What a run did, as counts rather than as the Report itself: a subscriber
+    # forwarding an event to a metrics backend wants numbers, and one that
+    # wants the whole report already has it as the return value of the call
+    # that emitted this.
+    sig { params(event: T.untyped, report: Report).void }
+    def summarize(event, report)
+      event[:outcomes] = report.results.to_h { |result| [result.source, result.status] }
+      event[:updated] = report.updated.size
+      event[:unchanged] = report.unchanged.size
+      event[:failed] = report.failed.size
+      event[:records] = report.record_count
+    end
+
     # A failure captured for a source names that source, even when it was
     # raised somewhere that could not know -- a store that will not open, an
     # adapter constructor. Only ever fills a blank; see Error#in_source.

data/lib/active_sanction/version.rb

@@ -6,7 +6,7 @@ module ActiveSanction
   # new source adapter, a storage fix or a documentation release -- none of
   # which change what a name scores. MATCHER_VERSION, below, is the one that
   # answers that question.
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 
   # Which matching pipeline scored a decision, stamped onto every MatchResult
   # and bumped whenever a change to the normalizer, the index, the similarity

data/lib/active_sanction.rb

@@ -6,6 +6,7 @@ require "sorbet-runtime"
 require "active_sanction/error"
 require "active_sanction/version"
 require "active_sanction/deprecation"
+require "active_sanction/instrumentation"
 require "active_sanction/configuration"
 require "active_sanction/name"
 require "active_sanction/address"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_sanction
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Marshall Shen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-13 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -102,6 +102,9 @@ files:
 - lib/active_sanction/index/candidate.rb
 - lib/active_sanction/index/entry.rb
 - lib/active_sanction/index/features.rb
+- lib/active_sanction/instrumentation.rb
+- lib/active_sanction/instrumentation/event.rb
+- lib/active_sanction/instrumentation/notifications.rb
 - lib/active_sanction/match_result.rb
 - lib/active_sanction/matcher.rb
 - lib/active_sanction/name.rb