graphql-analyzer

GraphQL::Analyzer

GraphQL Analyzer is a GraphQL extension for tracking datastore queries.

Installation

Add this line to your application's Gemfile:

gem 'graphql-analyzer'

And then execute:

$ bundle

Or install it yourself as:

$ gem install graphql-analyzer

Usage

Add an instance of GraphQL::Analyzer to your schema, instantiate it with a list of instrumentations to capture different datastore queries.

Analyzer

Add 'GraphQL::Analyzer' to your schema:

require 'graphql/analyzer'

Schema = GraphQL::Schema.define do
  query QueryType
  use(
      GraphQL::Analyzer.new(
        GraphQL::Analyzer::Instrumentation::Mysql.new,
        GraphQL::Analyzer::Instrumentation::Postgresql.new
      )
  )
end

Response Format

The GraphQL specification allows servers to include additional information as part of the response under an extensions key:

The response map may also contain an entry with key extensions. This entry, if set, must have a map as its value. This entry is reserved for implementors to extend the protocol however they see fit, and hence there are no additional restrictions on its contents.

GraphQL Analyzer exposes datastore query data for an individual request under a analyzer key in extensions:

{
  "data": <>,
  "errors": <>,
  "extensions": {
    "analyzer": {
      "version": 1,
      "execution": {
        "resolvers": [
          {
            "path": [
              "node"
            ],
            "adapter": "sqlite3",
            "parentType": "Query",
            "fieldName": "node",
            "returnType": "Node",
            "details": {
              "root": "EXPLAIN for: SELECT  \"users\".* FROM \"users\" WHERE \"users\".\"id\" = ? LIMIT ? [[\"id\", 7], [\"LIMIT\", 1]",
              "explained_queries": [
                {
                  "select_id": "0",
                  "order": "0",
                  "from": "0",
                  "details": "SEARCH TABLE users USING INTEGER PRIMARY KEY (rowid=?)"
                }
              ]
            }
          }
        ]
      }
    }
  }
}

Instrumentation

There are some common instruments already implemented that should work right away.

• Sqlite3
• Mysql
• Postgresql

Check lib/graphql/analyzer/instrumentation for the full list.

To write your own custom instrumentation, your object needs to respond to #instrument(type, field) and return a lambda that accepts three parameters, object, arguments, and context, and returns the original field value. It should also add any queries captured to the context.

module GraphQL
  class Analyzer
    module Instrumentation
      class MyCustomInstrumentation < Base
        def instrument(type, field)
          ->(obj, args, ctx) do
            ### OMITTED ###
              ctx['graphql-analyzer']['resolvers'] << {
                'adapter' => 'My Custom Adapter',
                'path' => ctx.path,
                'parentType' => type.name,
                'fieldName' => field.name,
                'returnType' => field.type.to_s,
                'details' => 'My Adapter Specific Information'
              }
              ### OMITTED ###
          end
        end
      end
    end
  end
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/GraphQL-Query-Planner/graphql-analyzer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.