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 for usage reporting and tracing.

Field	Type	Notes
`name_header`	`string`	HTTP header used to read client name for usage reporting. Default: `graphql-client-name`.
`version_header`	`string`	HTTP header used to read client version for usage reporting. Default: `graphql-client-version`.
`ip_header`	`string \| object \| null`	Optional header-based client IP resolution used for tracing. Default: `null`, which means use socket peer.

router.config.yaml

telemetry:
  client_identification:
    name_header: graphql-client-name # default
    version_header: graphql-client-version # default
    ip_header: null # default

`ip_header`

By default, Hive Router uses the address of the incoming socket connection as the client address.

If your router runs behind proxies or load balancers, you can tell it to resolve the client IP from an HTTP header instead. This affects the http.server tracing span attributes such as client.address and client.port.

Use the left-most value from a header

router.config.yaml

telemetry:
  client_identification:
    ip_header: x-forwarded-for

In this scenario, Hive Router reads the configured header and records the left-most valid IP address as client.address. If the header value includes a port, it also records client.port.

This works well when your networking layer already sanitizes forwarding headers before requests reach the router.

Trust forwarding headers only from trusted proxies

router.config.yaml

telemetry:
  client_identification:
    ip_header:
      name: x-forwarded-for
      trusted_proxies:
        - 10.0.0.0/8
        - 192.168.0.0/16
        - 127.0.0.1

Use this option when the router sits behind one or more trusted proxies.

Hive Router first checks whether the socket peer address belongs to trusted_proxies. If the peer is not trusted, the router ignores the header and falls back to the socket peer.

If the peer is trusted, the router scans the configured header from right to left, skips trusted proxy addresses, and records the first non-trusted IP as client.address.

If all values in the header are trusted, the router uses the left-most value. If no valid client IP can be resolved, the router falls back to the socket peer address.

Each trusted_proxies entry can be either a single IP address or a CIDR range.

Supported header value formats

Hive Router can parse common forwarding header formats, including:

x-forwarded-for: 198.51.100.7, 10.0.0.2
x-forwarded-for: 198.51.100.7:4444, 10.0.0.2
forwarded: for=198.51.100.7;proto=https
forwarded: for="[2001:db8::1]:8080";proto=https

Forwarding headers such as x-forwarded-for can be spoofed by clients. Only trust them when the incoming socket peer is a trusted proxy you control.

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[] \| { expression: string }`	`[]`	Operations to exclude. Accepts a list of operation names or a VRL expression object. See details below.
`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.

The exclude field accepts two formats:

Legacy format — a list of operation names to skip:

router.config.yaml

telemetry:
  hive:
    usage_reporting:
      enabled: true
      exclude:
        - IntrospectionQuery
        - HealthCheck

Dynamic expression format — a VRL expression that has access to the full request context. Return true to exclude the operation or false to include it:

router.config.yaml

telemetry:
  hive:
    usage_reporting:
      enabled: true
      exclude:
        expression: '.request.operation.name == "IntrospectionQuery"'

You can also exclude based on request headers — for example, checking a custom graphql-client-name header:

router.config.yaml

telemetry:
  hive:
    usage_reporting:
      enabled: true
      exclude:
        expression: '.request.headers."graphql-client-name" == "my-internal-tool"'

Expressions can use any fields available under .request (see Expressions for the full list of variables). For more examples, see Excluding Operations.

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

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.

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.

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

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

Edit on GitHub

client_identification

ip_header

Use the left-most value from a header

Trust forwarding headers only from trusted proxies

resource

hive

tracing

metrics

On this page

`ip_header`