OpenTelemetry Metrics

Hive Router exposes OpenTelemetry metrics for gateway traffic, subgraph traffic, cache behavior, supergraph lifecycle, and GraphQL errors.

This guide explains where to export metrics, how to configure OTLP and Prometheus, how to customize instruments, and what each metric/label means in practice.

Choose your metrics destination

Hive Router supports two common metrics paths:

• OTLP-compatible backends
• Prometheus scraping

In practice, teams with existing OpenTelemetry pipelines usually choose OTLP. Teams with existing Prometheus/Grafana stacks usually choose Prometheus.

Send metrics to OTLP-compatible backends

Hive Router can export metrics directly to any OTLP-compatible destination, including OpenTelemetry Collector and vendor backends that support OTLP ingestion, either through HTTP or gRPC.

After enabling the exporter, send traffic through the router and verify that new metric series appear in your backend (for example HTTP server/client duration, cache metrics, and supergraph metrics). If metrics are missing, start by validating endpoint reachability and auth credentials, then check exporter protocol alignment (HTTP vs gRPC).

telemetry:
  metrics:
    exporters:
      - kind: otlp
        enabled: true
        protocol: http
        endpoint: https://otel-collector.example.com/v1/metrics
        interval: 30s
        max_export_timeout: 5s
        http:
          headers:
            authorization:
              expression: |
                "Bearer " + env("OTLP_TOKEN")

telemetry:
  metrics:
    exporters:
      - kind: otlp
        enabled: true
        protocol: grpc
        endpoint: https://otel-collector.example.com:4317
        interval: 30s
        max_export_timeout: 5s
        grpc:
          metadata:
            x-api-key:
              expression: env("OTEL_API_KEY")
          tls:
            domain_name: otel-collector.example.com
            ca: /etc/certs/ca.pem
            cert: /etc/certs/client.pem
            key: /etc/certs/client.key

Expose metrics for Prometheus scraping

If your observability stack is Prometheus-first, Hive Router can expose a scrape endpoint that Prometheus polls on a schedule.

The port and path settings define where Router serves metrics. Prometheus must be able to reach that address from its runtime environment (local network, Kubernetes service, or VM network path).

In production, make sure this endpoint is reachable only by trusted scrapers and that any ingress or firewall policy allows Prometheus access. Once configured, confirm the target appears as healthy (UP) in Prometheus and then verify expected series are present (for example http.server.request.duration, http.client.request.duration, and hive.router.* cache/supergraph metrics).

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

Production baseline

For production workloads, start with one primary exporter, a clear service identity, and default instrument settings.

telemetry:
  resource:
    attributes:
      service.name: hive-router
      service.namespace: your-platform
      deployment.environment:
        expression: env("ENVIRONMENT")
  metrics:
    exporters:
      - kind: otlp
        enabled: true
        protocol: grpc
        endpoint: https://otel-collector.example.com:4317
        interval: 30s
        max_export_timeout: 5s

This is a safe baseline and works well before introducing instrumentation-level customization. By default, all metrics and labels are exposed.

Customize instrumentation

You can override behavior per metric under telemetry.metrics.instrumentation.instruments.

• false disables a metric.
• true keeps default behavior.
• object form enables metric + optional attribute overrides.

telemetry:
  metrics:
    instrumentation:
      instruments:
        # Disable HTTP server request duration metric
        http.server.request.duration: false
        http.client.request.duration:
          attributes:
            # Disable the label
            subgraph.name: false
            # Enable the label (labels are enabled by default)
            http.response.status_code: true

Attribute override behavior:

• false - drop label from that metric
• true - keep label (all labels are enabled by default)

Metrics reference

GraphQL

GraphQL metrics focus on validation, parsing and execution-time errors surfaced by the router.

Supergraph

Supergraph metrics cover polling and processing lifecycle of schema updates.

HTTP server

HTTP server metrics describe inbound client traffic handled by the router.

HTTP client

HTTP client metrics describe outbound requests to the subgraphs, made by the router.

Cache

Cache metrics track lookup behavior and cache size across router caches.

Parsing cache

Parsing cache metrics measure query parse cache hit/miss behavior and cache size.

Validation cache

Validation cache metrics measure query validation cache hit/miss behavior and cache size.

Normalization cache

Normalization cache metrics measure query normalization cache hit/miss behavior and cache size.

Planning cache

Planning cache metrics measure query planning cache hit/miss behavior and cache size.

Labels

These labels are shared by cache lookup counters and duration histograms.

What to monitor in production

The examples below show what to monitor in production and how to break metrics down so you can quickly detect and isolate API, subgraph, cache, and GraphQL issues.

Monitor latency of your GraphQL API

Use http.server.request.duration as your primary latency signal.

In production, break this metric down by http.route, http.request.method, and http.response.status_code, then track p95 and p99 per route and method. Keep successful and failed responses separated so error-path latency does not get hidden by healthy traffic.

Monitor health of your subgraphs

Use http.client.request.duration and http.client.active_requests to monitor dependency health across your federated graph.

Break these metrics down by subgraph.name, http.response.status_code, and error.type to identify which subgraph is driving tail latency or error spikes.

Monitor cache effectiveness and planning pressure

Use the cache metrics to evaluate cache behavior over time.

For request and duration metrics, split by result (hit and miss) so you can track hit ratio and miss latency per cache tier.

Monitor GraphQL errors over time

Use hive.router.graphql.errors_total and break it down by code to track both volume and error shape.

In production, monitor how error-code distribution changes over time, not only total count, so you can separate validation issues from execution failures.

Configuration reference

For full options and defaults, see telemetry configuration reference.