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 Client
@graphql-hive/client
(opens in a new tab) is the official 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 (opens in a new tab)
for complete list of options and configurations you can pass to the Hive JavaScript Client.
Client Information
You can pass a custom clientInfo
callback to the HivePluginOptions
to have full control on how
you detect a client's information.
const config: HivePluginOptions = {
usage: {
clientInfo(context) {
const name = context.headers['x-graphql-client-name']
const version = context.headers['x-graphql-client-version']
if (name && version) {
return { name, version }
}
return null
}
}
}
Excluding Operations
You can pass a custom exclude
array to the HivePluginOptions
to ignore specific operations from
being reported to Hive.
const config: HivePluginOptions = {
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 sent1.0
= 100% chance of being sent.true
= 100%false
= 0%
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.
import { useHive, atLeastOnceSampler} from '@graphql-hive/client';
useHive({
/* ... 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) {
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/client'
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 (opens in a new tab) allows
GraphQL-Ruby (opens in a new tab) users to use Hive for usage reporting.
Refer to the following guides for integration with your project:
PHP Client
The Lighthouse Hive (opens in a new tab) 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: