GraphQL Hive: graphql-ruby integration

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.

Organization-level tokens

If you are using an organization-level access token (tokens starting with hvo1/), you must also provide a target parameter to specify which target the usage data should be reported to. See the organization access tokens documentation for more details.

1. Install the graphql-hive gem

gem install graphql-hive

2. Configure GraphQL::Hive in your Schema

Add GraphQL::Hive at the end of your schema definition:

class Schema < GraphQL::Schema
  query QueryType

  use(
      GraphQL::Hive,
      {
        token: '<YOUR_TOKEN>',
        # target is only needed if you're using an organization level token
        target: 'your-org/your-project/production', # or target UUID
        reporting: {
          author: ENV['GITHUB_USER'],
          commit: ENV['GITHUB_COMMIT']
        },
      }
  )
end

The reporting configuration is required to push your GraphQL Schema to the Hive registry. Doing so will help better detect breaking changes and more upcoming features. If you only want to use the operations monitoring, replace the reporting option with the following report_schema: false.

3. (Optional) Configure Lifecycle Hooks

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

on_start

Call this hook if you are running GraphQL::Hive in a process that forks itself.

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

# config/puma.rb
preload_app!

on_worker_boot do
  GraphQL::Hive.instance.on_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
  GraphQL::Hive.instance.on_exit
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

4. See how your GraphQL API is operating

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

5. 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 GraphQL::Hive:

class MySchema < GraphQL::Schema
  use(
    GraphQL::Hive,
    {
      # Token is the only required configuration value.
      token: 'YOUR-REGISTRY-TOKEN',
      # Target is required when using organization-level tokens (tokens starting with 'hvo1/').
      # Can be a target slug (e.g., 'org/project/target') or target UUID.
      target: 'your-org/your-project/production',
      #
      # The following are optional configuration values.
      #
      # Enable/disable Hive Client.
      enabled: true,
      # Verbose logs.
      debug: false,
      # A custom logger.
      logger: MyLogger.new,
      # Log request details at info level (default: false, logs at debug level). Details include request type, request path, and a unique request ID.
      log_request_details: false,
      # Log Hive errors (unsuccessful responses and exceptions) as warnings instead of errors (default: false, logs as errors).
      warn_on_hive_errors: false,
      # Endpoint and port of the Hive API. Change this if you are using a self-hosted Hive instance.
      endpoint: 'app.graphql-hive.com',
      port: 80,
      # Number of operations sent to Hive in a batch (AFTER sampling).
      buffer_size: 50,
      # Size of the queue used to send operations to the buffer before sampling.
      queue_size: 1000,
      # Report usage to Hive.
      collect_usage: true,
      # Usage sampling configurations.
      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 }
      },
      # Publish schema to Hive.
      report_schema: true,
      # Mandatory if `report_schema: true`.
      reporting: {
        # Mandatory members of `reporting`.
        author: 'Author of the latest change',
        commit: 'git sha or any identifier',
        # Optional members of `reporting`.
        service_name: '',
        service_url: '',
      },

      # Pass an optional proc to client_info to help identify the client (ex: Apollo web app) that performed the query.
      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.