OpenTelemetry Collector Protobuf over HTTP Exporter
raw JSON → 1.40.0 verified Tue May 12 auth: no python install: stale quickstart: stale
The OpenTelemetry Exporter for sending telemetry data via HTTP using the OpenTelemetry Protocol. Current version is 1.40.0, released regularly as part of the OpenTelemetry project.
pip install opentelemetry-exporter-otlp-proto-http Common errors
error ModuleNotFoundError: No module named 'opentelemetry.exporter.otlp.proto.http' ↓
cause This error occurs when the 'opentelemetry-exporter-otlp-proto-http' package is not installed in the Python environment, or there is a Python environment mismatch.
fix
Install the necessary package using pip:
pip install opentelemetry-exporter-otlp-proto-http. Ensure you are installing it in the same Python environment where your application is running. error Failed to export spans. The request could not be executed. Full error message: Failed to connect to localhost:4318 ↓
cause This often indicates a 'Connection refused' error where the OpenTelemetry Collector or backend is not running, is inaccessible, or the exporter is trying to connect to a port/protocol that the receiver is not configured for (e.g., sending HTTP to a gRPC port). A common cause is the Collector binding to 'localhost' (127.0.0.1) instead of '0.0.0.0'.
fix
Verify that your OpenTelemetry Collector or backend is running and configured to accept OTLP/HTTP connections on the specified endpoint and port (typically port 4318). Ensure the Collector is listening on '0.0.0.0' for external connections. For the Python exporter, ensure the endpoint matches, e.g.,
OTLPSpanExporter(endpoint='http://localhost:4318/v1/traces'). error TypeError: Descriptors cannot not be created directly. ↓
cause This error typically arises from a version incompatibility between the 'protobuf' library and the 'opentelemetry-proto' or other OpenTelemetry packages. It often happens when 'protobuf' v4.x is installed while a dependency expects v3.x, or vice versa.
fix
Downgrade your 'protobuf' package to a compatible version, such as
protobuf==3.20.3, or ensure all OpenTelemetry-related packages are installed with compatible versions. pip install protobuf==3.20.3. error Failed to export spans. Server responded with HTTP status code 401 ↓
cause This error indicates an authentication failure where the OTLP/HTTP exporter is attempting to send data to a backend that requires authentication, but the provided API key, token, or authentication headers are missing, invalid, or incorrectly configured.
fix
Configure the OTLP exporter with the correct authentication headers as required by your OpenTelemetry Collector or observability backend. For example, when creating the exporter:
OTLPSpanExporter(endpoint="https://your-otlp-endpoint", headers={"x-api-key": "YOUR_API_KEY"}). Warnings
breaking Changes to `start_span` and `start_as_current_span` behavior in NoOpTracer. ↓
fix Update to the new behavior for correct span context propagation.
deprecated The `LoggingHandler` in `opentelemetry-sdk` is now deprecated. ↓
fix Use `opentelemetry-instrumentation-logging` instead.
breaking The import path for `OTLPMetricExporter` has changed. It is no longer directly available from `opentelemetry.exporter.otlp.proto.http`. ↓
fix Update the import statement to `from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter`.
breaking The `OTLPMetricExporter` has been moved from `opentelemetry.exporter.otlp.proto.http`. ↓
fix Import `OTLPMetricExporter` from `opentelemetry.exporter.otlp.proto.http.metric_exporter` instead.
Install compatibility stale last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) - - - -
3.10 slim (glibc) - - - -
3.11 alpine (musl) - - - -
3.11 slim (glibc) - - - -
3.12 alpine (musl) - - - -
3.12 slim (glibc) - - - -
3.13 alpine (musl) - - - -
3.13 slim (glibc) - - - -
3.9 alpine (musl) - - - -
3.9 slim (glibc) - - - -
Imports
- OTLPExportSpanProcessor
from opentelemetry.exporter.otlp.proto.http import OTLPExportSpanProcessor
Quickstart stale last tested: 2026-04-23
import os
from opentelemetry import metrics
from opentelemetry.exporter.otlp.proto.http import OTLPMetricExporter
from opentelemetry.sdk.metrics import MeterProvider
# Set up OpenTelemetry
meter_provider = MeterProvider()
metrics.set_meter_provider(meter_provider)
# Create an exporter
exporter = OTLPMetricExporter(endpoint=os.environ.get('OTEL_EXPORTER_OTLP_ENDPOINT', 'http://localhost:4317'))
# Use the exporter
meter = metrics.get_meter(__name__)
metric = meter.create_counter('example_counter')
metric.add(1)