Hive Client

Hive Client is a set of libraries and utilities for interacting with Hive, for both Schema Registry and Usage Reporting.

Available Clients

JavaScript / NodeJS Clients

Here’s a list of official libraries for JavaScript and NodeJS:

• @graphql-hive/yoga (npm, guide) - Integration with GraphQL Yoga.
• @graphql-hive/apollo (npm, guide) - Integration with Apollo Server.
• @graphql-hive/envelop (npm, guide) - Integration with Envelop.
• @graphql-hive/core (npm) - core library for interacting with Hive’s Schema Registry and Usage Reporting.

You can refer to the following guides for getting started within your project, then revisit this page for configuring the client to your needs.

Configuration

Refer to the HivePluginOptions interface for complete list of options and configurations you can pass to the Hive JavaScript Client of choice.

Client Information

By default, the client information is retrieved by looking up the x-graphql-client-name and x-graphql-client-version headers in the HTTP request. For operations executed via the GraphQL over WebSocket protocol, the client information is retrieved by looking for the client key within the connectionParams.

You can fully customize how to retrieve the client information by passing a custom clientInfo implementation.

You can pass a custom clientInfo callback to have full control on how you detect a client’s information.

useHive({
  usage: {
    clientInfo(context /* Your GraphQL execution context */) {
      const name = context?.headers?.['x-graphql-client-name']
      const version = context?.headers?.['x-graphql-client-version']
 
      if (name && version && typeof name === 'string' && typeof version === 'string') {
        return { name, version }
      }
 
      return null
    }
  }
})

The context object is the context object as used within the GraphQL execution. Depending on your server framework and GraphQL protocol, the context object may contain different properties.

We recommend to always try to safely decode the context.

Excluding Operations

You can pass a custom exclude array to the HivePluginOptions to ignore specific operations from being reported to Hive.

useHive({
  usage: {
    exclude: ['unwantedOperationName', 'anotherOperationName']
  }
})

Sampling

Basic sampling

With sampleRate option, you’re able to control the sampling rate of the usage reporting. Setting it to 0.5 will result in 50% of the operations being sent to Hive. There is no guarantee that every operation will be reported at least once (see atLeastOnceSampler).

Default: 1 (100%)

useHive({
  /* ... other options ... */,
  usage: {
    sampleRate: 0.6 // 60% of the operations will be sent to Hive
  }
})

Dynamic sampling

GraphQL Hive client accepts a function that returns a number between 0 and 1. This allows you to implement dynamic sampling based on the operation’s context.

If sampler is defined, sampleRate is ignored.

A sample rate between 0 and 1.

• 0.0 = 0% chance of being sent
• 1.0 = 100% chance of being sent.
• true = 100%
• false = 0%

The samplingContext object contains the following properties:

• operationName - The name of the operation.
• document - The operation AST.
• contextValue - The context value passed to the GraphQL execution.

useHive({
  /* ... other options ... */,
  usage: {
  sampler(samplingContext) {
      if (samplingContext.operationName === 'GetUser') {
        return 0.5 // 50% of GetUser operations will be sent to Hive
      }
 
      return 0.7; // 70% of the other operations will be sent to Hive
    }
  }
})

At-least-once sampling

If you want to make sure that every operation is reported at least once, you can use the atLeastOnceSampler. Every operation is reported at least once, but every next occurrence is decided by the sampler.

Both keyFn and sampler are required and receive the same samplingContext object.

The samplingContext object contains the following properties:

• operationName - The name of the operation.
• document - The operation AST.
• contextValue - The context value passed to the GraphQL execution.

import { createHive, atLeastOnceSampler} from '@graphql-hive/core';
 
const hive = createHive({
  /* ... other options ... */,
  usage: {
    sampler: atLeastOnceSampler({
      // Produces a unique key for a given GraphQL request.
      // This key is used to determine the uniqueness of a GraphQL operation.
      keyFn(samplingContext) {
        // Operation name is a good candidate for a key, but not perfect,
        // as not all operations have names
        // and some operations may have the same name but different body.
        return samplingContext.operationName;
      },
      sampler(samplingContext) {
        // Use the context to decide if the operation should be sent to Hive.
        if (samplingContext.contextValue.headers.get('x-graphql-client-name') === 'WebApp') {
          return 1; // 100% of the operations from WebApp will be sent to Hive
        }
 
        const hour = new Date().getHours();
 
        if (hour >= 9 && hour <= 17) {
          return 0.3;
        }
 
        return 0.8;
      }
    })
  }
})

Custom Integration

If your GraphQL server is not listed above, you can implement a custom integration. Start by importing and creating a Hive instance using the createHive function.

import { createHive } from '@graphql-hive/core'
 
const hive = createHive({
  enabled: true,
  debug: true, // or, false
  token: 'YOUR-TOKEN'
})

Call collectUsage as soon as a GraphQL operation execution starts, and use the return value callback when the operation ends. You may also wrap and replace the execute function with the following:

export async function executeWithHive(args: ExecutionArgs): Promise<ExecutionResult> {
  // args is ExecutionArgs of graphql-js
  const finish = hive.collectUsage(args)
  // result is ExecutionResult of graphql-js
  const result = await execute(args)
  // Use this callback to finish measuring times, and save the operation report
  finish(result)
 
  return result
}

Ruby Client

The graphql-hive gem allows GraphQL-Ruby users to use Hive for usage reporting.

Refer to the following guides for integration with your project:

PHP Client

The Lighthouse Hive is third-party integration can be used to measure and collect data against all your GraphQL operations.

Rust Client

Refer to the following guides for integration with your Rust project: