OpenTelemetry Collector Exporters

Common errors

• ModuleNotFoundError: No module named 'opentelemetry.exporter.otlp.proto.grpc.trace_exporter'

  cause The specific OTLP protocol exporter (e.g., gRPC or HTTP for traces, metrics, or logs) was not installed, as these are separate packages from the base `opentelemetry-exporter-otlp` library.
  fix Install the required protocol-specific package, for example, `pip install opentelemetry-exporter-otlp-proto-grpc` for gRPC or `pip install opentelemetry-exporter-otlp-proto-http` for HTTP.

• rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing: dial tcp 127.0.0.1:4317: connect: connection refused"

  cause The OpenTelemetry Collector or the configured telemetry backend is either not running, not accessible from the application's network, or is listening on a different IP address or port than specified in the exporter configuration.
  fix Verify that the OpenTelemetry Collector or backend service is running and configured to listen on the correct IP address and port (e.g., `0.0.0.0:4317` for gRPC or `0.0.0.0:4318` for HTTP to accept external connections). Check firewall rules and ensure the exporter's `endpoint` URL matches the Collector's listening address.

• io.opentelemetry.exporter.internal.http.HttpExporter - Failed to export spans. Server responded with HTTP status code 401.

  cause The OTLP exporter is attempting to send telemetry data to a secured endpoint without providing valid authentication credentials (e.g., API key, bearer token, or correct TLS certificates), resulting in an unauthorized (401) or forbidden (403) response, or a gRPC 'Unauthenticated' status.
  fix Configure the OTLP exporter with the necessary authentication headers or TLS client certificates as required by your telemetry backend. Enable debug logging for the exporter to view detailed authentication failure messages.

• Failed to export metrics. Server responded with UNIMPLEMENTED. This usually means that your collector is not configured with an otlp receiver in the "pipelines" section of the configuration.

  cause The OpenTelemetry Collector (or the final telemetry backend) is not configured to receive and process the specific type of telemetry data (metrics, traces, or logs) being sent via OTLP.
  fix Update the OpenTelemetry Collector's configuration to include an `otlp` receiver in the relevant `pipelines` section (e.g., `metrics`, `traces`, or `logs`) and ensure it's connected to an appropriate exporter within the Collector's service definition. If the backend does not support a specific signal type, disable its export.

Warnings

• breaking The behavior of start_span and start_as_current_span in NoOpTracer has changed; it now propagates the span context properly.
  Fix: Update code to handle the new behavior in NoOpTracer.
• deprecated LoggingHandler in opentelemetry-sdk is deprecated; use opentelemetry-instrumentation-logging instead.
  Fix: Switch to using opentelemetry-instrumentation-logging for logging.
• breaking The module 'opentelemetry.exporter.otlp.trace_exporter' no longer exists. The OTLP exporter functionality was split into protocol-specific packages (gRPC and HTTP) and their import paths changed.
  Fix: Install either 'opentelemetry-exporter-otlp-proto-grpc' or 'opentelemetry-exporter-otlp-proto-http' (depending on the desired protocol) and update the import statement. For example, change 'from opentelemetry.exporter.otlp.trace_exporter import OTLPSpanExporter' to 'from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter' for the gRPC exporter.
• breaking The application failed with `ModuleNotFoundError: No module named 'opentelemetry.exporter.otlp.trace_exporter'`, indicating that the `opentelemetry-exporter-otlp` package is not installed.
  Fix: Install the missing OpenTelemetry OTLP exporter package. For example, run: `pip install opentelemetry-exporter-otlp`.

Install

• pip install opentelemetry-exporter-otlp Install opentelemetry-exporter-otlp

Imports

• OTLPSpanExporter

  from opentelemetry.exporter.otlp.trace_exporter import OTLPSpanExporter

  Ensure the module structure is correctly followed.

Quickstart

A simple quickstart example to set up an OTLP exporter and send telemetry data.

import os
from opentelemetry import trace
from opentelemetry.exporter.otlp.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.trace import set_tracer_provider

# Set up the OTLP exporter
exporter = OTLPSpanExporter(endpoint=os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'localhost:4317'))

set_tracer_provider(TracerProvider(resource=Resource.create({'service.name': 'example-service'})))

tracer = trace.get_tracer(__name__)

# Example usage
with tracer.start_as_current_span('example-span'):
    print('Hello, OpenTelemetry!')