Common Setup Issues

This guide covers the most common problems encountered when instrumenting applications with OpenTelemetry and sending traces to Kloudfuse APM, with steps to diagnose and resolve each issue.

No Traces Appear in UI

Symptoms

• APM Trace Explorer is empty after setup

• Service does not appear in the service list

• No spans appear even after sending requests

Diagnose

1. Confirm the application is actually emitting spans — add a test span at startup and check application logs for exporter errors.

2. Verify kf-agent is running and reachable from the application pod:

   kubectl get pods -n <namespace>
   kubectl exec -it <app-pod> -- nc -zv kf-agent 4317
   

3. Check the OTLP endpoint format — gRPC uses http://kf-agent:4317 (no trailing slash, no path); HTTP/JSON uses http://kf-agent:4318.

4. Confirm service.name is set — without it the SDK defaults to unknown_service:<process> and may not appear where you expect it.

5. Confirm the sampler is not set to always_off or traceidratio with arg 0.

Fix

Enable debug logging for the SDK to see exporter errors in the application log output:

# Java agent
-Dotel.javaagent.debug=true

# Python
OTEL_LOG_LEVEL=debug opentelemetry-instrument python app.py

For Go applications, do not import OpenTelemetry internal packages. Instead, enable debug logging through your application’s normal logger and log any exporter or provider initialization errors using public OpenTelemetry APIs. Look for lines containing OTLP export failed, connection refused, or StatusCode. Fix the endpoint or firewall rules and retry.

Partial or Broken Traces

Symptoms

• Trace timeline shows orphan spans with no parent

• trace_id is the same but spans appear under separate traces

• Parent-child relationships are missing between services

Causes

• Trace context headers (traceparent, tracestate) are not forwarded on outbound HTTP or gRPC calls

• An intermediate service strips or rewrites headers

• Services use different propagator formats (e.g., B3 vs W3C TraceContext)

Fix

Ensure W3C TraceContext propagation is configured globally and that headers are forwarded on every outbound call.

Java — the agent propagates automatically for all supported HTTP clients. If using RestTemplate or WebClient manually, do not recreate the client inside a span — let the agent intercept it.

Python — inject headers on outbound requests using the propagator:

from opentelemetry.propagate import inject

headers = {}
inject(headers)   # adds traceparent / tracestate
response = requests.get("http://other-service/api", headers=headers)

Go — use otelhttp.NewTransport so the HTTP client injects headers automatically:

import "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"

client := &http.Client{Transport: otelhttp.NewTransport(http.DefaultTransport)}
req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
client.Do(req)

If services use different propagator formats, set a consistent list on all services:

OTEL_PROPAGATORS=tracecontext,baggage

Spans Are Dropped or Silently Lost

Symptoms

• Traces appear incomplete under high load but are fine at low throughput

• Application logs show BatchSpanProcessor queue is full or dropping span

Causes

The BatchSpanProcessor has a finite in-memory queue. When the application produces spans faster than the exporter can flush them, excess spans are dropped without error.

Fix

Increase the queue and batch sizes using environment variables (applies to Java, Python, and Go):

OTEL_BSP_MAX_QUEUE_SIZE=8192        # default 2048
OTEL_BSP_MAX_EXPORT_BATCH_SIZE=1024 # default 512
OTEL_BSP_SCHEDULE_DELAY=2000        # flush interval in ms, default 5000
OTEL_EXPORTER_OTLP_COMPRESSION=gzip # reduce network overhead

If drops persist, consider reducing trace volume with sampling:

OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1   # sample 10% of root traces

See Performance Tuning for a full reference of BSP environment variables.