OTel Troubleshooting

Troubleshoot common issues with OpenTelemetry ingestion, export, data transformation, and instrumentation in Edge Delta.

  3 minute read  

Overview

This page provides a starting point for troubleshooting OpenTelemetry-related issues in Edge Delta. Each section covers common symptoms and links to the relevant detailed guide.

OTLP source issues

Symptoms: No data arriving in the pipeline, connection refused errors in the Collector or SDK, port conflicts.

Common causes:

  • The OTLP source node port does not match the exporter’s target port
  • In Kubernetes, the Service is not configured or targets the wrong port
  • The protocol (gRPC vs HTTP) does not match between source and exporter
  • Firewall rules block the OTLP port

Steps:

  1. Verify the OTLP source node configuration matches the exporter’s endpoint, port, and protocol.
  2. In Kubernetes, confirm the Service exists and maps to the correct agent pod port.
  3. Use Live Capture on the OTLP source node to check if data is arriving.

See OTLP Source Node for configuration details.

OTLP destination issues

Symptoms: Data not reaching the downstream system, 401 authentication errors, connection timeouts, TLS handshake failures.

Common causes:

  • The endpoint includes http:// or https:// (it should not; use tls.enabled instead)
  • Authentication headers are missing or incorrect
  • TLS is not enabled for HTTPS endpoints
  • Metric temporality mismatch (the destination rejects cumulative or delta metrics)

Steps:

  1. Verify the endpoint format does not include the protocol prefix.
  2. Confirm tls.enabled: true is set for port 443 endpoints.
  3. Check authentication headers match the destination’s requirements.
  4. Review agent logs for specific error messages.

See OTLP Destination Troubleshooting for detailed guidance including destination-specific configurations.

Deotel issues

Symptoms: Deotel processor outputs empty data, errors about unsupported field types, arrays instead of objects in output.

Common causes:

  • The field_path points to a field that contains a string, array, or primitive instead of an object
  • The body contains unparsed JSON (a string that needs parsing first)
  • The field does not exist in the data item

Steps:

  1. Use Live Capture before the Deotel processor to inspect the actual data structure.
  2. If the body is a JSON string, add an OTTL Transform with set(body, ParseJSON(body)) before Deotel.
  3. Verify the field_path matches the field name in your data.

See Deotel Troubleshooting for solutions to specific error scenarios.

Instrumentation issues

Symptoms: No traces or metrics from instrumented applications, missing spans, incomplete telemetry.

Common causes:

  • The OTLP exporter endpoint is misconfigured (wrong host, port, or protocol)
  • The SDK is not initialized before application code runs
  • Environment variables for zero-code instrumentation are not set
  • The application exits before the SDK flushes pending telemetry

Steps:

  1. Verify the exporter endpoint points to a running OTLP source node or cloud pipeline.
  2. Check SDK initialization happens before any application logic.
  3. For zero-code instrumentation, verify agent environment variables are set correctly.
  4. Ensure graceful shutdown allows the SDK to flush data.

See the specific language guide for detailed troubleshooting:

Metric temporality issues

Symptoms: Metrics rejected by the destination, errors about unsupported metric types, missing metric data points.

Common causes:

  • The source emits cumulative metrics but the destination requires delta (or vice versa)
  • The cumulative-to-delta processor is missing from the pipeline

Steps:

  1. Check your destination’s documentation for temporality requirements.
  2. If conversion is needed, add the Cumulative to Delta Processor before the OTLP destination.
  3. When possible, configure the SDK to emit the required temporality at the source using OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE.

See Metric Temporality for a detailed explanation.

See also