telemetry

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.

sampling

The sampling field controls how operations are sampled before being reported to Hive Console. Exclusion (the exclude field) is always evaluated before sampling, so excluded operations are dropped immediately and never affect sampling decisions.

The at_least_once object accepts:

telemetry:
  hive:
    usage_reporting:
      enabled: true
      sampling:
        rate: "10%" # report 10% of operations
        at_least_once:
          key: # the combination of operation name and body makes a request unique
            - operation_name
            - operation_body
          max_distinct_keys: 12000

See Sampling for more details.

The exclude field accepts two formats:

Legacy format — a list of operation names to skip:

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:

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:

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.

This configuration object controls sending traces to Hive Console.

Batching settings for traces sent to Hive Console:

telemetry:
  hive:
    tracing:
      enabled: true

List of exporters used to send traces.

Each item in this array defines one exporter instance. OTLP, stdout, Hive Console tracing, and one enabled native Datadog exporter can share the same tracer provider.

otlp

batch_processor settings for this exporter:

OTLP over HTTP:

telemetry:
  tracing:
    exporters:
      - kind: "otlp"
        enabled: true
        protocol: http
        http:
          headers:
            x-otlp-header: value

OTLP over gRPC:

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

datadog

Native Datadog tracing sends traces to a Datadog Agent and uses Datadog’s provider-wide sampler. Only one Datadog exporter can be enabled.

telemetry:
  tracing:
    collect:
      sampling: 0.01
    exporters:
      - kind: datadog
        endpoint:
          expression: env("DD_TRACE_AGENT_URL")
        include_graphql_document: false

When endpoint is omitted, Datadog uses DD_TRACE_AGENT_URL, DD_AGENT_HOST, DD_TRACE_AGENT_PORT, or its native default. Configured endpoints are resolved and validated at startup, but Agent reachability is not probed.

collect.sampling overrides DD_TRACE_SAMPLE_RATE as Datadog’s catch-all rate. More specific DD_TRACE_SAMPLING_RULES, remote configuration, and DD_TRACE_RATE_LIMIT still apply. Explicit sampling has a default ceiling of 100 retained traces per second. Datadog continues recording non-retained requests for request, error, and latency statistics, including when sampling is 0.0.

parent_based_sampler does not configure Datadog. Mixed OTLP, stdout, and Hive processors receive only sampled spans. DD_TRACE_ENABLED=false disables every processor attached to the shared Datadog-backed provider; set this exporter’s enabled field to false to disable only Datadog.

When include_graphql_document is false, suppression occurs before the shared provider, so mixed OTLP, stdout, and Hive processors also omit the document. The router retains its configured propagators and does not install Datadog-native propagation.

See Native Datadog tracing for operational details and security guidance.

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.

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

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

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

Controls histogram aggregation and per-instrument overrides.

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