docs(js-sdk): document agent and logger configuration options (#7269)

Author: n1ru4l

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)
    */
@@ -86,6 +82,8 @@ export interface AgentOptions {
    * used by the agent to send reports
    */
   fetch?: typeof fetch;
+  /** @deprecated This is no longer used. */
+  minTimeout?: number;
 }
 
 export function createAgent<TEvent>(

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,68 @@ useHive({
 
 </Tabs>
 
+##### 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
+
+###### `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
@@ -397,6 +461,34 @@ useHive({
 })
 ```
 
+#### Logging
+
+You can customize the logging level or provide your own (JSON) logger implementation.
+
+##### `logger`
+
+- Type: [`Logger`](/docs/logger) or log level string
+- Default: `info`
+
+It is possible to provide the following options:
+
+- `'trace'`
+- `'debug'`
+- `'info'` default
+- `'warn'`
+- `'error'`
+
+```ts filename="Example: Set debug level based on environment variable"
+import { createHive } from '@graphql-hive/core'
+
+const client = createHive({
+  logger: process.env.DEBUG === '1' ? 'debug' : 'info'
+})
+```
+
+Alternatively, you can also provide your own [`Logger`](/docs/logger) (or any API-compatible
+implementation) to integrate Hive logs with your web server or logging solution.
+
 #### Custom Integration
 
 If your GraphQL server is not listed above, you can implement a custom integration. Start by