• Stars
    star
    157
  • Rank 229,783 (Top 5 %)
  • Language
    Ruby
  • License
    MIT License
  • Created almost 6 years ago
  • Updated 11 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Extract as much much detail as you want from GraphQL queries, served up from your Ruby app and the graphql gem.

GraphQL Metrics

Extract as much detail as you want from GraphQL queries, served up from your Ruby app and the graphql gem. Compatible with the graphql-batch gem, to extract batch-loaded fields resolution timings.

Be sure to read the CHANGELOG to stay updated on feature additions, breaking changes made to this gem.

NOTE: Not tested with graphql-ruby's multiplexing feature. Metrics may not be accurate if you execute multiple operations at once.

Installation

Add this line to your application's Gemfile:

gem 'graphql-metrics'

You can require it with in your code as needed with:

require 'graphql/metrics'

Or globally in the Gemfile with:

gem 'graphql-metrics', require: 'graphql/metrics'

And then execute:

$ bundle

Or install it yourself as:

$ gem install graphql-metrics

Usage

Get started by defining your own Analyzer, inheriting from GraphQL::Metrics::Analyzer.

The following analyzer demonstrates a simple way to capture commonly used metrics sourced from key parts of your schema definition, the query document being served, as well as runtime query and resolver timings. In this toy example, all of this data is simply stored on the GraphQL::Query context, under a namespace to avoid collisions with other analyzers etc.

What you do with these captured metrics is up to you!

NOTE: If any non-graphql-ruby gem-related exceptions occur in your application during query document parsing and validation, runtime metrics for queries (like query_duration, parsing_start_time_offset etc.) as well as field resolver timings (like resolver_timings, lazy_resolver_timings) may not be present in the extracted metrics hash, even if you opt to collect them by using GraphQL::Metrics::Analyzer and GraphQL::Metrics::Tracer.

Define your own analyzer subclass

  class SimpleAnalyzer < GraphQL::Metrics::Analyzer
    ANALYZER_NAMESPACE = :simple_analyzer_namespace

    def initialize(query_or_multiplex)
      super

      # `query` is defined on instances of objects inheriting from GraphQL::Metrics::Analyzer
      ns = query.context.namespace(ANALYZER_NAMESPACE)
      ns[:simple_extractor_results] = {}
    end

    # @param metrics [Hash] Query metrics, including a few details about the query document itself, as well as runtime
    # timings metrics, intended to be compatible with the Apollo Tracing spec:
    # https://github.com/apollographql/apollo-tracing#response-format
    #
    # {
    #   operation_type: "query",
    #   operation_name: "PostDetails",
    #   query_start_time: 1573833076.027327,
    #   query_duration: 2.0207119999686256,
    #   lexing_start_time_offset: 0.0010339999571442604,
    #   lexing_duration: 0.0008190000080503523,
    #   parsing_start_time_offset: 0.0010339999571442604,
    #   parsing_duration: 0.0008190000080503523,
    #   validation_start_time_offset: 0.0030819999519735575,
    #   validation_duration: 0.01704599999357015,
    #   analysis_start_time_offset: 0.0010339999571442604,
    #   analysis_duration: 0.0008190000080503523,
    #   multiplex_start_time: 0.0008190000080503523,
    # }
    #
    # You can use these metrics to track high-level query performance, along with any other details you wish to
    # manually capture from `query` and/or `query.context`.
    def query_extracted(metrics)
      custom_metrics_from_context = {
        request_id: query.context[:request_id],
        # ...
      }

      # You can make use of captured metrics here (logging to Kafka, request logging etc.)
      # log_metrics(:fields, metrics)
      #
      # Or store them on the query context:
      store_metrics(:queries, metrics.merge(custom_metrics_from_context))
    end

    # For use after controller:
    # class GraphQLController < ActionController::Base
    #   def graphql_query
    #     query_result = graphql_query.result.to_h
    #     do_something_with_metrics(query.context[:simple_extractor_results])
    #     render json: graphql_query.result
    #   end
    # end

    # @param metrics [Hash] Field selection metrics, including resolver timings metrics, also adhering to the Apollo
    # Tracing spec referred to above.
    #
    # `resolver_timings` is populated any time a field is resolved (which may be many times, if the field is nested
    # within a list field e.g. a Relay connection field).
    #
    # `lazy_resolver_timings` is only populated by fields that are resolved lazily (for example using the
    # graphql-batch gem) or that are otherwise resolved with a Promise. Any time spent in the field's resolver to
    # prepare work to be done "later" in a Promise, or batch loader will be captured in `resolver_timings`. The time
    # spent actually doing lazy field loading, including time spent within a batch loader can be obtained from
    # `lazy_resolver_timings`.
    #
    # {
    #   field_name: "id",
    #   return_type_name: "ID",
    #   parent_type_name: "Post",
    #   deprecated: false,
    #   path: ["post", "id"],
    #   resolver_timings: [
    #     start_time_offset: 0.011901999998372048,
    #     duration: 5.999987479299307e-06
    #   ],
    #   lazy_resolver_timings: [
    #     start_time_offset: 0.031901999998372048,
    #     duration: 5.999987479299307e-06
    #   ],
    # }
    def field_extracted(metrics)
      store_metrics(:fields, metrics)
    end

    # @param metrics [Hash] Directive metrics
    # {
    #   directive_name: "customDirective",
    # }
    def directive_extracted(metrics)
      store_metrics(:directives, metrics)
    end

    # @param metrics [Hash] Argument usage metrics, including a few details about the query document itself, as well
    # as resolver timings metrics, also ahering to the Apollo Tracing spec referred to above.
    # {
    #   argument_name: "ids",
    #   argument_type_name: "ID",
    #   parent_name: "comments",
    #   grandparent_type_name: "Post",
    #   grandparent_node_name: "post",
    #   default_used: false,
    #   value_is_null: false,
    #   value: <GraphQL::Query::Arguments::ArgumentValue>,
    # }
    #
    # `value` is exposed here, in case you want to get access to the argument's definition, including the type
    # class which defines it, e.g. `metrics[:value].definition.metadata[:type_class]`
    def argument_extracted(metrics)
      store_metrics(:arguments, metrics)
    end

    private

    def store_metrics(context_key, metrics)
      ns = query.context.namespace(ANALYZER_NAMESPACE)
      ns[:simple_extractor_results][context_key] ||= []
      ns[:simple_extractor_results][context_key] << metrics
    end
  end

Once defined, you can opt into capturing all metrics seen above by simply including GraphQL::Metrics as a plugin on your schema.

Metrics that are captured for arguments for fields and directives

Let's have a query example

query PostDetails($postId: ID!, $commentsTags: [String!] = null, $val: Int!) @customDirective(val: $val) {
  post(id: $postId) {
    title @skip(if: true)
    comments(ids: [1, 2], tags: $commentsTags) {
      id
      body
    }
  }
}

These are some of the arguments that are extracted

{
  argument_name: "if",                    # argument name
  argument_type_name: "Boolean",          # argument type
  parent_name: "skip",                    # argument belongs to `skip` directive
  grandparent_type_name: "__Directive",   # argument was applied to directive
  grandparent_node_name: "title",         # directive was applied to field title
  default_used: false,                    # check if default value was used
  value_is_null: false,                   # check if value was null
  value: <GraphQL::Execution::Interpreter::ArgumentValue>
}, {
  argument_name: "id",
  argument_name: "ids",
  argument_type_name: "ID",
  parent_name: "comments",                # name of the node that argument was applied to
  grandparent_type_name: "Post",          # grandparent node to uniquely identify which node the argument was applied to
  grandparent_node_name: "post",          # name of grandparend node
  default_used: false,
  value_is_null: false,
  value: <GraphQL::Execution::Interpreter::ArgumentValue>
}, {
  argument_name: "id",
  argument_type_name: "ID",
  parent_name: "post",                   # argument applied to post field
  grandparent_type_name: "QueryRoot",    # post is a QueryRoot
  grandparent_node_name: "query",        # post field is already in the query root
  parent_input_object_type: nil,
  default_used: false,
  value_is_null: false,
  value: <GraphQL::Execution::Interpreter::ArgumentValue>
}, {
  argument_name: "val",
  argument_type_name: "Int",
  parent_name: "customDirective",        # argument belongs to `customDirective` directive
  grandparent_type_name: "__Directive",  # argument was applied to directive
  grandparent_node_name: "query",        # directive was applied to query
  parent_input_object_type: nil,
  default_used: false,
  value_is_null: false,
  value: <GraphQL::Execution::Interpreter::ArgumentValue>
}

Make use of your analyzer

Ensure that your schema is using the graphql-ruby 1.9+ GraphQL::Execution::Interpreter and GraphQL::Analysis::AST engine, and then simply add the below GraphQL::Metrics plugins.

This opts you in to capturing all static and runtime metrics seen above.

class Schema < GraphQL::Schema
  query QueryRoot
  mutation MutationRoot

  query_analyzer SimpleAnalyzer

  instrument :query, GraphQL::Metrics::Instrumentation.new # Both of these are required if either is used.
  tracer GraphQL::Metrics::Tracer.new                      # <-- Note!

  use GraphQL::Batch # Optional, but highly recommended. See https://github.com/Shopify/graphql-batch/.
end

Optionally, only gather static metrics

If you don't care to capture runtime metrics like query and resolver timings, you can use your analyzer a standalone analyzer without GraphQL::Metrics::Instrumentation and tracer GraphQL::Metrics::Tracer, like so:

class Schema < GraphQL::Schema
  query QueryRoot
  mutation MutationRoot

  query_analyzer SimpleAnalyzer
end

Your analyzer will still be called with query_extracted, field_extracted, but with timings metrics omitted. argument_extracted will work exactly the same, whether instrumentation and tracing are used or not.

Order of execution

Because of the structure of graphql-ruby's plugin architecture, it may be difficult to build an intuition around the order in which methods defined on GraphQL::Metrics::Instrumentation, GraphQL::Metrics::Tracer and subclasses of GraphQL::Metrics::Analyzer run.

Although you ideally will not need to care about these details if you are simply using this gem to gather metrics in your application as intended, here's a breakdown of the order of execution of the methods involved:

When used as instrumentation, an analyzer and tracing, the order of execution is usually:

  • Tracer.capture_multiplex_start_time
  • Tracer.capture_lexing_time
  • Tracer.capture_parsing_time
  • Instrumentation.before_query (context setup)
  • Tracer.capture_validation_time
  • Tracer.capture_analysis_time
  • Analyzer#initialize (bit more context setup, instance vars setup)
  • Analyzer#result
  • Tracer.capture_query_start_time
  • Tracer.trace_field (n times)
  • Instrumentation.after_query (call query and field callbacks, now that we have all static and runtime metrics gathered)
  • Analyzer#extract_query
  • Analyzer#query_extracted
  • Analyzer#extract_fields_with_runtime_metrics
    • calls Analyzer#field_extracted n times

When used as a simple analyzer, which doesn't gather or emit any runtime metrics (timings, arg values):

  • Analyzer#initialize
  • Analyzer#field_extracted n times
  • Analyzer#result
  • Analyzer#extract_query
  • Analyzer#query_extracted

Development

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

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Shopify/graphql-metrics. 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.

Code of Conduct

Everyone interacting in the GraphQL::Metrics project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

More Repositories

1

draggable

The JavaScript Drag & Drop library your grandparents warned you about.
JavaScript
17,454
star
2

dashing

The exceptionally handsome dashboard framework in Ruby and Coffeescript.
JavaScript
11,025
star
3

liquid

Liquid markup language. Safe, customer facing template language for flexible web apps.
Ruby
10,419
star
4

toxiproxy

⏰ 🔥 A TCP proxy to simulate network and system conditions for chaos and resiliency testing
Go
9,412
star
5

react-native-skia

High-performance React Native Graphics using Skia
TypeScript
6,392
star
6

polaris

Shopify’s design system to help us work together to build a great experience for all of our merchants.
TypeScript
5,352
star
7

flash-list

A better list for React Native
TypeScript
4,536
star
8

hydrogen-v1

React-based framework for building dynamic, Shopify-powered custom storefronts.
TypeScript
3,760
star
9

go-lua

A Lua VM in Go
Go
2,773
star
10

bootsnap

Boot large Ruby/Rails apps faster
Ruby
2,614
star
11

graphql-design-tutorial

2,335
star
12

restyle

A type-enforced system for building UI components in React Native with TypeScript.
TypeScript
2,331
star
13

dawn

Shopify's first source available reference theme, with Online Store 2.0 features and performance built-in.
Liquid
2,279
star
14

identity_cache

IdentityCache is a blob level caching solution to plug into Active Record. Don't #find, #fetch!
Ruby
1,874
star
15

shopify_app

A Rails Engine for building Shopify Apps
Ruby
1,649
star
16

kubeaudit

kubeaudit helps you audit your Kubernetes clusters against common security controls
Go
1,624
star
17

quilt

A loosely related set of packages for JavaScript/TypeScript projects at Shopify
TypeScript
1,570
star
18

graphql-batch

A query batching executor for the graphql gem
Ruby
1,388
star
19

shipit-engine

Deployment coordination
Ruby
1,382
star
20

packwerk

Good things come in small packages.
Ruby
1,346
star
21

krane

A command-line tool that helps you ship changes to a Kubernetes namespace and understand the result
Ruby
1,309
star
22

semian

🐒 Resiliency toolkit for Ruby for failing fast
Ruby
1,286
star
23

slate

Slate is a toolkit for developing Shopify themes. It's designed to assist your workflow and speed up the process of developing, testing, and deploying themes.
JavaScript
1,281
star
24

ejson

EJSON is a small library to manage encrypted secrets using asymmetric encryption.
Go
1,246
star
25

superdb

The Super Debugger, a realtime wireless debugger for iOS
Objective-C
1,158
star
26

shopify_python_api

ShopifyAPI library allows Python developers to programmatically access the admin section of stores
Python
1,072
star
27

storefront-api-examples

Example custom storefront applications built on Shopify's Storefront API
JavaScript
1,069
star
28

themekit

Shopify theme development command line tool.
Go
1,068
star
29

Timber

The ultimate Shopify theme framework, built by Shopify.
Liquid
992
star
30

shopify-cli

Shopify CLI helps you build against the Shopify platform faster.
Ruby
987
star
31

shopify-api-ruby

ShopifyAPI is a lightweight gem for accessing the Shopify admin REST and GraphQL web services.
Ruby
982
star
32

hydrogen

Hydrogen is Shopify’s stack for headless commerce. It provides a set of tools, utilities, and best-in-class examples for building dynamic and performant commerce applications. Hydrogen is designed to dovetail with Remix, Shopify’s full stack web framework, but it also provides a React library portable to other supporting frameworks. Demo store 👇🏼
TypeScript
966
star
33

js-buy-sdk

The JS Buy SDK is a lightweight library that allows you to build ecommerce into any website. It is based on Shopify's API and provides the ability to retrieve products and collections from your shop, add products to a cart, and checkout.
JavaScript
932
star
34

job-iteration

Makes your background jobs interruptible and resumable by design.
Ruby
907
star
35

cli-ui

Terminal user interface library
Ruby
869
star
36

ruby-lsp

An opinionated language server for Ruby
Ruby
851
star
37

react-native-performance

Performance monitoring for React Native apps
TypeScript
843
star
38

active_shipping

ActiveShipping is a simple shipping abstraction library extracted from Shopify
Ruby
809
star
39

shopify-api-js

Shopify Admin API Library for Node. Accelerate development with support for authentication, graphql proxy, webhooks
TypeScript
765
star
40

maintenance_tasks

A Rails engine for queueing and managing data migrations.
Ruby
705
star
41

shopify-app-template-node

JavaScript
701
star
42

remote-ui

TypeScript
701
star
43

shopify_theme

A console tool for interacting with Shopify Theme Assets.
Ruby
640
star
44

tapioca

The swiss army knife of RBI generation
Ruby
636
star
45

pitchfork

Ruby
630
star
46

ghostferry

The swiss army knife of live data migrations
Go
596
star
47

yjit

Optimizing JIT compiler built inside CRuby
593
star
48

erb-lint

Lint your ERB or HTML files
Ruby
565
star
49

statsd-instrument

A StatsD client for Ruby apps. Provides metaprogramming methods to inject StatsD instrumentation into your code.
Ruby
546
star
50

shopify.github.com

A collection of the open source projects by Shopify
CSS
505
star
51

theme-scripts

Theme Scripts is a collection of utility libraries which help theme developers with problems unique to Shopify Themes.
JavaScript
470
star
52

livedata-ktx

Kotlin extension for LiveData, chaining like RxJava
Kotlin
467
star
53

starter-theme

The Shopify Themes Team opinionated starting point for new a Slate project
Liquid
459
star
54

ruby-style-guide

Shopify’s Ruby Style Guide
Ruby
446
star
55

shopify-demo-app-node-react

JavaScript
444
star
56

web-configs

Common configurations for building web apps at Shopify
JavaScript
433
star
57

mobile-buy-sdk-ios

Shopify’s Mobile Buy SDK makes it simple to sell physical products inside your mobile app. With a few lines of code, you can connect your app with the Shopify platform and let your users buy your products using Apple Pay or their credit card.
Swift
433
star
58

shopify_django_app

Get a Shopify app up and running with Django and Python Shopify API
Python
425
star
59

deprecation_toolkit

⚒Eliminate deprecations from your codebase ⚒
Ruby
390
star
60

ruby-lsp-rails

A Ruby LSP extension for Rails
Ruby
388
star
61

bootboot

Dualboot your Ruby app made easy
Ruby
374
star
62

FunctionalTableData

Declarative UITableViewDataSource implementation
Swift
365
star
63

shadowenv

reversible directory-local environment variable manipulations
Rust
349
star
64

shopify-node-app

An example app that uses Polaris components and shopify-express
JavaScript
327
star
65

better-html

Better HTML for Rails
Ruby
311
star
66

theme-check

The Ultimate Shopify Theme Linter
Ruby
306
star
67

product-reviews-sample-app

A sample Shopify application that creates and stores product reviews for a store, written in Node.js
JavaScript
300
star
68

tracky

The easiest way to do motion tracking!
Swift
295
star
69

shopify-api-php

PHP
279
star
70

polaris-viz

A collection of React and React native components that compose Shopify's data visualization system
TypeScript
279
star
71

measured

Encapsulate measurements and their units in Ruby.
Ruby
275
star
72

cli

Build apps, themes, and hydrogen storefronts for Shopify
TypeScript
273
star
73

money

Manage money in Shopify with a class that won't lose pennies during division
Ruby
265
star
74

javascript

The home for all things JavaScript at Shopify.
254
star
75

ruvy

Rust
252
star
76

limiter

Simple Ruby rate limiting mechanism.
Ruby
244
star
77

vscode-ruby-lsp

VS Code plugin for connecting with the Ruby LSP
TypeScript
232
star
78

polaris-tokens

Design tokens for Polaris, Shopify’s design system
TypeScript
230
star
79

buy-button-js

BuyButton.js is a highly customizable UI library for adding ecommerce functionality to any website.
JavaScript
230
star
80

android-testify

Add screenshots to your Android tests
Kotlin
225
star
81

turbograft

Hard fork of turbolinks, adding partial page replacement strategies, and utilities.
JavaScript
213
star
82

mobile-buy-sdk-android

Shopify’s Mobile Buy SDK makes it simple to sell physical products inside your mobile app. With a few lines of code, you can connect your app with the Shopify platform and let your users buy your products using their credit card.
Java
202
star
83

spoom

Useful tools for Sorbet enthusiasts
Ruby
192
star
84

graphql-js-client

A Relay compliant GraphQL client.
JavaScript
187
star
85

ruby_memcheck

Use Valgrind memcheck on your native gem without going crazy
Ruby
187
star
86

shopify-app-template-php

PHP
186
star
87

skeleton-theme

A barebones ☠️starter theme with the required files needed to compile with Slate and upload to Shopify.
Liquid
185
star
88

sprockets-commoner

Use Babel in Sprockets to compile JavaScript modules for the browser
Ruby
182
star
89

rotoscope

High-performance logger of Ruby method invocations
Ruby
180
star
90

shopify-app-template-remix

TypeScript
178
star
91

git-chain

Tool to rebase multiple Git branches based on the previous one.
Ruby
176
star
92

verdict

Framework to define and implement A/B tests in your application, and collect data for analysis purposes.
Ruby
176
star
93

hydrogen-react

Reusable components and utilities for building Shopify-powered custom storefronts.
TypeScript
174
star
94

ui-extensions

TypeScript
173
star
95

storefront-api-learning-kit

JavaScript
171
star
96

heap-profiler

Ruby heap profiler
C++
159
star
97

autoload_reloader

Experimental implementation of code reloading using Ruby's autoload
Ruby
158
star
98

app_profiler

Collect performance profiles for your Rails application.
Ruby
157
star
99

active_fulfillment

Active Merchant library for integration with order fulfillment services
Ruby
155
star
100

ci-queue

Distribute tests over many workers using a queue
Ruby
148
star