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
<span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="fu">telemetry</span><span class="kw">:</span></span><span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">otlp</span><span class="kw">:</span></span><span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">endpoint</span><span class="kw">:</span><span class="at"> </span><span class="st">"localhost:4317"</span><span class="co"> # gRPC endpoint (OTel Collector or Jaeger)</span></span><span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">insecure</span><span class="kw">:</span><span class="at"> </span><span class="ch">true</span><span class="co"> # disable TLS — use for local collectors</span></span><span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">serviceName</span><span class="kw">:</span><span class="at"> </span><span class="st">"nexus-gslb"</span><span class="co"> # reported service name (default: "nexus-gslb")</span></span>| 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
<span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="fu">telemetry</span><span class="kw">:</span></span><span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">otlp</span><span class="kw">:</span></span><span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">endpoint</span><span class="kw">:</span><span class="at"> </span><span class="st">"localhost:4317"</span></span><span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">insecure</span><span class="kw">:</span><span class="at"> </span><span class="ch">true</span></span><span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">serviceName</span><span class="kw">:</span><span class="at"> </span><span class="st">"nexus-gslb"</span></span>The Collector should be configured with an OTLP receiver and an appropriate exporter:
<span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="co"># otel-collector-config.yaml</span></span><span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="fu">receivers</span><span class="kw">:</span></span><span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">otlp</span><span class="kw">:</span></span><span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">protocols</span><span class="kw">:</span></span><span id="cb3-5"><a href="#cb3-5" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">grpc</span><span class="kw">:</span></span><span id="cb3-6"><a href="#cb3-6" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">endpoint</span><span class="kw">:</span><span class="at"> </span><span class="st">"0.0.0.0:4317"</span></span><span id="cb3-7"><a href="#cb3-7" aria-hidden="true" tabindex="-1"></a><span class="fu">exporters</span><span class="kw">:</span></span><span id="cb3-8"><a href="#cb3-8" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">jaeger</span><span class="kw">:</span></span><span id="cb3-9"><a href="#cb3-9" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">endpoint</span><span class="kw">:</span><span class="at"> </span><span class="st">"jaeger:14250"</span></span><span id="cb3-10"><a href="#cb3-10" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">tls</span><span class="kw">:</span></span><span id="cb3-11"><a href="#cb3-11" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">insecure</span><span class="kw">:</span><span class="at"> </span><span class="ch">true</span></span><span id="cb3-12"><a href="#cb3-12" aria-hidden="true" tabindex="-1"></a><span class="fu">service</span><span class="kw">:</span></span><span id="cb3-13"><a href="#cb3-13" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">pipelines</span><span class="kw">:</span></span><span id="cb3-14"><a href="#cb3-14" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">traces</span><span class="kw">:</span></span><span id="cb3-15"><a href="#cb3-15" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">receivers</span><span class="kw">:</span><span class="at"> </span><span class="kw">[</span><span class="at">otlp</span><span class="kw">]</span></span><span id="cb3-16"><a href="#cb3-16" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">exporters</span><span class="kw">:</span><span class="at"> </span><span class="kw">[</span><span class="at">jaeger</span><span class="kw">]</span></span>Example: Jaeger directly
<span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="fu">telemetry</span><span class="kw">:</span></span><span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">otlp</span><span class="kw">:</span></span><span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">endpoint</span><span class="kw">:</span><span class="at"> </span><span class="st">"jaeger-host:4317"</span></span><span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">insecure</span><span class="kw">:</span><span class="at"> </span><span class="ch">false</span></span><span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a><span class="at"> </span><span class="fu">serviceName</span><span class="kw">:</span><span class="at"> </span><span class="st">"nexus-prod"</span></span>See Metrics.md for Prometheus metric coverage.