Skip to content

rperryng/graphql-ruby-hive

Repository files navigation

GraphQL Hive: graphql-ruby integration

CI Suite Gem Version

GraphQL Hive

GraphQL Hive provides all the tools to get visibility of your GraphQL architecture at all stages, from standalone APIs to composed schemas (Federation, Stitching):

  • Schema Registry with custom breaking changes detection
  • Monitoring of RPM, latency, error rate, and more
  • Integrations with your favorite tools (Slack, Github Actions, and more)

Getting started

0. Get your Hive token

If you are using Hive as a service, please refer to our documentation: https://docs.graphql-hive.com/features/tokens.

1. Install the graphql-hive gem

gem install graphql-hive

2. Configure GraphQLHive in your Schema

Add GraphQLHive at the end of your schema definition:

# app/initializers/graphql_hive.rb
GraphQLHive.configure do |config|
  config.token = '<YOUR_TOKEN>'
end

# schema.rb
class Schema < GraphQL::Schema
  query QueryType

  trace_with(GraphQLHive::Tracer)
end

3. (Optional) Report your schema to Hive

If you want to report your schema to Hive, you can do so by calling the report_schema_to_hive method. You can call this method in the initializer file or in CI.

# app/initializers/graphql_hive.rb
GraphQLHive.report_schema_to_hive(
  schema: Schema,
  options: {
    # Required
    author: ENV['GITHUB_USER'],
    commit: ENV['GITHUB_COMMIT'],
    # Optional
    service: ENV['GRAPHQL_HIVE_SERVICE_NAME'],
    url: ENV['GRAPHQL_HIVE_SERVICE_URL'],
    force: ENV['GRAPHQL_HIVE_FORCE_REPORT']
  }
)

4. (Optional) Configure Lifecycle Hooks

Calling these hooks are situational - it's likely that you may not need to call them at all!

start

Call this hook if you are running GraphQLHive in a process that forks itself.

example: puma web server running in ("clustered mode")

# config/puma.rb
preload_app!

on_worker_boot do
  GraphQLHive.start
end

on_exit

If your GraphQL API process is shut down non-gracefully but has a shutdown hook to call into, call on_worker_exit.

puma example:

# config/puma.rb

on_worker_shutdown do
  GraphQLHive.stop
end

You are all set! 🚀

When deploying or starting up your GraphQL API, graphql-hive will immediately:

  • publish the schema to the Hive registry
  • forward the operations metrics to Hive

5. See how your GraphQL API is operating

You should now see operations information (RPM, error rate, queries performed) on your GraphQL Hive dashboard:

GraphQL Hive

6. Going further: use the Hive Github app

Stay on top of your GraphQL Schema changes by installing the Hive Github Application and enabling Slack notifications about breaking changes:

https://docs.graphql-hive.com/features/integrations#github


Configuration

You will find below the complete list of options of GraphQLHive:

# app/initializers/graphql_hive.rb
GraphQLHive.configure do |config|
  # Token is the only required configuration value.
  config.token = 'YOUR-REGISTRY-TOKEN'
  
  # The following are optional configuration values.
  
  # Enable/disable Hive Client.
  config.enabled = true
  # Verbose logs.
  config.debug = false
  # A custom logger.
  config.logger = MyLogger.new
  # Endpoint and port of the Hive API. Change this if you are using a self-hosted Hive instance.
  config.endpoint = 'app.graphql-hive.com'
  config.port = 80
  # Number of operations sent to Hive in a batch (AFTER sampling).
  config.buffer_size = 50
  # Size of the queue used to send operations to the buffer before sampling.
  config.queue_size = 1000
  # Report usage to Hive.
  config.collect_usage = true
  # Usage sampling configurations.
  config.collect_usage_sampling = {
    # % of operations recorded.
    sample_rate: 0.5,
    # Custom sampler to assign custom sampling rates.
    sampler: proc { |context| context.operation_name.includes?('someQuery') 1 : 0.5 },
    # Sample every distinct operation at least once.
    at_least_once: true,
    # Assign custom keys to distinguish between distinct operations.
    key_generator: proc { |context| context.operation_name }
  }

  # Pass an optional proc to client_info to help identify the client (ex: Apollo web app) that performed the query.
  config.client_info = proc { |context|
    { name: context.client_name, version: context.client_version }
  }
end

See default options for the optional parameters here.

Important

buffer_size and queue_size will affect memory consumption.

buffer_size is the number of operations sent to Hive in a batch after operations have been sampled. queue_size is the size of the queue used to send operations to the buffer before sampling. Adjust these values according to your application's memory constraints and throughput. High throughput applications will need a larger queue_size.

About

GraphQL Hive integration for `graphql-ruby`

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages