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.

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

router.config.yaml


telemetry:
  resource:
    attributes:
      service.name:
        expression: env("SERVICE_NAME")
      service.version: 1.0.0

hive

Hive-specific telemetry options.

Show hive configuration

Field	Type	Notes
`token`	`StringOrExpression`	Your Registry Access Token with write permission. 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`). You can also set `HIVE_TARGET`.

usage_reporting

Allows you to control how the Hive Router does usage reporting to Hive Console.

For additional information about the usage reporting process in Hive Router, see the Usage Reporting page.

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.

router.config.yaml


telemetry:
  hive:
    usage_reporting:
      enabled: true
      exclude: ['IntrospectionQuery']

tracing

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` below.

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.

router.config.yaml


telemetry:
  hive:
    tracing:
      enabled: true

tracing

Top-level OpenTelemetry tracing configuration.

Show tracing configuration

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.

exporters

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` below.

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 }`).

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.

router.config.yaml


telemetry:
  tracing:
    exporters:
      - kind: 'otlp'
        enabled: true
        protocol: grpc
        grpc:
          metadata:
            x-api-key: key