diff --git a/packages/libraries/core/src/client/agent.ts b/packages/libraries/core/src/client/agent.ts index 459939289e3..481fe024e7b 100644 --- a/packages/libraries/core/src/client/agent.ts +++ b/packages/libraries/core/src/client/agent.ts @@ -54,10 +54,6 @@ export interface AgentOptions { * 5 by default */ maxRetries?: number; - /** - * 200 by default - */ - minTimeout?: number; /** * Send reports in interval (defaults to 10_000ms) */ @@ -82,6 +78,8 @@ export interface AgentOptions { * object -> use custom configuration see {AgentCircuitBreakerConfiguration} */ circuitBreaker?: boolean | AgentCircuitBreakerConfiguration; + /** @deprecated This is no longer used. */ + minTimeout?: number; } export function createAgent( diff --git a/packages/web/docs/src/content/api-reference/client.mdx b/packages/web/docs/src/content/api-reference/client.mdx index 65ef23956f1..b323d2abe82 100644 --- a/packages/web/docs/src/content/api-reference/client.mdx +++ b/packages/web/docs/src/content/api-reference/client.mdx @@ -49,7 +49,9 @@ Refer to the for complete list of options and configurations you can pass to the Hive JavaScript Client of choice. -#### Client Information +#### Usage reporting + +##### 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 @@ -82,9 +84,9 @@ useHive({ 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. +We recommend to safely decode the context in order to avoid runtime errors. -#### Excluding Operations +##### Excluding Operations You can pass a custom `exclude` array to the `HivePluginOptions` to ignore specific operations from being reported to Hive. @@ -97,9 +99,9 @@ useHive({ }) ``` -#### Sampling +##### Sampling -##### Basic 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 @@ -116,7 +118,7 @@ useHive({ }) ``` -##### Dynamic sampling +###### 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. @@ -151,7 +153,7 @@ useHive({ }) ``` -##### At-least-once sampling +###### 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 @@ -321,6 +323,75 @@ useHive({ +##### Agent + +The agent collects and schedules usage reporting call to the Hive Console usage reporting service. +The configuration can be customized. + +###### `maxRetries` + +- Type: `number` +- Default: `3` + +Configure the maximum amount of retries per usage reporting batch before dropping the reporting +attempts. + +###### `maxSize` + +- Type: `number` +- Default: `25` + +The maximum batch size of usage reports before sending the batch. + +###### `sendInterval` + +- Type: `number` +- Default: `10_000` + +The amount of time after which a pending usage reporting batch should be sent in case before the +`maxSize` amount is reached. + +###### `fetch` + +- Type: [`Fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) +- Default: `fetch` + +Provide a custom WHATWG `fetch` implementation + +###### `logger` + +- Type: [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console) +- Default: `globalThis.console` + +Console object to use for logging info, errors and debug information. + +###### `circuitBreaker` + +- Type: `AgentCircuitBreakerConfiguration` +- Default: + ```js + { + /** + * Percentage after what the circuit breaker should kick in. + * Default: 50 + */ + errorThresholdPercentage: 50, + /** + * Count of requests before starting evaluating. + * Default: 10 + */ + volumeThreshold: 10, + /** + * After what time the circuit breaker is attempting to retry sending requests in milliseconds + * Default: 30_000 + */ + resetTimeout: 30_000, + } + ``` + +Configure the curcuit breaker for temporarily suspending sending usage reports in case of network +issues or outages to avoid exhausting the service from being overwhelmed with failing HTTP requests. + #### Persisted Documents Hive client supports resolving persisted documents. For getting started please refer to our