graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/internal.rb

@@ -47,26 +47,63 @@ module GraphWeaver
           DidYouMean::SpellChecker.new(dictionary: dictionary).correct(term).first
         end
 
+        # "a" or "an" for a word an error message is about to name.
+        def article(word) = word.downcase.start_with?(/[aeiou]/) ? "an" : "a"
+
         # The module a .graphql file generates, and the basename of the file
         # it generates into: the camelized file name plus the operation's own
-        # word.
+        # word. Every run of non-alphanumerics in the name is a word boundary,
+        # and a trailing extension naming the document's own operation kind is
+        # dropped rather than doubled.
         #
         #      person.graphql          => PersonQuery       (person_query.rb)
         #      save_list_entry.graphql => SaveListEntryMutation
         #                                 (save_list_entry_mutation.rb)
+        #      get-hello.graphql       => GetHelloQuery     (get_hello_query.rb)
+        #      hello.query.graphql     => HelloQuery        (hello_query.rb)
         #
         # Every naming site goes through here — generate!, parse(path), and
         # load_queries! — so the constant a file produces is the same one
         # whichever door you came in by, and the file it lands in matches it.
         def generated_names(path, source)
-          base = File.basename(path, ".*")
-          suffix = operation_suffix(source)
-          ["#{Inflect.camelize(base)}#{suffix}", "#{base}_#{suffix.downcase}.rb"]
+          kind = operation_kind(source)
+          base = strip_kind_extension(File.basename(path, ".*"), kind, path)
+          stem = base.gsub(/[^A-Za-z0-9]+/, "_")
+          suffix = (kind == "mutation") ? "Mutation" : "Query"
+          name = Inflect.camelize(stem)
+          # all punctuation camelizes to nothing, which would leave the suffix
+          # standing alone as the whole name — keep the base so it stays refusable
+          name = base if name.empty?
+          ["#{name}#{suffix}", "#{stem}_#{suffix.downcase}.rb"]
         end
 
         # just the module name — see generated_names
         def module_name(path, source) = generated_names(path, source).first
 
+        # The one sentence about scalars nothing registered — said on the
+        # logger per parse and once per run by the build, and worth saying
+        # identically in both. Keyed by graph name (nil for an app with no
+        # declared graphs): a registration is scoped to one graph, so merging
+        # the names across several would read as "forgotten everywhere" for a
+        # scalar registered for one of them and forgotten for the next.
+        def untyped_scalars_report(by_graph)
+          found = by_graph.reject { |_, names| names.empty? }
+          return if found.empty?
+
+          advice = "(register with GraphWeaver.register_scalar)"
+          # One graph ran, so there is nothing to attribute — including when it
+          # is the only one with findings is what made a forgetful graph read
+          # as a forgetful app.
+          if by_graph.one?
+            names = found.values.first.sort
+            return "#{names.size} unregistered custom scalar#{"s" unless names.one?} → T.untyped: " \
+              "#{names.join(", ")} #{advice}"
+          end
+
+          ["unregistered custom scalars → T.untyped #{advice}:",
+            *found.map { |graph, names| "  graph #{graph.inspect}: #{names.sort.join(", ")}" }].join("\n")
+        end
+
         # A path setting, as a real path: relative to GraphWeaver.root, which
         # is the app root and not wherever the process was started. Every
         # filesystem access on a configured path goes through here; the
@@ -85,12 +122,95 @@ module GraphWeaver
           path.start_with?(prefix) ? path.delete_prefix(prefix) : path
         end
 
+        # The registrations a schema generates with: the graph that named it,
+        # or the default graph's. The testing fakes ask, so a fabricated
+        # scalar is the shape the module generated against that schema will
+        # cast — a `Money` registered for one graph is not a `Money` for the
+        # next one along. Matched on the schema class a graph runs in-process,
+        # which is the only identity cheap enough to ask per fake; anything
+        # else falls back to the default, which is where a single-schema app
+        # has always read from.
+        def registry_for(schema) = graph_for(schema)&.registry || Codegen.registry
+
+        # The declared graph that runs `schema` in-process, or nil. Matched on
+        # the schema class a graph runs, which is the only identity cheap
+        # enough to ask per call — a dump would have to be re-read, and
+        # re-reading it gives a different object every time. GraphWeaver.parse
+        # asks too, to bake the GRAPH a generated file would have carried.
+        def graph_for(schema)
+          schema && GraphWeaver.graphs.find { |candidate| candidate.live_schema.equal?(schema) }
+        end
+
+        # Where generated modules are READ from: the configured patterns, plus
+        # any graph writing somewhere they don't already cover. generated_paths'
+        # default glob (app/graphql/*/generated) covers the conventional layout,
+        # so listing a graph's output as well would name the same directory
+        # twice — in the log, and in the globbing.
+        #
+        # FNM_PATHNAME because Dir.glob is what expands these patterns
+        # everywhere else (Zeitwerk's ignore, load_generated!) and its * stops
+        # at a /. Without it app/graphql/*/generated "covered"
+        # app/graphql/a/b/generated, which was then neither ignored nor loaded.
+        def generated_dirs
+          extra = GraphWeaver.graphs.map(&:output).reject do |dir|
+            GraphWeaver.generated_paths.any? do |pattern|
+              File.fnmatch?(resolve(pattern), resolve(dir), File::FNM_PATHNAME)
+            end
+          end
+          GraphWeaver.generated_paths | extra
+        end
+
         # Every query document under these directories, sorted — the files
         # generate!, verify_generated!, check_queries and load_queries! read.
         def query_files(paths = GraphWeaver.queries_paths)
           Array(paths).flat_map { |dir| Dir[File.join(resolve(dir), Codegen::DOCUMENT_GLOB)].sort }
         end
 
+        # Anywhere GraphWeaver takes schema:, a Client stands for its schema — so
+        # the console object and the rake task point at the same thing. A path
+        # (String or Pathname) or SDL loads like it does everywhere else in the
+        # library; without that it reached `schema.validate` as itself and failed
+        # as `undefined method 'validate' for an instance of String`.
+        def schema_for(source)
+          return source.schema if source.is_a?(Client)
+          return SchemaLoader.load(source) if source.is_a?(String) || source.respond_to?(:to_path)
+
+          source
+        end
+
+        # Whether this source carries the @join__* routing table, i.e. is a
+        # composed supergraph rather than an API schema. The one place that
+        # asks: Graph#supergraph reads it per graph, Testing::Config for the
+        # app-wide fallbacks, and the federation rake tasks through both.
+        #
+        # Kept per source for the life of the process — parsing a supergraph
+        # is milliseconds and :wire asks per example — and keyed on what the
+        # file IS, since the answer is a property of its content. A supergraph
+        # recomposed at a stable path (a `before` hook, chained rake tasks)
+        # used to be answered from the previous composition, which routed a
+        # graph into the wrong plan or refused it as being in none.
+        def composed?(source)
+          @composed ||= {}
+          key = composed_key(source)
+          return @composed[key] if @composed.key?(key)
+
+          @composed[key] = begin
+            SchemaLoader.routing_table?(source)
+          rescue GraphWeaver::Error
+            # a source that can't even be read is in no supergraph either —
+            # and that Error is worth its warn line, where "not federated"
+            # never was
+            false
+          end
+        end
+
+        # the conventional schema dump, required
+        def locate_schema!
+          SchemaLoader.locate or raise GraphWeaver::Error,
+            "no schema dump at #{GraphWeaver.schema_path} (.json/.graphql/.gql) — pass schema:, " \
+            "or cache one: GraphWeaver.new(url, cache: true).schema"
+        end
+
         # The graphql-ruby schema class the app default executes against,
         # when it runs in-process — a Client wrapping one, or the class in
         # the slot bare. nil for every network client. Not memoized: in dev
@@ -104,15 +224,62 @@ module GraphWeaver
           target if target.is_a?(Class) && target <= GraphQL::Schema
         end
 
+        # The context to hand resolvers. A proc is answered from a request's
+        # headers (Testing::Endpoint resolves it), so off the wire there is
+        # nothing to answer it with — and a Proc reaching graphql-ruby as a
+        # context fails far from the line that set it.
+        def context!(context)
+          return context unless context.respond_to?(:call)
+
+          raise GraphWeaver::Error, "context: is a proc, so it is answered from a request's " \
+            "headers — and nothing here made a request. Tag the example graphql: :wire, which " \
+            "serves your resolvers at your client's endpoint so your transport's headers reach " \
+            "them; off the wire, pass the hash."
+        end
+
         private
 
-        # "Mutation" for a mutation document, "Query" for everything else.
-        def operation_suffix(source)
+        # What makes a composed? answer stale. Both callers pass a path that
+        # exists, so the file's identity is its stat — size as well as mtime,
+        # because a coarse mtime can miss two writes in one tick. Anything
+        # that isn't a path (SDL, a class) is its own key.
+        def composed_key(source)
+          stat = File.stat(source.to_s)
+          [source.to_s, stat.mtime, stat.size]
+        rescue SystemCallError
+          source
+        end
+
+        # The document's operation kind — "query", "mutation" or
+        # "subscription" — or nil when it holds no operation or won't parse.
+        # The one source of truth for the word a module name ends in AND for
+        # the file-name extension that word makes redundant.
+        def operation_kind(source)
           operation = GraphQL.parse(source).definitions
             .grep(GraphQL::Language::Nodes::OperationDefinition).first
-          (operation&.operation_type == "mutation") ? "Mutation" : "Query"
+          operation && (operation.operation_type || "query") # `{ hello }` is shorthand for a query
         rescue GraphQL::ParseError
-          "Query" # unparseable: codegen brands the real error a moment later
+          nil # unparseable: codegen brands the real error a moment later
+        end
+
+        # GraphQL's operation kinds, as a file name spells them. Apollo, Relay
+        # and GitLab's frontend all name a query file for its operation, so
+        # `blob_content.query.graphql` says in the extension exactly what the
+        # module's own suffix says — drop it rather than emit BlobContentQueryQuery.
+        # `_query` inside a snake_case name is a word OF the name, not this, so
+        # nothing that generates today is renamed.
+        OPERATION_EXTENSION = /\.(query|mutation|subscription)\z/i
+        private_constant :OPERATION_EXTENSION
+
+        def strip_kind_extension(base, kind, path)
+          declared = base[OPERATION_EXTENSION, 1]&.downcase
+          stem = declared && base[0...-(declared.length + 1)]
+          return base if stem.nil? || stem.empty?
+          return stem if kind.nil? || kind == declared
+
+          raise GraphWeaver::Error, "#{relative(path)}: the file name ends .#{declared}, but the " \
+            "document defines a #{kind} — rename it #{stem}.#{kind}#{File.extname(path)} " \
+            "or drop the .#{declared}"
         end
       end
     end
@@ -142,7 +309,7 @@ module GraphWeaver
         # JSON round-trip so symbol keys become strings — otherwise
         # YAML.dump writes Ruby symbols the safe loader rejects on the next
         # run, and lookup keys stay stable across processes
-        def normalize_variables(variables) = JSON.parse(JSON.generate(variables || {}))
+        def normalize_variables(variables) = JSON.parse(Wire.json(variables || {}))
 
         # one readable line: an error naming a 60-line query is a wall, not a hint
         def summarize(query, limit: 160)
@@ -157,6 +324,54 @@ module GraphWeaver
     # carries an error in. Lived on Transport and Router, both of which
     # users touch — the worst place for it.
     module Wire
+      # JSON for the wire, or the caller's bug named under the umbrella: a
+      # value with no JSON form (NaN, Infinity, binary) raised a raw JSON::
+      # error from wherever it was first encoded — the transport, a cassette
+      # key, a log line — so every encoder goes through here.
+      def self.json(value)
+        JSON.generate(value)
+      rescue JSON::GeneratorError => e
+        raise GraphWeaver::Error, "variables are not JSON-serializable: #{e.message}"
+      end
+
+      # The half of that discipline JSON doesn't raise for. JSON.generate
+      # carries a String, a number, a boolean, null, a list and an object;
+      # anything else it renders as the value's #to_s — right for a Date or
+      # a Symbol, a memory address for a File, which then sits in the
+      # server's database looking like it meant something. So a variable
+      # whose #to_s is Ruby's debug form, or that is a stream whose bytes
+      # JSON can't carry at all, is refused before the body is built.
+      def self.check_variables!(variables)
+        variables&.each { |name, value| check_variable!(name.to_s, value) }
+      end
+
+      def self.check_variable!(path, value)
+        case value
+        when Hash then value.each { |key, nested| check_variable!("#{path}.#{key}", nested) }
+        when Array then value.each_with_index { |nested, i| check_variable!("#{path}[#{i}]", nested) }
+        when String, Symbol, Numeric, true, false, nil then nil
+        else
+          raise GraphWeaver::Error, variable_refusal(path, value) if value.respond_to?(:read) ||
+            value.to_s.start_with?("#<")
+        end
+      end
+      private_class_method :check_variable!
+
+      # A stream and an anonymous object fail the same way and need different
+      # next steps: one is a feature this client doesn't have, the other is a
+      # value that never said what it is.
+      def self.variable_refusal(path, value)
+        if value.respond_to?(:read)
+          "$#{path} is a #{value.class} — graph_weaver posts application/json and doesn't implement " \
+            "the GraphQL multipart request spec, so a file can't ride along; send what the server " \
+            "expects as JSON, or POST the upload with your own transport"
+        else
+          "$#{path} is a #{value.class}, which has no JSON form — it would go on the wire as " \
+            "#{value.to_s.inspect}; send a String, a number, a boolean, a list, or an object"
+        end
+      end
+      private_class_method :variable_refusal
+
       # The name of the document's FIRST operation, nil when anonymous. Only
       # the fallback for a raw query string handed straight to a transport —
       # generated modules pass their OPERATION_NAME, parsed properly.
@@ -168,7 +383,8 @@ module GraphWeaver
       # every request, and the only way to be wrong (a field literally named
       # `mutation` opening a line) errs toward not retrying.
       MUTATION_PATTERN = /^[ \t]*mutation\b/
-      private_constant :MUTATION_PATTERN
+      SUBSCRIPTION_PATTERN = /^[ \t]*subscription\b/
+      private_constant :MUTATION_PATTERN, :SUBSCRIPTION_PATTERN
 
       REQUEST_MUTEX = Mutex.new
       private_constant :REQUEST_MUTEX
@@ -183,16 +399,35 @@ module GraphWeaver
 
         def mutation?(query) = MUTATION_PATTERN.match?(query)
 
+        # What this document runs, for the instrumentation payload — :query
+        # for the shorthand `{ ... }` document too, which is what it is.
+        # Built on mutation? rather than beside it, so an APM's write-failure
+        # rate and the decision not to retry can't come to disagree.
+        def kind(query)
+          return :mutation if mutation?(query)
+
+          SUBSCRIPTION_PATTERN.match?(query) ? :subscription : :query
+        end
+
         # one error in the shape a GraphQL response carries them
         def graphql_error(message, code)
           { "message" => message, "extensions" => { "code" => code } }
         end
 
-        # "[req 3 FilteredPokemon]" — a per-process request id plus the
-        # operation name, when there is one
+        # "[req 4123-3 FilteredPokemon]" — the pid, this process's own
+        # request count, and the operation name when there is one.
+        #
+        # Both halves, because a Puma cluster forks: the counter is inherited
+        # with everything else, so without the reset every worker continues
+        # the master's sequence, and without the pid two workers' "[req 3]"
+        # are two unrelated requests in one aggregated log.
         def log_tag(operation_name = nil)
-          id = REQUEST_MUTEX.synchronize { @request_count = (@request_count || 0) + 1 }
-          "[req #{id}#{" #{operation_name}" if operation_name}]"
+          pid = Process.pid
+          id = REQUEST_MUTEX.synchronize do
+            @request_pid, @request_count = pid, 0 unless @request_pid == pid
+            @request_count += 1
+          end
+          "[req #{pid}-#{id}#{" #{operation_name}" if operation_name}]"
         end
 
         def truncate_for_log(query)

data/lib/graph_weaver/log_subscriber.rb

@@ -0,0 +1,74 @@
+# typed: ignore — ActiveSupport::LogSubscriber, which sorbet can't resolve here
+# frozen_string_literal: true
+
+# The superclass, so this file stands alone: requiring it by hand is the
+# documented way to subscribe outside Rails, and there is no railtie out there
+# to have loaded ActiveSupport first. Skipped when the constant already
+# exists, which is how a stand-in can take its place.
+require "active_support/log_subscriber" unless defined?(ActiveSupport::LogSubscriber)
+
+module GraphWeaver
+  # One line per GraphQL operation in a Rails log, the shape ActiveRecord
+  # uses for a query:
+  #
+  #      GraphWeaver PersonQuery (12.3ms) ok
+  #      GraphWeaver PersonQuery (8.1ms) errors [THROTTLED]
+  #      GraphWeaver PersonQuery (31.2ms) failed GraphWeaver::TransportError
+  #      GraphWeaver billing/InvoicesQuery (12.3ms) ok
+  #
+  # Attached by the railtie wherever ActiveSupport is, and fed by the
+  # instrumenter it sets. Requires ActiveSupport — `require` this yourself
+  # only if you subscribe by hand.
+  #
+  # **One rule decides which line you get: the summary is info, the wire is
+  # debug.** This is the only GraphWeaver line at info, so a production log
+  # gets one per operation and nothing that could carry PII; turning
+  # GraphWeaver.logger up to debug adds the query, the variables and the
+  # response *beneath* it rather than repeating it.
+  #
+  # It writes through GraphWeaver.logger rather than Rails.logger, so
+  # `GraphWeaver.logger = nil` — the documented way to silence the gem —
+  # silences this too, and the line carries the same `graph_weaver`
+  # progname as every other one.
+  class LogSubscriber < ActiveSupport::LogSubscriber
+    # attach_to(:graph_weaver) subscribes "#{method}.graph_weaver" and
+    # ActiveSupport::Subscriber#call dispatches on the name up to the first
+    # dot — so this method name is EXECUTE_EVENT's first half, both ways.
+    def execute(event)
+      payload = event.payload
+
+      GraphWeaver::Internal::Log.log(:info) do
+        # duration_ms is the instrumenter's own measurement; event.duration
+        # covers a subscriber attached to something that didn't set it
+        ms = payload[:duration_ms] || event.duration
+        "GraphWeaver #{subject(payload)} (#{format("%.1f", ms)}ms) #{outcome(payload)}"
+      end
+    end
+
+    # GraphWeaver's logger, not Rails' — LogSubscriber#call skips a
+    # subscriber whose logger is nil, which is what makes the gem's own
+    # opt-out reach this line too.
+    def logger = GraphWeaver.logger
+
+    private
+
+    # What ran: the operation, prefixed by its graph when the request carried
+    # one — an app with several graphs reads `billing/InvoicesQuery` without
+    # a second line shape to learn, and one with a single graph never sees it.
+    def subject(payload)
+      operation = payload[:operation] || "query"
+      payload[:graph] ? "#{payload[:graph]}/#{operation}" : operation
+    end
+
+    # status, then whatever narrows it: the error class, the reason an alert
+    # groups by, and which attempt this was when a Retry is in the stack.
+    def outcome(payload)
+      parts = [payload[:status], payload[:error]]
+      # the GraphQL code, or the HTTP status where the request never got one
+      reason = payload[:code] || (payload[:http_status] if payload[:status] == :failed)
+      parts << "[#{reason}]" if reason
+      parts << "(retry #{payload[:retries]})" if payload[:retries].to_i.positive?
+      parts.compact.join(" ")
+    end
+  end
+end

data/lib/graph_weaver/logging.rb

@@ -1,6 +1,8 @@
 # typed: true
 # frozen_string_literal: true
 
+require "json"
+
 module GraphWeaver
   class << self
     # Where GraphWeaver narrates what it's doing — anything
@@ -43,18 +45,20 @@ module GraphWeaver
 
     # One callable wrapping every request GraphWeaver makes — over the
     # wire or in-process — so an APM can time it and count errors. A
-    # no-op until you set one:
+    # no-op until you set one (Rails sets this one for you):
     #
     #      GraphWeaver.instrumenter = lambda do |event, payload, &block|
     #        ActiveSupport::Notifications.instrument(event, payload, &block)
     #      end
     #
-    # It must call the block and return its value. The only event today
-    # is EXECUTE_EVENT; its payload carries :url (nil in-process),
-    # :schema (in-process only), :operation (the document's operation
-    # name, nil for an anonymous one), and — added after the response
-    # lands — :status. Never the query text or the variables: those
-    # carry PII and belong at debug on the logger, where they're gated.
+    # It must call the block and return its value. The only event today is
+    # EXECUTE_EVENT; its payload is the contract in docs/logging.md —
+    # :operation, :client, :kind, :status, :duration_ms, :graph always;
+    # :url/:http_status over the wire, :schema in-process, :error/:code on a
+    # failure, :retries when a Retry wrapped it. Never the query text or the
+    # variables: the payload fans out to subscribers that know none of the
+    # filtering rules, so PII belongs at debug on the logger, where the
+    # level gates it and filter_parameters scrubs it.
     attr_accessor :instrumenter
   end
 
@@ -73,10 +77,49 @@ module GraphWeaver
           !key.nil? && Log.filter_variables({ key.to_s => nil })[key.to_s] == FILTERED
         end
 
+        # True when this key names a credential — asked of a url's query
+        # parameters, which are scrubbed whatever the app's logging appetite.
+        # filter_parameters is a knob about log verbosity; emptying it must
+        # not un-scrub a token in an endpoint, any more than it un-scrubs the
+        # url's userinfo. The app's list widens this; it can't narrow it.
+        def credential?(key)
+          filtered?(key) || Log.filtered?(key, GraphWeaver::DEFAULT_FILTER_PARAMETERS)
+        end
+
         # `detail` unless the key is filtered — free text a coercer or sorbet
         # wrote can spell a value any way, so for a filtered key none of it
         # survives, not the parts that would have been safe.
         def detail(key, detail) = filtered?(key) ? FILTERED : detail
+
+        # A value the library reports as DATA rather than inside a sentence —
+        # InputError#value. Scrubbed at every depth, so a filtered key nested
+        # inside an input object is covered too, and the same list decides it
+        # as decides the debug log's variables line.
+        def value(key, value) = Log.filter_variables({ key.to_s => value })[key.to_s]
+
+        # A value the library spells INTO a sentence. `detail` can only ask
+        # about the key the value arrived under, so it reads a filtered key one
+        # level in as safe; this scrubs at every depth, like #value. The key is
+        # optional because a coercer refusing a value hasn't been told one.
+        def shown(raw, key = nil) = filtered?(key) ? FILTERED : cap(value(key, raw).inspect)
+
+        # A short server-chosen string the library republishes inside its own
+        # text — the APM's :code, the [CODE] in the one line info writes, a
+        # redirect's destination. Control characters are stripped because it
+        # lands where the log's own framing lives: a newline in
+        # extensions.code forges a second, complete-looking line.
+        def tag(value) = value.is_a?(String) ? cap(value.gsub(/[[:cntrl:]]+/, " ")) : value
+
+        # Text the library didn't author — a value a caller sent, a sentence a
+        # server wrote — cut to what an error may carry. The number lives on
+        # InputError, which is the class that documents it and the one every
+        # capped string reaches.
+        def cap(text, limit = GraphWeaver::InputError::VALUE_LIMIT)
+          return text if text.bytesize <= limit
+
+          # byteslice can land mid-character; scrub drops the partial tail
+          "#{text.byteslice(0, limit).scrub("")}…(#{text.bytesize - limit} more bytes)"
+        end
       end
     end
   end
@@ -91,14 +134,23 @@ module GraphWeaver
   self.filter_parameters = DEFAULT_FILTER_PARAMETERS
 
   # The one instrumentation event: a single GraphQL request, start to
-  # parsed response, whichever client slot served it.
-  EXECUTE_EVENT = "graph_weaver.execute"
+  # parsed response, whichever client slot served it. `<event>.<namespace>`
+  # is how every notification in this ecosystem is spelled
+  # (sql.active_record, execute_multiplex.graphql) — it's what
+  # ActiveSupport::LogSubscriber.attach_to and an APM's namespace routing
+  # key on, so a backwards name made both of them a puzzle.
+  EXECUTE_EVENT = "execute.graph_weaver"
 
   module Internal
     # The emitting half of the narration the three accessors above
     # configure. Setting a logger is API; writing to it is not, and the
     # two read as a pair when they sit on the same object.
     module Log
+      # fiber-local, set only for the duration of one attempt (with_retries)
+      RETRIES = :graph_weaver_retries
+      # fiber-local, set only for the duration of one dispatch (with_graph)
+      GRAPH = :graph_weaver_graph
+
       class << self
         # Level-gated and lazy — the block only runs when a logger is
         # listening. Messages carry "graph_weaver" as progname.
@@ -118,13 +170,91 @@ module GraphWeaver
           result
         end
 
-        # Wrap the block in the instrumenter, if one is set. The payload is
-        # a plain Hash the caller may add to inside the block.
+        # Wrap the block in the instrumenter, if one is set. The caller
+        # supplies what only it knows (:url, :schema, :client); this fills
+        # in the half every path shares — how it ended, how long it took,
+        # what a Retry had already spent — so one subscriber reads one
+        # shape whichever client slot served the request.
         def instrument(event, payload)
           hook = GraphWeaver.instrumenter
           return yield unless hook
 
-          hook.call(event, payload) { yield }
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          retries = Thread.current[RETRIES]
+          payload[:retries] = retries if retries
+          payload[:graph] = Thread.current[GRAPH]
+          # pessimistic, so :status is set even for what a rescue can't
+          # see — an Interrupt, a killed thread — and never silently absent
+          payload[:status] = :failed
+
+          # One dispatch labels one request. Whatever THIS request reaches —
+          # a resolver serving it that calls out — is a request of its own,
+          # and the caller's graph would be a wrong label on it.
+          with_graph(nil) do
+            hook.call(event, payload) do
+              result = yield
+              errors = response_errors(result)
+              if errors.empty?
+                payload[:status] = :ok
+              else
+                payload[:status] = :errors
+                code = errors.grep(Hash).filter_map { |e| GraphWeaver::GraphQLError.from_h(e).code }.first
+                payload[:code] = Redact.tag(code)
+              end
+              result
+            rescue => e
+              payload[:error] = e.class.name
+              # :code stays the GraphQL error code and nothing else — it used
+              # to hold a ServerError's status here, so one tag carried two
+              # dimensions ("THROTTLED" and 429). The number is :http_status.
+              raise
+            ensure
+              payload[:duration_ms] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
+            end
+          end
+        end
+
+        # What a Retry has already spent, read by the attempt it is about
+        # to make. A dynamic extent rather than a global: the count is only
+        # visible while the call it describes is on the stack, so a client
+        # that never reaches instrument can't leave a stale one behind.
+        def with_retries(count)
+          return yield unless GraphWeaver.instrumenter
+
+          previous = Thread.current[RETRIES]
+          Thread.current[RETRIES] = count
+          begin
+            yield
+          ensure
+            Thread.current[RETRIES] = previous
+          end
+        end
+
+        # The graph a generated module is dispatching, read by the request it
+        # is about to make. Same dynamic extent as with_retries, for the same
+        # reason — and instrument clears it for the duration of the request it
+        # labels, so exactly one request wears the label.
+        def with_graph(name)
+          return yield unless GraphWeaver.instrumenter
+
+          previous = Thread.current[GRAPH]
+          Thread.current[GRAPH] = name
+          begin
+            yield
+          ensure
+            Thread.current[GRAPH] = previous
+          end
+        end
+
+        # The variables as one JSON line for a log: filtered, and unable to
+        # raise. A value with no JSON form (NaN, binary) is the caller's bug
+        # and the transport refuses it a few lines later — but a logger that
+        # decides WHICH exception a caller sees, or whether one is raised at
+        # all, is worse than a log line that says it couldn't render.
+        def variables_for_log(variables)
+          JSON.generate(filter_variables(variables))
+        rescue StandardError => e
+          "<unloggable: #{e.class}>"
         end
 
         # variables with the filtered keys blanked out
@@ -136,8 +266,29 @@ module GraphWeaver
           filters.nil? ? variables : filters.filter(variables)
         end
 
+        # Whether a key matches one of `filters` — the same matching the
+        # variables line uses, asked about a list other than the app's so
+        # Redact.credential? can hold url parameters to the default names.
+        def filtered?(key, filters)
+          name = key.to_s
+          filters.any? do |filter|
+            filter.is_a?(Regexp) ? name.match?(filter) : name.downcase.include?(filter.to_s.downcase)
+          end
+        end
+
         private
 
+        # The GraphQL errors a response carries, whatever answered it — a
+        # Hash from a transport, a graphql-ruby Result in-process, a fake.
+        # Never raises: an instrumenter that decides which exception a
+        # caller sees is worse than a missing tag.
+        def response_errors(result)
+          errors = result.to_h["errors"] if result.respond_to?(:to_h)
+          errors.is_a?(Array) ? errors : []
+        rescue StandardError
+          []
+        end
+
         def scrub(value, filters)
           case value
           when Hash then value.to_h { |k, v| [k, filtered?(k, filters) ? FILTERED : scrub(v, filters)] }
@@ -145,13 +296,6 @@ module GraphWeaver
           else value
           end
         end
-
-        def filtered?(key, filters)
-          name = key.to_s
-          filters.any? do |filter|
-            filter.is_a?(Regexp) ? name.match?(filter) : name.downcase.include?(filter.to_s.downcase)
-          end
-        end
       end
     end
   end