OpenTelemetry Exporter Connection Refused Fix
In this tutorial, you'll learn about OpenTelemetry Exporter Connection Refused Fix. We cover key concepts, practical examples, and best practices.
Your OpenTelemetry SDK logs Failed to export spans. Connection refused — the OTLP exporter cannot reach the OpenTelemetry Collector or backend. The endpoint URL is wrong, TLS is misconfigured, or nothing is listening on the target port.
The Problem
# WRONG — using HTTPS instead of HTTP for the local collector
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
exporter = OTLPSpanExporter(
endpoint="https://localhost:4317",
insecure=False
)
ERROR: Failed to export spans. Connection refused
Status: StatusCode.UNAVAILABLE
The collector runs insecurely on HTTP port 4317, but the exporter tries HTTPS. With insecure=False, the gRPC client attempts TLS handshake, which the non-TLS collector rejects.
Step-by-Step Fix
1. Match the protocol to the collector
# For gRPC with TLS (collector with TLS)
exporter = OTLPSpanExporter(
endpoint="https://collector.example.com:4317",
insecure=False
)
# For gRPC without TLS (local collector)
exporter = OTLPSpanExporter(
endpoint="http://localhost:4317",
insecure=True
)
# For HTTP/protobuf
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
exporter = OTLPSpanExporter(
endpoint="http://localhost:4318/v1/traces"
)
2. Verify the collector is running
# Check if the collector is listening
netstat -tlnp | grep 4317
# If using Docker
docker ps | grep otel-collector
# Test gRPC connectivity
grpcurl -plaintext localhost:4317 list
3. Configure the collector properly
# otel-collector-config.yaml
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
exporters:
otlp:
endpoint: jaeger:4317
logging:
loglevel: debug
service:
pipelines:
traces:
receivers: [otlp]
exporters: [otlp, logging]
4. Set environment variables for the SDK
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_INSECURE=true
export OTEL_SERVICE_NAME=myapp
5. Handle TLS certificates
# Custom TLS certificate
exporter = OTLPSpanExporter(
endpoint="https://collector.example.com:4317",
credentials=grpc.ssl_channel_credentials(
root_certificates=open('/path/to/ca.crt', 'rb').read()
)
)
Expected output:
OpenTelemetry Collector: localhost:4317
Connection: OK
Exported: 15 spans, 20 metrics, 3 logs
✓ Telemetry pipeline healthy
Prevention Tips
- Use environment variables (
OTEL_EXPORTER_OTLP_ENDPOINT) for endpoint configuration - Verify collector port with
netstatordocker ps - Match
insecuresetting to collector's TLS configuration - Use collector health check:
curl http://localhost:13133/health - Add
otlpexporter logging for debugging
Common Mistakes with exporter
- Misunderstanding that
Stringis[Char]with poor performance for large text operations - Using
foldlinstead offoldl'causing stack overflow on large lists - Forgetting
deriving (Show, Eq)on custom data types needed for debugging
These mistakes appear frequently in real-world OPENTELEMETRY code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.
Practice Exercise
Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.
This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.
FAQ
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro