telemetry

The telemetry configuration controls client identification, Hive reporting, and OpenTelemetry tracing and metrics 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

metrics

Top-level OpenTelemetry metrics configuration.

Show metrics configuration

Metrics are enabled when at least one exporter is configured and enabled.

Field	Type	Default	Notes
`exporters`	`array`	`[]`	List of exporters used to send metrics.
`instrumentation`	`object`	`{}`	Instrument behavior for metrics (histogram aggregation and per-instrument overrides).

exporters

Each item configures one metrics exporter.

Each item in this array defines one exporter instance, so you can configure multiple metrics destinations if needed.

This reference documents OTLP and Prometheus exporter configuration.

Field	Type	Default	Notes
`kind`	`string`	-	Exporter kind. Supported values: `otlp`, `prometheus`.
`enabled`	`boolean`	`true`	Enables or disables this exporter.

otlp

Field	Type	Default	Notes
`kind`	`string`	-	Must be `otlp`.
`enabled`	`boolean`	`true`	Enables or disables this exporter.
`endpoint`	`StringOrExpression`	-	OTLP endpoint. Must be set explicitly.
`protocol`	`string`	-	OTLP transport protocol. Supported values: `http`, `grpc`.
`interval`	`string`	`60s`	Interval between OTLP export attempts.
`temporality`	`string`	`cumulative`	Aggregation temporality. Supported values: `cumulative`, `delta`.
`max_export_timeout`	`string`	`5s`	Maximum time for one OTLP export attempt.
`http`	`object`	-	HTTP-specific OTLP settings (for `protocol: http`).
`grpc`	`object`	-	gRPC-specific OTLP settings (for `protocol: grpc`).

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:
  metrics:
    exporters:
      - kind: otlp
        enabled: true
        protocol: http
        endpoint: https://otel-collector.example.com/v1/metrics
        interval: 60s
        temporality: cumulative
        max_export_timeout: 5s
        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:
  metrics:
    exporters:
      - kind: otlp
        enabled: true
        protocol: grpc
        endpoint: https://otel-collector.example.com:4317
        interval: 60s
        temporality: cumulative
        max_export_timeout: 5s
        grpc:
          metadata:
            x-api-key: key

prometheus

Field	Type	Default	Notes
`kind`	`string`	-	Must be `prometheus`.
`enabled`	`boolean`	`true`	Enables/disables Prometheus metrics export.
`port`	`integer`	-	Optional port for metrics endpoint.
`path`	`string`	`/metrics`	HTTP path exposed for scraping.

router.config.yaml


telemetry:
  metrics:
    exporters:
      - kind: prometheus
        enabled: true
        port: 9090
        path: /metrics

instrumentation

Controls histogram aggregation and per-instrument overrides.

Field	Type	Default	Notes
`common.histogram`	`object`	exponential aggregation	Histogram aggregation strategy for instrumented histograms.
`instruments`	`object`	`{}`	Map of metric name to `false`, `true`, or object override.

common.histogram

Set aggregation mode with aggregation.

explicit aggregation (default):

Field	Type	Default	Notes
`aggregation`	`string`	-	Must be `explicit`.
`seconds`	`object`	-	Explicit histogram config for metrics with unit `s`.
`bytes`	`object`	-	Explicit histogram config for metrics with unit `By`.

seconds and bytes fields:

Field	Type	Default	Notes
`buckets`	`number[] \| string[]`	varies	Explicit bucket upper bounds. Must be non-empty and increasing.
`record_min_max`	`boolean`	`false`	Record min/max values for this unit bucket set.

Default explicit buckets:

seconds.buckets: [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10]
bytes.buckets: [128, 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288, 1048576, 2097152, 3145728, 4194304, 5242880]

Bucket format rules:

buckets can be either all numbers or all strings.
mixed arrays are not allowed.
for seconds.buckets, string values are parsed as durations (for example "5ms", "1s").
for bytes.buckets, string values are parsed as human-readable sizes (for example "1KB", "5MB").

exponential aggregation:

Field	Type	Default	Notes
`aggregation`	`string`	-	Must be `exponential`.
`max_size`	`integer`	-	Max bucket count. Required.
`max_scale`	`integer`	-	Max scale for bucket precision. Required.
`record_min_max`	`boolean`	`false`	Record min/max values.

instruments

instruments is a map keyed by metric name. Value can be:

false to disable a metric
true to keep defaults
object to keep metric enabled and override attributes

Object form supports:

Field	Type	Notes
`attributes`	`object`	Map of attribute name to `boolean` (`false` drops attribute, `true` keeps it).

router.config.yaml


telemetry:
  metrics:
    instrumentation:
      common:
        histogram:
          aggregation: explicit
          seconds:
            buckets:
              [
                '5ms',
                '10ms',
                '25ms',
                '50ms',
                '75ms',
                '100ms',
                '250ms',
                '500ms',
                '750ms',
                '1s',
                '2.5s',
                '5s',
                '7.5s',
                '10s'
              ]
            record_min_max: false
          bytes:
            buckets:
              [
                '128B',
                '512B',
                '1KB',
                '2KB',
                '4KB',
                '8KB',
                '16KB',
                '32KB',
                '64KB',
                '128KB',
                '256KB',
                '512KB',
                '1MB',
                '2MB',
                '3MB',
                '4MB',
                '5MB'
              ]
            record_min_max: false
      instruments:
        http.server.request.duration: true
        http.client.request.duration:
          attributes:
            subgraph.name: true
            http.response.status_code: true
            server.address: false