Elgato_dark/console
1
0
Fork 0
mirror of https://github.com/graphql-hive/console synced 2026-04-21 14:37:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
console/packages/web/docs/src/content/router/configuration/telemetry.mdx
Kamil Kisiela 39432a7aa0
docs(router): document telemetry (#7658)
2026-02-11 15:49:00 +02:00

238 lines
12 KiB
Text
Raw Blame History

---
title: 'telemetry'
---
# telemetry
The `telemetry` configuration controls client identification, Hive reporting, and OpenTelemetry
tracing behavior in Hive Router.
## client_identification
Configure how Hive Router identifies calling clients in telemetry, based on request headers.
| Field | Type | Notes |
| ---------------- | -------- | ------------------------------------------------------------ |
| `name_header` | `string` | HTTP header used to read client name for usage reporting. |
| `version_header` | `string` | HTTP header used to read client version for usage reporting. |
```yaml filename="router.config.yaml"
telemetry:
client_identification:
name_header: graphql-client-name # default
version_header: graphql-client-version # default
```
## resource
Attach OpenTelemetry resource attributes that describe this router instance, such as service name,
version, or environment.
| Field | Type | Default | Notes |
| ------------ | -------- | ------- | -------------------------------------------- |
| `attributes` | `object` | `{}` | Additional OpenTelemetry resource attributes |
```yaml filename="router.config.yaml"
telemetry:
resource:
attributes:
service.name:
expression: env("SERVICE_NAME")
service.version: 1.0.0
```
## hive
Hive-specific telemetry options.
<details>
<summary>Show hive configuration</summary>
| Field | Type | Notes |
| -------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `token` | `StringOrExpression` | Your [Registry Access Token](/docs/management/targets#registry-access-tokens) with write permission.<br />You can also set `HIVE_ACCESS_TOKEN`. |
| `target` | `StringOrExpression` | Target ID as slug (`the-guild/graphql-hive/staging`) or UUID (`a0f4c605-6541-4350-8cfe-b31f21a4bf80`).<br />You can also set `HIVE_TARGET`. |
<div id="usage_reporting" style={{marginTop: 10}}>
<details>
<summary>usage_reporting</summary>
Allows you to control how the Hive Router does
[usage reporting](/docs/schema-registry/usage-reporting) to Hive Console.
> For additional information about the usage reporting process in Hive Router, see the
> [Usage Reporting page](/docs/router/observability/usage_reporting).
| Field | Type | Default | Notes |
| ---------------------- | ---------- | ------------------------------------ | ------------------------------------------------------------- |
| `enabled` | `boolean` | `false` | Explicitly enable or disable usage reporting. |
| `endpoint` | `string` | `https://app.graphql-hive.com/usage` | Override for self-hosted Hive. |
| `sample_rate` | `string` | `100%` | Percentage between `0%` and `100%`. |
| `exclude` | `string[]` | `[]` | Operation names to ignore (for example `IntrospectionQuery`). |
| `buffer_size` | `integer` | `1000` | Buffer size before flush. |
| `accept_invalid_certs` | `boolean` | `false` | Accept invalid SSL certificates for usage reporting. |
| `connect_timeout` | `string` | `5s` | Timeout for connect phase only. |
| `request_timeout` | `string` | `15s` | Timeout for the full request. |
| `flush_interval` | `string` | `5s` | Buffer flush interval. |
```yaml filename="router.config.yaml"
telemetry:
hive:
usage_reporting:
enabled: true
exclude: ['IntrospectionQuery']
```
</details>
</div>
<div id="hive-tracing" style={{marginTop: 10}}>
<details>
<summary>tracing</summary>
This configuration object controls sending traces to Hive Console.
| Field | Type | Default | Notes |
| ----------------- | -------------------- | --------------------------------------------- | ------------------------------------------------------------- |
| `enabled` | `boolean` | `false` | If `true`, the Hive Router sends traces to Hive Console. |
| `endpoint` | `StringOrExpression` | `https://api.graphql-hive.com/otel/v1/traces` | Hive Console traces ingestion endpoint. |
| `batch_processor` | `object` | - | See [`batch_processor`](#hive-tracing-batch-processor) below. |
<div id="hive-tracing-batch-processor"></div>
Batching settings for traces sent to Hive Console:
| Field | Type | Default | Notes |
| ------------------------ | --------- | ------- | --------------------------------------------- |
| `max_traces_in_memory` | `integer` | `30000` | Maximum number of traces in memory. |
| `max_spans_per_trace` | `integer` | `1000` | Maximum spans buffered per trace. |
| `max_export_timeout` | `string` | `5s` | Maximum time to wait for batch export. |
| `max_queue_size` | `integer` | `20000` | Capacity of the internal queue before export. |
| `max_export_batch_size` | `integer` | `500` | Maximum traces per single export batch. |
| `scheduled_delay` | `string` | `5s` | Maximum delay before exporting ready traces. |
| `max_concurrent_exports` | `integer` | `1` | Maximum number of concurrent export tasks. |
```yaml filename="router.config.yaml"
telemetry:
hive:
tracing:
enabled: true
```
</details>
</div>
</details>
## tracing
Top-level OpenTelemetry tracing configuration.
<details>
<summary>Show tracing configuration</summary>
`collect` - Collection and sampling limits for spans.
| Field | Type | Default | Notes |
| -------------------------- | --------- | ------- | -------------------------------------------- |
| `max_events_per_span` | `integer` | `128` | Maximum events to record per span. |
| `max_attributes_per_span` | `integer` | `128` | Maximum attributes to record per span. |
| `max_attributes_per_event` | `integer` | `16` | Maximum attributes to record per span event. |
| `max_attributes_per_link` | `integer` | `32` | Maximum attributes to record per span link. |
| `sampling` | `number` | `1.0` | Sampling ratio between `0.0` and `1.0`. |
| `parent_based_sampler` | `boolean` | `false` | Inherit sampling decisions from parent span. |
`propagation` - Incoming and outgoing trace context propagation formats.
These settings apply to both extracting trace context from incoming requests and injecting trace
context into outgoing requests.
| Field | Type | Default | Notes |
| --------------- | --------- | ------- | ------------------------------------- |
| `trace_context` | `boolean` | `true` | Enable W3C Trace Context propagation. |
| `baggage` | `boolean` | `false` | Enable W3C Baggage propagation. |
| `b3` | `boolean` | `false` | Enable B3 propagation. |
| `jaeger` | `boolean` | `false` | Enable Jaeger propagation. |
`instrumentation` - Instrumentation behavior for spans.
| Field | Type | Default | Allowed values | Notes |
| ------------ | -------- | ---------------- | ----------------------------------------------------- | --------------------------------------------------------- |
| `spans.mode` | `string` | `spec_compliant` | `spec_compliant`, `deprecated`, `spec_and_deprecated` | Controls which semantic conventions are emitted on spans. |
<div id="exporters" style={{marginTop: 10}}>
<details>
<summary>`exporters`</summary>
List of exporters used to send traces.
Each item in this array defines one exporter instance, so you can configure multiple OTLP
destinations if needed.
This reference documents the OTLP exporter configuration.
| Field | Type | Default | Notes |
| ----------------- | -------------------- | ------- | ---------------------------------------------------------------------------- |
| `kind` | `string` | - | Exporter kind. Supported value: `otlp`. |
| `enabled` | `boolean` | `true` | Enables or disables this exporter. |
| `endpoint` | `StringOrExpression` | - | OTLP endpoint. Must be set explicitly. |
| `batch_processor` | `object` | - | See [`batch_processor`](#telemetry-tracing-exporters-batch-processor) below. |
<div id="telemetry-tracing-exporters-batch-processor"></div>
`batch_processor` settings for this exporter:
| Field | Type | Default |
| ------------------------ | --------- | ------- |
| `max_concurrent_exports` | `integer` | `1` |
| `max_export_batch_size` | `integer` | `512` |
| `max_queue_size` | `integer` | `2048` |
| `max_export_timeout` | `string` | `5s` |
| `scheduled_delay` | `string` | `5s` |
OTLP over HTTP:
| Field | Type | Value / Default | Notes |
| -------------- | -------- | --------------- | ------------------------------------------------------------- |
| `protocol` | `string` | `http` | OTLP transport protocol. |
| `http.headers` | `object` | `{}` | Map of header names to values (`string` or `{ expression }`). |
```yaml filename="router.config.yaml"
telemetry:
tracing:
exporters:
- kind: 'otlp'
enabled: true
protocol: http
http:
headers:
x-otlp-header: value
```
OTLP over gRPC:
| Field | Type | Value / Default | Notes |
| ---------------------- | -------- | --------------- | ---------------------------------------------------------------------------- |
| `protocol` | `string` | `grpc` | OTLP transport protocol. |
| `grpc.metadata` | `object` | `{}` | Map of metadata keys to values (`string` or `{ expression }`). |
| `grpc.tls.domain_name` | `string` | - | Domain name used to verify the server certificate. |
| `grpc.tls.key` | `string` | - | Path to the client private key file. |
| `grpc.tls.cert` | `string` | - | Path to the client certificate file (PEM). |
| `grpc.tls.ca` | `string` | - | Path to the CA certificate file (PEM) used to verify the server certificate. |
```yaml filename="router.config.yaml"
telemetry:
tracing:
exporters:
- kind: 'otlp'
enabled: true
protocol: grpc
grpc:
metadata:
x-api-key: key
```
</details>
</div>
</details>
Reference in a new issue View git blame Copy permalink