OpenTelemetry Collector Protobuf over gRPC Exporter

1.40.0 verified Tue May 12 auth: no python install: stale quickstart: stale

This library provides an exporter for sending telemetry data to the OpenTelemetry Collector using Protobuf over gRPC. The current version is 1.40.0, and releases are made regularly with updates and fixes.

pip install opentelemetry-exporter-otlp-proto-grpc

Common errors

error ModuleNotFoundError: No module named 'opentelemetry.exporter.otlp.proto.grpc' ↓

cause The `opentelemetry-exporter-otlp-proto-grpc` package is not installed in your Python environment or there's a problem with your Python path.

fix

Install the necessary exporter package: pip install opentelemetry-exporter-otlp-proto-grpc.

error grpc._channel._MultiThreadedRendezvous: <_Rendezvous object at ...> debug_error_string = "{"created":"@1679934000.000000000","description":"Error received from peer ipv4:127.0.0.1:4317","file":"src/core/lib/surface/call.cc","file_line":901,"grpc_message":"Connect Failed","grpc_status":14}" or "failed to export traces: connection refused" ↓

cause Your application cannot establish a gRPC connection to the OpenTelemetry Collector or the configured OTLP endpoint. This often happens because the Collector is not running, is listening on an incorrect address (e.g., 'localhost' instead of '0.0.0.0' in a containerized environment), or a firewall is blocking the connection.

fix

Ensure the OpenTelemetry Collector is running and accessible from your application. Verify the OTLP endpoint configuration in your code matches the Collector's listening address and port (default gRPC port is 4317). If running in Docker or Kubernetes, configure the Collector to listen on '0.0.0.0' and ensure your application uses the correct service name or IP.

error TypeError: Descriptors cannot not be created directly. If this call came from a _pb2.py file, your generated code is out of date and must be regenerated with protoc >= 3.19.0. ↓

cause This error is typically caused by a version conflict with the `protobuf` library. It occurs when a newer version of `protobuf` (e.g., 4.x) is installed, but an OpenTelemetry dependency (like `grpcio` or `opentelemetry-proto`) expects an older `protobuf` version (e.g., 3.x) and has out-of-date generated `.proto` files.

fix

Downgrade your protobuf package to a version compatible with your grpcio and OpenTelemetry packages, or update grpcio and opentelemetry-proto to versions that support protobuf 4.x. A common fix is pip install 'protobuf<4.0.0' or pip install --upgrade grpcio opentelemetry-proto to ensure compatible versions. Sometimes PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python can also temporarily work, but it's slower.

error AttributeError: module 'opentelemetry.sdk.trace' has no attribute 'SpanLimits' ↓

cause This indicates an incompatibility or version mismatch among different OpenTelemetry Python packages (e.g., `opentelemetry-api`, `opentelemetry-sdk`, and the exporter). Components might be expecting classes or attributes that exist in different versions of other packages.

fix

Ensure all OpenTelemetry packages are installed at compatible versions. It's often best to upgrade all OpenTelemetry-related packages to their latest stable versions simultaneously: pip install --upgrade opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-grpc grpcio or perform a clean reinstall.

Warnings

breaking Invalid span will no longer be returned in NoOpTracer methods. ↓

fix Ensure that the current span context is properly propagated.

deprecated LoggingHandler in opentelemetry-sdk is deprecated. ↓

fix Use opentelemetry-instrumentation-logging instead.

breaking The class 'OTLPExporter' has been removed or renamed within the 'opentelemetry.exporter.otlp.proto.grpc' module and is no longer directly importable. ↓

fix Use 'OTLPSpanExporter' for traces or 'OTLPMetricExporter' for metrics. The import path has also changed; for example, use 'from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter' for traces or 'from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter' for metrics.

breaking The `OTLPExporter` class is no longer available directly under `opentelemetry.exporter.otlp.proto.grpc` due to package restructuring. ↓

fix Update the import statement. For general OTLP/gRPC export, import `OTLPGRPCExporter` from `opentelemetry.exporter.otlp.proto.grpc.exporter`. For trace exporting, import `OTLPTraceExporter` from `opentelemetry.exporter.otlp.proto.grpc.trace_exporter`. For metric exporting, import `OTLPMetricExporter` from `opentelemetry.exporter.otlp.proto.grpc.metric_exporter`.

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

OTLPExporter

from opentelemetry.exporter.otlp.proto.grpc import OTLPExporter

This import was previously under a different path.

Quickstart stale last tested: 2026-04-23

A simple example of using the OTLP exporter to start a span.

import os
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc import OTLPExporter

exporter = OTLPExporter(endpoint=os.environ.get('OTLP_ENDPOINT', 'localhost:4317'))

tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span('example-span'):
    print('This is a traced span')