graphql-metrics 2.0.1 → 3.0.0

data/Rakefile

@@ -5,6 +5,12 @@ Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
   t.test_files = FileList["test/**/*_test.rb"]
+
+  # TODO: We should remove this line. See `puts` line below.
+  t.warning = false
+
+  puts "Reminder: Remove `t.warning = false` in Rakefile once graphql-ruby fixes all instances of"\
+    "`warning: instance variable @<ivar> not initialized` and `mismatched indentations`"
 end
 
 task :default => :test

data/bin/console

@@ -1,14 +1,12 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "graphql_metrics"
+require 'graphql'
+require "graphql/metrics"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start(__FILE__)
+require "pry"
+Pry.start

data/graphql_metrics.gemspec

@@ -1,11 +1,8 @@
-
-lib = File.expand_path("../lib", __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "graphql_metrics/version"
+require_relative "lib/graphql/metrics/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "graphql-metrics"
-  spec.version       = GraphQLMetrics::VERSION
+  spec.version       = GraphQL::Metrics::VERSION
   spec.authors       = ["Christopher Butcher"]
   spec.email         = ["gems@shopify.com"]
 
@@ -33,16 +30,19 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_runtime_dependency "concurrent-ruby", "~> 1.1.0"
+  spec.add_runtime_dependency "graphql", "~> 1.9.15"
+
+  spec.add_development_dependency "bundler", "~> 2.0.2"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest", "~> 5.0"
   spec.add_development_dependency 'graphql-batch'
-  spec.add_development_dependency "graphql", "~> 1.8.2"
   spec.add_development_dependency "activesupport", "~> 5.1.5"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "pry-byebug"
   spec.add_development_dependency "mocha"
   spec.add_development_dependency "diffy"
+  spec.add_development_dependency "hashdiff"
   spec.add_development_dependency "fakeredis"
   spec.add_development_dependency "minitest-focus"
 end

data/lib/graphql/metrics.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "concurrent"
+require "graphql/metrics/version"
+require "graphql/metrics/instrumentation"
+require "graphql/metrics/tracer"
+require "graphql/metrics/analyzer"
+
+module GraphQL
+  module Metrics
+    # The context namespace for all values stored by this gem.
+    CONTEXT_NAMESPACE = :graphql_metrics_analysis
+
+    # Skip metrics capture altogher, by setting `skip_graphql_metrics_analysis: true` in query context.
+    SKIP_GRAPHQL_METRICS_ANALYSIS = :skip_graphql_metrics_analysis
+
+    # Skips just field and argument logging, when query metrics logging is still desirable
+    SKIP_FIELD_AND_ARGUMENT_METRICS = :skip_field_and_argument_metrics
+
+    # Timings related constants.
+    TIMINGS_CAPTURE_ENABLED = :timings_capture_enabled
+    ANALYZER_INSTANCE_KEY = :analyzer_instance
+
+    # Context keys to store timings for query phases of execution, field resolver timings.
+    QUERY_START_TIME = :query_start_time
+    QUERY_START_TIME_MONOTONIC = :query_start_time_monotonic
+    PARSING_START_TIME_OFFSET = :parsing_start_time_offset
+    PARSING_DURATION = :parsing_duration
+    VALIDATION_START_TIME_OFFSET = :validation_start_time_offset
+    VALIDATION_DURATION = :validation_duration
+    INLINE_FIELD_TIMINGS = :inline_field_timings
+    LAZY_FIELD_TIMINGS = :lazy_field_timings
+
+    def self.timings_capture_enabled?(context)
+      return false unless context
+      !!context.namespace(CONTEXT_NAMESPACE)[TIMINGS_CAPTURE_ENABLED]
+    end
+
+    def self.current_time
+      Process.clock_gettime(Process::CLOCK_REALTIME)
+    end
+
+    def self.current_time_monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def self.time(*args)
+      TimedResult.new(*args) { yield }
+    end
+
+    class TimedResult
+      # NOTE: `time_since_offset` is used to produce start times timed phases of execution (validation, field
+      # resolution). These start times are relative to the executed operation's start time, which is captured at the
+      # outset of document parsing.
+      #
+      # The times produced are intentionally similar to:
+      # https://github.com/apollographql/apollo-tracing#response-format
+      #
+      # Taking a field resolver start offset example:
+      #
+      # <   start offset   >
+      # |------------------|----------|--------->
+      # OS (t=0)           FS (t=1)   FE (t=2)
+      #
+      # OS = Operation start time
+      # FS = Field resolver start time
+      # FE = Field resolver end time
+      #
+      attr_reader :result, :start_time, :duration, :time_since_offset
+
+      def initialize(offset_time = nil)
+        @offset_time = offset_time
+        @start_time = GraphQL::Metrics.current_time_monotonic
+        @result = yield
+        @duration = GraphQL::Metrics.current_time_monotonic - @start_time
+        @time_since_offset = @start_time - @offset_time if @offset_time
+      end
+    end
+  end
+end

data/lib/graphql/metrics/analyzer.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Metrics
+    class Analyzer < GraphQL::Analysis::AST::Analyzer
+      attr_reader :query
+
+      def initialize(query_or_multiplex)
+        super
+
+        @query = query_or_multiplex
+        ns = query.context.namespace(CONTEXT_NAMESPACE)
+        ns[ANALYZER_INSTANCE_KEY] = self
+
+        @static_query_metrics = nil
+        @static_field_metrics = []
+      end
+
+      def analyze?
+        query.valid? && !query.context[GraphQL::Metrics::SKIP_GRAPHQL_METRICS_ANALYSIS]
+      end
+
+      def extract_query(runtime_query_metrics: {})
+        query_extracted(@static_query_metrics.merge(runtime_query_metrics)) if @static_query_metrics
+      end
+
+      def on_enter_operation_definition(_node, _parent, visitor)
+        @static_query_metrics = {
+          operation_type: visitor.query.selected_operation.operation_type,
+          operation_name: visitor.query.selected_operation.name,
+        }
+      end
+
+      def on_leave_field(node, _parent, visitor)
+        return if visitor.field_definition.introspection?
+        return if query.context[SKIP_FIELD_AND_ARGUMENT_METRICS]
+
+        # NOTE: @rmosolgo "I think it could be reduced to `arguments = visitor.arguments_for(ast_node)`"
+        arguments = visitor.arguments_for(node, visitor.field_definition)
+        extract_arguments(arguments.argument_values.values, visitor.field_definition)
+
+        static_metrics = {
+          field_name: node.name,
+          return_type_name: visitor.type_definition.name,
+          parent_type_name: visitor.parent_type_definition.name,
+          deprecated: visitor.field_definition.deprecation_reason.present?,
+          path: visitor.response_path,
+        }
+
+        if GraphQL::Metrics.timings_capture_enabled?(query.context)
+          @static_field_metrics << static_metrics
+        else
+          field_extracted(static_metrics)
+        end
+      end
+
+      def extract_fields_with_runtime_metrics
+        return if query.context[SKIP_FIELD_AND_ARGUMENT_METRICS]
+
+        ns = query.context.namespace(CONTEXT_NAMESPACE)
+
+        @static_field_metrics.each do |static_metrics|
+          resolver_timings = ns[GraphQL::Metrics::INLINE_FIELD_TIMINGS][static_metrics[:path]]
+          lazy_field_timings = ns[GraphQL::Metrics::LAZY_FIELD_TIMINGS][static_metrics[:path]]
+
+          metrics = static_metrics.merge(
+            resolver_timings: resolver_timings || [],
+            lazy_resolver_timings: lazy_field_timings || [],
+          )
+
+          field_extracted(metrics)
+        end
+      end
+
+      def result
+        return if GraphQL::Metrics.timings_capture_enabled?(query.context)
+        return if query.context[GraphQL::Metrics::SKIP_GRAPHQL_METRICS_ANALYSIS]
+
+        # NOTE: If we're running as a static analyzer (i.e. not with instrumentation and tracing), we still need to
+        # flush static query metrics somewhere other than `after_query`.
+        ns = query.context.namespace(CONTEXT_NAMESPACE)
+        analyzer = ns[GraphQL::Metrics::ANALYZER_INSTANCE_KEY]
+        analyzer.extract_query
+      end
+
+      private
+
+      def extract_arguments(argument, field_defn, parent_input_object = nil)
+        case argument
+        when Array
+          argument.each do |a|
+            extract_arguments(a, field_defn, parent_input_object)
+          end
+        when Hash
+          argument.each_value do |a|
+            extract_arguments(a, field_defn, parent_input_object)
+          end
+        when ::GraphQL::Query::Arguments
+          argument.each_value do |arg_val|
+            extract_arguments(arg_val, field_defn, parent_input_object)
+          end
+        when ::GraphQL::Query::Arguments::ArgumentValue
+          extract_argument(argument, field_defn, parent_input_object)
+          extract_arguments(argument.value, field_defn, parent_input_object)
+        when ::GraphQL::Schema::InputObject
+          input_object_argument_values = argument.arguments.argument_values.values
+          parent_input_object = input_object_argument_values.first&.definition&.metadata&.fetch(:type_class, nil)&.owner
+
+          extract_arguments(input_object_argument_values, field_defn, parent_input_object)
+        end
+      end
+
+      def extract_argument(value, field_defn, parent_input_object = nil)
+        static_metrics = {
+          argument_name: value.definition.expose_as,
+          argument_type_name: value.definition.type.unwrap.to_s,
+          parent_field_name: field_defn.name,
+          parent_field_type_name: field_defn.metadata[:type_class].owner.graphql_name,
+          parent_input_object_type: parent_input_object&.graphql_name,
+          default_used: value.default_used?,
+          value_is_null: value.value.nil?,
+          value: value,
+        }
+
+        argument_extracted(static_metrics)
+      end
+    end
+  end
+end

data/lib/graphql/metrics/instrumentation.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Metrics
+    class Instrumentation
+      def before_query(query)
+        unless query_present_and_valid?(query)
+          # Setting this prevents Analyzer and Tracer from trying to gather runtime metrics for invalid queries.
+          query.context[GraphQL::Metrics::SKIP_GRAPHQL_METRICS_ANALYSIS] = true
+        end
+
+        # Even if queries are present and valid, applications may set this context value in order to opt out of
+        # having Analyzer and Tracer gather runtime metrics.
+        # If we're skipping runtime metrics, then both Instrumentation before_ and after_query can and should be
+        # short-circuited as well.
+        return if query.context[GraphQL::Metrics::SKIP_GRAPHQL_METRICS_ANALYSIS]
+
+        ns = query.context.namespace(CONTEXT_NAMESPACE)
+        ns[GraphQL::Metrics::TIMINGS_CAPTURE_ENABLED] = true
+        ns[GraphQL::Metrics::INLINE_FIELD_TIMINGS] = {}
+        ns[GraphQL::Metrics::LAZY_FIELD_TIMINGS] = {}
+      end
+
+      def after_query(query)
+        return if query.context[GraphQL::Metrics::SKIP_GRAPHQL_METRICS_ANALYSIS]
+
+        ns = query.context.namespace(CONTEXT_NAMESPACE)
+
+        # NOTE: The start time stored at `ns[GraphQL::Metrics::QUERY_START_TIME_MONOTONIC]` is captured during query
+        # parsing, which occurs before `Instrumentation#before_query`.
+        query_duration = GraphQL::Metrics.current_time_monotonic - ns[GraphQL::Metrics::QUERY_START_TIME_MONOTONIC]
+
+        runtime_query_metrics = {
+          query_start_time: ns[GraphQL::Metrics::QUERY_START_TIME],
+          query_duration: query_duration,
+          parsing_start_time_offset: ns[GraphQL::Metrics::PARSING_START_TIME_OFFSET],
+          parsing_duration: ns[GraphQL::Metrics::PARSING_DURATION],
+          validation_start_time_offset: ns[GraphQL::Metrics::VALIDATION_START_TIME_OFFSET],
+          validation_duration: ns[GraphQL::Metrics::VALIDATION_DURATION],
+        }
+
+        analyzer = ns[GraphQL::Metrics::ANALYZER_INSTANCE_KEY]
+        analyzer.extract_fields_with_runtime_metrics
+        analyzer.extract_query(runtime_query_metrics: runtime_query_metrics)
+      end
+
+      private
+
+      def query_present_and_valid?(query)
+        query.valid? && query.document.to_query_string.present?
+      end
+    end
+  end
+end

data/lib/graphql/metrics/tracer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Metrics
+    class Tracer
+      # NOTE: These constants come from the graphql ruby gem.
+      GRAPHQL_GEM_LEXING_KEY = 'lex'
+      GRAPHQL_GEM_PARSING_KEY = 'parse'
+      GRAPHQL_GEM_VALIDATION_KEYS = ['validate', 'analyze_query']
+      GRAPHQL_GEM_TRACING_FIELD_KEYS = [
+        GRAPHQL_GEM_TRACING_FIELD_KEY = 'execute_field',
+        GRAPHQL_GEM_TRACING_LAZY_FIELD_KEY = 'execute_field_lazy'
+      ]
+
+      def trace(key, data, &block)
+        # NOTE: Context doesn't exist yet during lexing, parsing.
+        possible_context = data[:query]&.context
+
+        skip_tracing = possible_context&.fetch(GraphQL::Metrics::SKIP_GRAPHQL_METRICS_ANALYSIS, false)
+        return yield if skip_tracing
+
+        # NOTE: Not all tracing events are handled here, but those that are are handled in this case statement in
+        # chronological order.
+        case key
+        when GRAPHQL_GEM_LEXING_KEY
+          return setup_tracing_before_lexing(&block)
+        when GRAPHQL_GEM_PARSING_KEY
+          return capture_parsing_time(&block)
+        when *GRAPHQL_GEM_VALIDATION_KEYS
+          context = possible_context
+
+          return yield unless context.query.valid?
+          return capture_validation_time(context, &block)
+        when *GRAPHQL_GEM_TRACING_FIELD_KEYS
+          return yield if data[:query].context[SKIP_FIELD_AND_ARGUMENT_METRICS]
+          return yield unless GraphQL::Metrics.timings_capture_enabled?(data[:query].context)
+
+          pre_context = nil
+
+          context_key = case key
+          when GRAPHQL_GEM_TRACING_FIELD_KEY
+            GraphQL::Metrics::INLINE_FIELD_TIMINGS
+          when GRAPHQL_GEM_TRACING_LAZY_FIELD_KEY
+            GraphQL::Metrics::LAZY_FIELD_TIMINGS
+          end
+
+          trace_field(context_key, data, &block)
+        else
+          return yield
+        end
+      end
+
+      private
+
+      def pre_context
+        # NOTE: This is used to store timings from lexing, parsing, validation, before we have a context to store
+        # values in. Uses thread-safe Concurrent::ThreadLocalVar to store a set of values per thread.
+        @pre_context ||= Concurrent::ThreadLocalVar.new(OpenStruct.new)
+      end
+
+      def setup_tracing_before_lexing
+        pre_context.value.query_start_time = GraphQL::Metrics.current_time
+        pre_context.value.query_start_time_monotonic = GraphQL::Metrics.current_time_monotonic
+
+        yield
+      end
+
+      def capture_parsing_time
+        timed_result = GraphQL::Metrics.time { yield }
+
+        pre_context.value.parsing_start_time_offset = timed_result.start_time
+        pre_context.value.parsing_duration = timed_result.duration
+
+        timed_result.result
+      end
+
+      def capture_validation_time(context)
+        timed_result = GraphQL::Metrics.time(pre_context.value.query_start_time_monotonic) { yield }
+
+        ns = context.namespace(CONTEXT_NAMESPACE)
+        previous_validation_duration = ns[GraphQL::Metrics::VALIDATION_DURATION] || 0
+
+        ns[QUERY_START_TIME] = pre_context.value.query_start_time
+        ns[QUERY_START_TIME_MONOTONIC] = pre_context.value.query_start_time_monotonic
+        ns[PARSING_START_TIME_OFFSET] = pre_context.value.parsing_start_time_offset
+        ns[PARSING_DURATION] = pre_context.value.parsing_duration
+        ns[VALIDATION_START_TIME_OFFSET] = timed_result.time_since_offset
+        ns[VALIDATION_DURATION] = timed_result.duration + previous_validation_duration
+
+        timed_result.result
+      end
+
+      def trace_field(context_key, data)
+        ns = data[:query].context.namespace(CONTEXT_NAMESPACE)
+        query_start_time_monotonic = ns[GraphQL::Metrics::QUERY_START_TIME_MONOTONIC]
+
+        timed_result = GraphQL::Metrics.time(query_start_time_monotonic) { yield }
+
+        path_excluding_numeric_indicies = data[:path].select { |p| p.is_a?(String) }
+        ns[context_key][path_excluding_numeric_indicies] ||= []
+        ns[context_key][path_excluding_numeric_indicies] << {
+          start_time_offset: timed_result.time_since_offset, duration: timed_result.duration
+        }
+
+        timed_result.result
+      end
+    end
+  end
+end

data/lib/graphql/metrics/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Metrics
+    VERSION = "3.0.0"
+  end
+end