Telemetry

Telemetry (OpenTelemetry)

Nexus GSLB supports distributed tracing via OpenTelemetry (OTel). Traces complement Prometheus metrics: metrics give aggregate throughput and latency; traces show the per-request path through the daemon for debugging individual queries or health probe failures.

When no endpoint is configured, the global OTel no-op tracer is used and tracing has zero overhead.

Enable tracing

telemetry:
  otlp:
    endpoint: "localhost:4317"   # gRPC endpoint (OTel Collector or Jaeger)
    insecure: true               # disable TLS — use for local collectors
    serviceName: "nexus-gslb"   # reported service name (default: "nexus-gslb")

Field	Default	Description
`telemetry.otlp.endpoint`	`""`	gRPC endpoint for the OTLP exporter. Leave empty to disable tracing entirely.
`telemetry.otlp.insecure`	`false`	Disable TLS on the gRPC connection. Set `true` for local collectors without TLS.
`telemetry.otlp.serviceName`	`"nexus-gslb"`	Service name reported to the trace backend.

Span catalog

Span name	Tracer	Parent	Key attributes
`dns.handleRequest`	`nexus-gslb/dns`	root	`dns.question` — queried name; `dns.type` — record type (A, AAAA, …)
`dns.resolveFromDB`	`nexus-gslb/dns`	`dns.handleRequest`	`dns.qname` — queried name; status Ok on member hit, Error("no result") on miss
`health.probe`	`nexus-gslb/health`	root (one per endpoint per interval)	`health.ip` — endpoint address; `health.type` — check type (tcp, http, icmp, script, webhook); `health.result` — boolean outcome

Compatible backends

OpenTelemetry Collector (recommended): accepts OTLP gRPC on port 4317. The Collector can fan out to Jaeger, Zipkin, Prometheus remote-write, and more.
Jaeger (v1.35+): accepts native OTLP gRPC directly on port 4317 without a Collector.
Grafana Tempo: accepts OTLP gRPC on port 4317 via its built-in ingester.

Example: local OTel Collector

telemetry:
  otlp:
    endpoint: "localhost:4317"
    insecure: true
    serviceName: "nexus-gslb"

The Collector should be configured with an OTLP receiver and an appropriate exporter:

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: "0.0.0.0:4317"
exporters:
  jaeger:
    endpoint: "jaeger:14250"
    tls:
      insecure: true
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [jaeger]

Example: Jaeger directly

telemetry:
  otlp:
    endpoint: "jaeger-host:4317"
    insecure: false
    serviceName: "nexus-prod"

See Metrics.md for Prometheus metric coverage.