graphql-persisted_queries 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12531a6f0099e3220f5ea0bf400b1ccd23f2e6f3161d91d54c05ae404d3e1532
-  data.tar.gz: 4660b422f801db343ce2f8e04ea21576ae500d7d9519f87399300e957f555160
+  metadata.gz: 47cee014870d4382ee5d140302c25a5942ac2e0b8ba3886577a9299e8e097e24
+  data.tar.gz: 1d0406419d6bcce3137863906d72c3d5a670cf56477c166d54b1dc182e016dfa
 SHA512:
-  metadata.gz: c2d317723d55e67aebc607624e32e7052c53f378e8dd4584d161102167f5f44c221580518ab912a88db3e8b82381455ba77b20aefce5904602159c33bd23b88c
-  data.tar.gz: b831aeb69392cdd662fcf285cc8f48051feb3cd3703db862bd4434cfdbb67acd4b85cf70ae64cbcee61f7df969cbd913c152517af4a7da2b7121ae99fd0282a4
+  metadata.gz: b5cf4c0e7d3021dff138122c176983edc1ebbf17ffad0327423389d354e19f6fdc1ef541be58adb5aa4d364aa0e21bf17226ede8dee47cb94f283d677dae326a
+  data.tar.gz: 10763b571169cdddd8c47c31f4a0350ee8a0a5d3aa6729f6a7669799800b3474810edecd5126c4c6f18c5cf5b52de7ac4f686c5ead9d648eb3032f8cddedbe4c

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## master
 
+## 0.5.0 (2020-03-12)
+
+- [PR#29](https://github.com/DmitryTsepelev/graphql-ruby-persisted_queries/pull/29) Instrumentation via graphql-ruby's tracer feature ([@bmorton][])
+
 ## 0.4.0 (2020-02-26)
 
 - [PR#26](https://github.com/DmitryTsepelev/graphql-ruby-persisted_queries/pull/26) Add Memcached store ([@JanStevens][])

data/README.md

@@ -208,6 +208,10 @@ Using `GET` requests for persisted queries allows you to enable HTTP caching (e.
 
 HTTP method verification is important, because when mutations are allowed via `GET` requests, it's easy to perform an attack by sending the link containing mutation to a signed in user.
 
+## Tracing and instrumentation
+
+An experimental tracing feature can be enabled by setting `tracing: true` when configuring the plugin.  Read more about this feature in the [Tracing guide](docs/tracing.md).
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/DmitryTsepelev/graphql-ruby-persisted_queries.

data/docs/tracing.md

@@ -0,0 +1,51 @@
+# Tracing
+
+Tracing is an experimental feature that, when enabled, uses the tracing system defined in `graphql-ruby` to surface these events:
+
+* `persisted_queries.fetch_query.cache_hit` - Triggered when a store adapter successfully looks up a hash and finds a query.
+* `persisted_queries.fetch_query.cache_miss` - Triggered when a store adapter attempts to look up a hash but cannot find it.
+* `persisted_queries.save_query` - Triggered when a store adapter persists a query.
+
+All events include a metadata hash as their `data` parameter.  This hash currently only includes the name of the adapter that triggered the event.
+
+## Usage
+
+Tracing must be opted into via the plugin configuration for the events to trigger.  Once they are enabled, any tracer that is defined on the schema will get the following events yielded to them.  An example configuration will look similar to this:
+
+```ruby
+class GraphqlSchema < GraphQL::Schema
+  use GraphQL::PersistedQueries, tracing: true
+  tracer MyPersistedQueriesTracer
+end
+```
+
+Tracers in this plugin integrate with the `GraphQL::Tracing` feature in [`graphql-ruby`](https://github.com/rmosolgo/graphql-ruby).  The same tracers are used for tracing events directly from `graphql-ruby` and this plugin.  The [guide on "Tracing"](https://graphql-ruby.org/queries/tracing.html) in `graphql-ruby` has implementation details, but an example tracer would look similar to this:
+
+```ruby
+class MyPersistedQueriesTracer
+  def self.trace(key, data)
+    yield.tap do |result|
+      # Note: this tracer will get called for these persisted queries events as
+      # well as all events traced by the graphql-ruby gem.
+      case key
+      when "persisted_queries.fetch_query.cache_hit"
+        # data = { adapter: :redis }
+        # result = nil
+        # increment a counter metric to track cache hits
+      when "persisted_queries.fetch_query.cache_miss"
+        # data = { adapter: :redis }
+        # result = nil
+        # increment a counter metric to track cache misses
+      when "persisted_queries.save_query"
+        # data = { adapter: :redis }
+        # result = return value from method call
+        # increment a counter metric to track saved queries
+      end
+    end
+  end
+end
+```
+
+## Be aware of tracers-as-notifications
+
+A word of caution about the `cache_hit` and `cache_miss` events: they yield an empty block.  The `GraphQL::Tracing` feature typically wraps around the code performing the event.  The `save_query` event works this way, too -- the block that is yielded is essentially the `StoreAdapter#save` method.  This means you can add timing instrumentation for this call.  However, the `cache_hit` and `cache_miss` events are simply event notifications and do not wrap any code.  This means that they won't yield anything meaningful and they can't be timed.

data/lib/graphql/persisted_queries.rb

@@ -21,6 +21,8 @@ module GraphQL
       error_handler = options.delete(:error_handler) || :default
       schema.configure_persisted_query_error_handler(error_handler)
 
+      schema.persisted_queries_tracing_enabled = options.delete(:tracing)
+
       store = options.delete(:store) || :memory
       schema.configure_persisted_query_store(store, options)
     end

data/lib/graphql/persisted_queries/schema_patch.rb

@@ -16,9 +16,12 @@ module GraphQL
       end
 
       attr_reader :persisted_query_store, :hash_generator_proc, :persisted_query_error_handler
+      attr_writer :persisted_queries_tracing_enabled
 
       def configure_persisted_query_store(store, options)
-        @persisted_query_store = StoreAdapters.build(store, options)
+        @persisted_query_store = StoreAdapters.build(store, options).tap do |adapter|
+          adapter.tracers = tracers if persisted_queries_tracing_enabled?
+        end
       end
 
       def configure_persisted_query_error_handler(handler)
@@ -41,9 +44,22 @@ module GraphQL
         end
       end
 
+      def persisted_queries_tracing_enabled?
+        @persisted_queries_tracing_enabled
+      end
+
       def multiplex(queries, **kwargs)
         MultiplexResolver.new(self, queries, kwargs).resolve
       end
+
+      def tracer(name)
+        super.tap do
+          # Since tracers can be set before *and* after our plugin hooks in,
+          # we need to set tracers both when this plugin gets initialized
+          # and any time a tracer is added after initialization
+          persisted_query_store.tracers = tracers if persisted_queries_tracing_enabled?
+        end
+      end
     end
   end
 end

data/lib/graphql/persisted_queries/store_adapters/base_store_adapter.rb

@@ -5,15 +5,42 @@ module GraphQL
     module StoreAdapters
       # Base class for all store adapters
       class BaseStoreAdapter
-        def initialize(_options); end
+        include GraphQL::Tracing::Traceable
+        attr_writer :tracers
 
-        def fetch_query(_hash)
+        def initialize(_options)
+          @name = :base
+        end
+
+        def fetch_query(hash)
+          fetch(hash).tap do |result|
+            event = result ? "cache_hit" : "cache_miss"
+            trace("fetch_query.#{event}", adapter: @name)
+          end
+        end
+
+        def save_query(hash, query)
+          trace("save_query", adapter: @name) { save(hash, query) }
+        end
+
+        protected
+
+        def fetch(_hash)
           raise NotImplementedError
         end
 
-        def save_query(_hash, _query)
+        def save(_hash, _query)
           raise NotImplementedError
         end
+
+        def trace(key, metadata)
+          if @tracers
+            key = "persisted_queries.#{key}"
+            block_given? ? super : super {}
+          elsif block_given?
+            yield
+          end
+        end
       end
     end
   end

data/lib/graphql/persisted_queries/store_adapters/memcached_store_adapter.rb

@@ -14,13 +14,16 @@ module GraphQL
           @dalli_proc = build_dalli_proc(dalli_client)
           @expiration = expiration || DEFAULT_EXPIRATION
           @namespace = namespace || DEFAULT_NAMESPACE
+          @name = :memcached
         end
 
-        def fetch_query(hash)
+        protected
+
+        def fetch(hash)
           @dalli_proc.call { |dalli| dalli.get(key_for(hash)) }
         end
 
-        def save_query(hash, query)
+        def save(hash, query)
           @dalli_proc.call { |dalli| dalli.set(key_for(hash), query, @expiration) }
         end
 

data/lib/graphql/persisted_queries/store_adapters/memory_store_adapter.rb

@@ -7,13 +7,16 @@ module GraphQL
       class MemoryStoreAdapter < BaseStoreAdapter
         def initialize(_options)
           @storage = {}
+          @name = :memory
         end
 
-        def fetch_query(hash)
+        protected
+
+        def fetch(hash)
           @storage[hash]
         end
 
-        def save_query(hash, query)
+        def save(hash, query)
           @storage[hash] = query
         end
       end

data/lib/graphql/persisted_queries/store_adapters/redis_store_adapter.rb

@@ -14,13 +14,16 @@ module GraphQL
           @redis_proc = build_redis_proc(redis_client)
           @expiration = expiration || DEFAULT_EXPIRATION
           @namespace = namespace || DEFAULT_NAMESPACE
+          @name = :redis
         end
 
-        def fetch_query(hash)
+        protected
+
+        def fetch(hash)
           @redis_proc.call { |redis| redis.get(key_for(hash)) }
         end
 
-        def save_query(hash, query)
+        def save(hash, query)
           @redis_proc.call { |redis| redis.set(key_for(hash), query, ex: @expiration) }
         end
 

data/lib/graphql/persisted_queries/store_adapters/redis_with_local_cache_store_adapter.rb

@@ -19,9 +19,20 @@ module GraphQL
             namespace: namespace
           )
           @memory_adapter = memory_adapter_class.new(nil)
+          @name = :redis_with_local_cache
         end
 
-        def fetch_query(hash)
+        # We don't need to implement our own traces for this adapter since the
+        # underlying adapters will emit the proper events for us.  However,
+        # since tracers can be defined at any time, we need to pass them through.
+        def tracers=(tracers)
+          @memory_adapter.tracers = tracers
+          @redis_adapter.tracers = tracers
+        end
+
+        protected
+
+        def fetch(hash)
           result = @memory_adapter.fetch_query(hash)
           result ||= begin
             inner_result = @redis_adapter.fetch_query(hash)
@@ -31,7 +42,7 @@ module GraphQL
           result
         end
 
-        def save_query(hash, query)
+        def save(hash, query)
           @redis_adapter.save_query(hash, query)
           @memory_adapter.save_query(hash, query)
         end

data/lib/graphql/persisted_queries/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module PersistedQueries
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-persisted_queries
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - DmitryTsepelev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-02-26 00:00:00.000000000 Z
+date: 2020-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: graphql
@@ -125,6 +125,7 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/tracing.md
 - gemfiles/graphql_1_10.gemfile
 - gemfiles/graphql_1_8.gemfile
 - gemfiles/graphql_1_9.gemfile