graphql 2.2.17 → 2.5.16

data/lib/graphql/tracing/detailed_trace/memory_backend.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Tracing
+    class DetailedTrace
+      # An in-memory trace storage backend. Suitable for testing and development only.
+      # It won't work for multi-process deployments and everything is erased when the app is restarted.
+      class MemoryBackend
+        def initialize(limit: nil)
+          @limit = limit
+          @traces = {}
+          @next_id = 0
+        end
+
+        def traces(last:, before:)
+          page = []
+          @traces.values.reverse_each do |trace|
+            if page.size == last
+              break
+            elsif before.nil? || trace.begin_ms < before
+              page << trace
+            end
+          end
+          page
+        end
+
+        def find_trace(id)
+          @traces[id]
+        end
+
+        def delete_trace(id)
+          @traces.delete(id.to_i)
+          nil
+        end
+
+        def delete_all_traces
+          @traces.clear
+          nil
+        end
+
+        def save_trace(operation_name, duration, begin_ms, trace_data)
+          id = @next_id
+          @next_id += 1
+          @traces[id] = DetailedTrace::StoredTrace.new(
+            id: id,
+            operation_name: operation_name,
+            duration_ms: duration,
+            begin_ms: begin_ms,
+            trace_data: trace_data
+          )
+          if @limit && @traces.size > @limit
+            del_keys = @traces.keys[0...-@limit]
+            del_keys.each { |k| @traces.delete(k) }
+          end
+          id
+        end
+      end
+    end
+  end
+end

data/lib/graphql/tracing/detailed_trace/redis_backend.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Tracing
+    class DetailedTrace
+      class RedisBackend
+        KEY_PREFIX = "gql:trace:"
+        def initialize(redis:, limit: nil)
+          @redis = redis
+          @key = KEY_PREFIX + "traces"
+          @remrangebyrank_limit = limit ? -limit - 1 : nil
+        end
+
+        def traces(last:, before:)
+          before = case before
+          when Numeric
+            "(#{before}"
+          when nil
+            "+inf"
+          end
+          str_pairs = @redis.zrange(@key, before, 0, byscore: true, rev: true, limit: [0, last || 100], withscores: true)
+          str_pairs.map do |(str_data, score)|
+            entry_to_trace(score, str_data)
+          end
+        end
+
+        def delete_trace(id)
+          @redis.zremrangebyscore(@key, id, id)
+          nil
+        end
+
+        def delete_all_traces
+          @redis.del(@key)
+        end
+
+        def find_trace(id)
+          str_data = @redis.zrange(@key, id, id, byscore: true).first
+          if str_data.nil?
+            nil
+          else
+            entry_to_trace(id, str_data)
+          end
+        end
+
+        def save_trace(operation_name, duration_ms, begin_ms, trace_data)
+          id = begin_ms
+          data = JSON.dump({ "o" => operation_name, "d" => duration_ms, "b" => begin_ms, "t" => Base64.encode64(trace_data) })
+          @redis.pipelined do |pipeline|
+            pipeline.zadd(@key, id, data)
+            if @remrangebyrank_limit
+              pipeline.zremrangebyrank(@key, 0, @remrangebyrank_limit)
+            end
+          end
+          id
+        end
+
+        private
+
+        def entry_to_trace(id, json_str)
+          data = JSON.parse(json_str)
+          StoredTrace.new(
+            id: id,
+            operation_name: data["o"],
+            duration_ms: data["d"].to_f,
+            begin_ms: data["b"].to_i,
+            trace_data: Base64.decode64(data["t"]),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/graphql/tracing/detailed_trace.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+require "graphql/tracing/detailed_trace/memory_backend"
+require "graphql/tracing/detailed_trace/redis_backend"
+
+module GraphQL
+  module Tracing
+    # `DetailedTrace` can make detailed profiles for a subset of production traffic.
+    #
+    # When `MySchema.detailed_trace?(query)` returns `true`, a profiler-specific `trace_mode: ...` will be used for the query,
+    # overriding the one in `context[:trace_mode]`.
+    #
+    # By default, the detailed tracer calls `.inspect` on application objects returned from fields. You can customize
+    # this behavior by extending {DetailedTrace} and overriding {#inspect_object}. You can opt out of debug annotations
+    # entirely with `use ..., debug: false` or for a single query with `context: { detailed_trace_debug: false }`.
+    #
+    # __Redis__: The sampler stores its results in a provided Redis database. Depending on your needs,
+    # You can configure this database to retain all data (persistent) or to expire data according to your rules.
+    # If you need to save traces indefinitely, you can download them from Perfetto after opening them there.
+    #
+    # @example Adding the sampler to your schema
+    #   class MySchema < GraphQL::Schema
+    #     # Add the sampler:
+    #     use GraphQL::Tracing::DetailedTrace, redis: Redis.new(...), limit: 100
+    #
+    #     # And implement this hook to tell it when to take a sample:
+    #     def self.detailed_trace?(query)
+    #       # Could use `query.context`, `query.selected_operation_name`, `query.query_string` here
+    #       # Could call out to Flipper, etc
+    #       rand <= 0.000_1 # one in ten thousand
+    #     end
+    #   end
+    #
+    # @see Graphql::Dashboard GraphQL::Dashboard for viewing stored results
+    #
+    # @example Customizing debug output in traces
+    #   class CustomDetailedTrace < GraphQL::Tracing::DetailedTrace
+    #     def inspect_object(object)
+    #       if object.is_a?(SomeThing)
+    #         # handle it specially ...
+    #       else
+    #         super
+    #        end
+    #     end
+    #   end
+    #
+    # @example disabling debug annotations completely
+    #    use DetailedTrace, debug: false, ...
+    #
+    # @example disabling debug annotations for one query
+    #    MySchema.execute(query_str, context: { detailed_trace_debug: false })
+    #
+    class DetailedTrace
+      # @param redis [Redis] If provided, profiles will be stored in Redis for later review
+      # @param limit [Integer] A maximum number of profiles to store
+      # @param debug [Boolean] if `false`, it won't create `debug` annotations in Perfetto traces (reduces overhead)
+      def self.use(schema, trace_mode: :profile_sample, memory: false, debug: debug?, redis: nil, limit: nil)
+        storage = if redis
+          RedisBackend.new(redis: redis, limit: limit)
+        elsif memory
+          MemoryBackend.new(limit: limit)
+        else
+          raise ArgumentError, "Pass `redis: ...` to store traces in Redis for later review"
+        end
+        detailed_trace = self.new(storage: storage, trace_mode: trace_mode, debug: debug)
+        schema.detailed_trace = detailed_trace
+        schema.trace_with(PerfettoTrace, mode: trace_mode, save_profile: true)
+      end
+
+      def initialize(storage:, trace_mode:, debug:)
+        @storage = storage
+        @trace_mode = trace_mode
+        @debug = debug
+      end
+
+      # @return [Symbol] The trace mode to use when {Schema.detailed_trace?} returns `true`
+      attr_reader :trace_mode
+
+      # @return [String] ID of saved trace
+      def save_trace(operation_name, duration_ms, begin_ms, trace_data)
+        @storage.save_trace(operation_name, duration_ms, begin_ms, trace_data)
+      end
+
+      # @return [Boolean]
+      def debug?
+        @debug
+      end
+
+      # @param last [Integer]
+      # @param before [Integer] Timestamp in milliseconds since epoch
+      # @return [Enumerable<StoredTrace>]
+      def traces(last: nil, before: nil)
+        @storage.traces(last: last, before: before)
+      end
+
+      # @return [StoredTrace, nil]
+      def find_trace(id)
+        @storage.find_trace(id)
+      end
+
+      # @return [void]
+      def delete_trace(id)
+        @storage.delete_trace(id)
+      end
+
+      # @return [void]
+      def delete_all_traces
+        @storage.delete_all_traces
+      end
+
+      def inspect_object(object)
+        self.class.inspect_object(object)
+      end
+
+      def self.inspect_object(object)
+        if defined?(ActiveRecord::Relation) && object.is_a?(ActiveRecord::Relation)
+          "#{object.class}, .to_sql=#{object.to_sql.inspect}"
+        else
+          object.inspect
+        end
+      end
+
+      # Default debug setting
+      # @return [true]
+      def self.debug?
+        true
+      end
+
+      class StoredTrace
+        def initialize(id:, operation_name:, duration_ms:, begin_ms:, trace_data:)
+          @id = id
+          @operation_name = operation_name
+          @duration_ms = duration_ms
+          @begin_ms = begin_ms
+          @trace_data = trace_data
+        end
+
+        attr_reader :id, :operation_name, :duration_ms, :begin_ms, :trace_data
+      end
+    end
+  end
+end

data/lib/graphql/tracing/legacy_hooks_trace.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module GraphQL
   module Tracing
     module LegacyHooksTrace

data/lib/graphql/tracing/legacy_trace.rb

@@ -1,67 +1,10 @@
 # frozen_string_literal: true
-module GraphQL
-  module Tracing
-    # This trace class calls legacy-style tracer with payload hashes.
-    # New-style `trace_with` modules significantly reduce the overhead of tracing,
-    # but that advantage is lost when legacy-style tracers are also used (since the payload hashes are still constructed).
-    module CallLegacyTracers
-      def lex(query_string:)
-        (@multiplex || @query).trace("lex", { query_string: query_string }) { super }
-      end
-
-      def parse(query_string:)
-        (@multiplex || @query).trace("parse", { query_string: query_string }) { super }
-      end
-
-      def validate(query:, validate:)
-        query.trace("validate", { validate: validate, query: query }) { super }
-      end
-
-      def analyze_multiplex(multiplex:)
-        multiplex.trace("analyze_multiplex", { multiplex: multiplex }) { super }
-      end
-
-      def analyze_query(query:)
-        query.trace("analyze_query", { query: query }) { super }
-      end
-
-      def execute_multiplex(multiplex:)
-        multiplex.trace("execute_multiplex", { multiplex: multiplex }) { super }
-      end
-
-      def execute_query(query:)
-        query.trace("execute_query", { query: query }) { super }
-      end
-
-      def execute_query_lazy(query:, multiplex:)
-        multiplex.trace("execute_query_lazy", { multiplex: multiplex, query: query }) { super }
-      end
 
-      def execute_field(field:, query:, ast_node:, arguments:, object:)
-        query.trace("execute_field", { field: field, query: query, ast_node: ast_node, arguments: arguments, object: object, owner: field.owner, path: query.context[:current_path] }) { super }
-      end
-
-      def execute_field_lazy(field:, query:, ast_node:, arguments:, object:)
-        query.trace("execute_field_lazy", { field: field, query: query, ast_node: ast_node, arguments: arguments, object: object, owner: field.owner, path: query.context[:current_path] }) { super }
-      end
-
-      def authorized(query:, type:, object:)
-        query.trace("authorized", { context: query.context, type: type, object: object, path: query.context[:current_path] }) { super }
-      end
-
-      def authorized_lazy(query:, type:, object:)
-        query.trace("authorized_lazy", { context: query.context, type: type, object: object, path: query.context[:current_path] }) { super }
-      end
-
-      def resolve_type(query:, type:, object:)
-        query.trace("resolve_type", { context: query.context, type: type, object: object, path: query.context[:current_path] }) { super }
-      end
-
-      def resolve_type_lazy(query:, type:, object:)
-        query.trace("resolve_type_lazy", { context: query.context, type: type, object: object, path: query.context[:current_path] }) { super }
-      end
-    end
+require "graphql/tracing/trace"
+require "graphql/tracing/call_legacy_tracers"
 
+module GraphQL
+  module Tracing
     class LegacyTrace < Trace
       include CallLegacyTracers
     end

data/lib/graphql/tracing/monitor_trace.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Tracing
+    # This module is the basis for Ruby-level integration with third-party monitoring platforms.
+    # Platform-specific traces include this module and implement an adapter.
+    #
+    # @see ActiveSupportNotificationsTrace Integration via ActiveSupport::Notifications, an alternative approach.
+    module MonitorTrace
+      class Monitor
+        def initialize(trace:, set_transaction_name:, **_rest)
+          @trace = trace
+          @set_transaction_name = set_transaction_name
+          @platform_field_key_cache = Hash.new { |h, k| h[k] = platform_field_key(k) }.compare_by_identity
+          @platform_authorized_key_cache = Hash.new { |h, k| h[k] = platform_authorized_key(k) }.compare_by_identity
+          @platform_resolve_type_key_cache = Hash.new { |h, k| h[k] = platform_resolve_type_key(k) }.compare_by_identity
+          @platform_source_class_key_cache = Hash.new { |h, source_cls| h[source_cls] = platform_source_class_key(source_cls) }.compare_by_identity
+        end
+
+        def instrument(keyword, object, &block)
+          raise "Implement #{self.class}#instrument to measure the block"
+        end
+
+        def start_event(keyword, object)
+          ev = self.class::Event.new(self, keyword, object)
+          ev.start
+          ev
+        end
+
+        # Get the transaction name based on the operation type and name if possible, or fall back to a user provided
+        # one. Useful for anonymous queries.
+        def transaction_name(query)
+          selected_op = query.selected_operation
+          txn_name = if selected_op
+            op_type = selected_op.operation_type
+            op_name = selected_op.name || fallback_transaction_name(query.context) || "anonymous"
+            "#{op_type}.#{op_name}"
+          else
+            "query.anonymous"
+          end
+          "GraphQL/#{txn_name}"
+        end
+
+        def fallback_transaction_name(context)
+          context[:tracing_fallback_transaction_name]
+        end
+
+        def name_for(keyword, object)
+          case keyword
+          when :execute_field
+            @platform_field_key_cache[object]
+          when :authorized
+            @platform_authorized_key_cache[object]
+          when :resolve_type
+            @platform_resolve_type_key_cache[object]
+          when :dataloader_source
+            @platform_source_class_key_cache[object.class]
+          when :parse then self.class::PARSE_NAME
+          when :lex then self.class::LEX_NAME
+          when :execute then self.class::EXECUTE_NAME
+          when :analyze then self.class::ANALYZE_NAME
+          when :validate then self.class::VALIDATE_NAME
+          else
+            raise "No name for #{keyword.inspect}"
+          end
+        end
+
+        class Event
+          def initialize(monitor, keyword, object)
+            @monitor = monitor
+            @keyword = keyword
+            @object = object
+          end
+
+          attr_reader :keyword, :object
+
+          def start
+            raise "Implement #{self.class}#start to begin a new event (#{inspect})"
+          end
+
+          def finish
+            raise "Implement #{self.class}#finish to end this event (#{inspect})"
+          end
+        end
+
+        module GraphQLSuffixNames
+          PARSE_NAME = "parse.graphql"
+          LEX_NAME = "lex.graphql"
+          VALIDATE_NAME = "validate.graphql"
+          EXECUTE_NAME = "execute.graphql"
+          ANALYZE_NAME = "analyze.graphql"
+
+          def platform_field_key(field)
+            "#{field.path}.graphql"
+          end
+
+          def platform_authorized_key(type)
+            "#{type.graphql_name}.authorized.graphql"
+          end
+
+          def platform_resolve_type_key(type)
+            "#{type.graphql_name}.resolve_type.graphql"
+          end
+
+          def platform_source_class_key(source_class)
+            "#{source_class.name.gsub("::", "_")}.fetch.graphql"
+          end
+        end
+
+        module GraphQLPrefixNames
+          PARSE_NAME = "graphql.parse"
+          LEX_NAME = "graphql.lex"
+          VALIDATE_NAME = "graphql.validate"
+          EXECUTE_NAME = "graphql.execute"
+          ANALYZE_NAME = "graphql.analyze"
+
+          def platform_field_key(field)
+            "graphql.#{field.path}"
+          end
+
+          def platform_authorized_key(type)
+            "graphql.authorized.#{type.graphql_name}"
+          end
+
+          def platform_resolve_type_key(type)
+            "graphql.resolve_type.#{type.graphql_name}"
+          end
+
+          def platform_source_class_key(source_class)
+            "graphql.fetch.#{source_class.name.gsub("::", "_")}"
+          end
+        end
+      end
+
+      def self.create_module(monitor_name)
+        if !monitor_name.match?(/[a-z]+/)
+          raise ArgumentError, "monitor name must be [a-z]+, not: #{monitor_name.inspect}"
+        end
+
+        trace_module = Module.new
+        code = MODULE_TEMPLATE % {
+          monitor: monitor_name,
+          monitor_class: monitor_name.capitalize + "Monitor",
+        }
+        trace_module.module_eval(code, __FILE__, __LINE__ + 5) # rubocop:disable Development/NoEvalCop This is build-time with a validated string
+        trace_module
+      end
+
+      MODULE_TEMPLATE = <<~RUBY
+        # @param set_transaction_name [Boolean] If `true`, use the GraphQL operation name as the request name on the monitoring platform
+        # @param trace_scalars [Boolean] If `true`, leaf fields will be traced too (Scalars _and_ Enums)
+        # @param trace_authorized [Boolean] If `false`, skip tracing `authorized?` calls
+        # @param trace_resolve_type [Boolean] If `false`, skip tracing `resolve_type?` calls
+        def initialize(...)
+          setup_%{monitor}_monitor(...)
+          super
+        end
+
+        def setup_%{monitor}_monitor(trace_scalars: false, trace_authorized: true, trace_resolve_type: true, set_transaction_name: false, **kwargs)
+          @trace_scalars = trace_scalars
+          @trace_authorized = trace_authorized
+          @trace_resolve_type = trace_resolve_type
+          @set_transaction_name = set_transaction_name
+          @%{monitor} = %{monitor_class}.new(trace: self, set_transaction_name: @set_transaction_name, **kwargs)
+        end
+
+        def parse(query_string:)
+          @%{monitor}.instrument(:parse, query_string) do
+            super
+          end
+        end
+
+        def lex(query_string:)
+          @%{monitor}.instrument(:lex, query_string) do
+            super
+          end
+        end
+
+        def validate(query:, validate:)
+          @%{monitor}.instrument(:validate, query) do
+            super
+          end
+        end
+
+        def begin_analyze_multiplex(multiplex, analyzers)
+          begin_%{monitor}_event(:analyze, nil)
+          super
+        end
+
+        def end_analyze_multiplex(multiplex, analyzers)
+          finish_%{monitor}_event
+          super
+        end
+
+        def execute_multiplex(multiplex:)
+          @%{monitor}.instrument(:execute, multiplex) do
+            super
+          end
+        end
+
+        def begin_execute_field(field, object, arguments, query)
+          return_type = field.type.unwrap
+          trace_field = if return_type.kind.scalar? || return_type.kind.enum?
+            (field.trace.nil? && @trace_scalars) || field.trace
+          else
+            true
+          end
+
+          if trace_field
+            begin_%{monitor}_event(:execute_field, field)
+          end
+          super
+        end
+
+        def end_execute_field(field, object, arguments, query, result)
+          finish_%{monitor}_event
+          super
+        end
+
+        def dataloader_fiber_yield(source)
+          Fiber[PREVIOUS_EV_KEY] = finish_%{monitor}_event
+          super
+        end
+
+        def dataloader_fiber_resume(source)
+          prev_ev = Fiber[PREVIOUS_EV_KEY]
+          if prev_ev
+            begin_%{monitor}_event(prev_ev.keyword, prev_ev.object)
+          end
+          super
+        end
+
+        def begin_authorized(type, object, context)
+          @trace_authorized && begin_%{monitor}_event(:authorized, type)
+          super
+        end
+
+        def end_authorized(type, object, context, result)
+          finish_%{monitor}_event
+          super
+        end
+
+        def begin_resolve_type(type, value, context)
+          @trace_resolve_type && begin_%{monitor}_event(:resolve_type, type)
+          super
+        end
+
+        def end_resolve_type(type, value, context, resolved_type)
+          finish_%{monitor}_event
+          super
+        end
+
+        def begin_dataloader_source(source)
+          begin_%{monitor}_event(:dataloader_source, source)
+          super
+        end
+
+        def end_dataloader_source(source)
+          finish_%{monitor}_event
+          super
+        end
+
+        CURRENT_EV_KEY = :__graphql_%{monitor}_trace_event
+        PREVIOUS_EV_KEY = :__graphql_%{monitor}_trace_previous_event
+
+        private
+
+        def begin_%{monitor}_event(keyword, object)
+          Fiber[CURRENT_EV_KEY] = @%{monitor}.start_event(keyword, object)
+        end
+
+        def finish_%{monitor}_event
+          if ev = Fiber[CURRENT_EV_KEY]
+            ev.finish
+            # Use `false` to prevent grabbing an event from a parent fiber
+            Fiber[CURRENT_EV_KEY] = false
+            ev
+          end
+        end
+      RUBY
+    end
+  end
+end