feat: make retryable gRPC error codes configurable for gRPC exporters (open-telemetry#4917)

* feat: make retryable gRPC error codes configurable for gRPC exporters

* update CHANGELOG.md

* add ability to configure OTLP gRPC retryable error codes via environment variables

* update OTLP gRPC exporter constructor type hints

* update retryable error codes initialization logic

* fix typechecking error

* update environment variables docstring

* remove trailing whitespace

* Fix formattings

---------

Co-authored-by: Aaron Abbott <aaronabbott@google.com>

Author: herin049

CHANGELOG.md

@@ -50,6 +50,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#5145](https://github.com/open-telemetry/opentelemetry-python/pull/5145))
 - `opentelemetry-exporter-otlp-json-common`: add 'opentelemetry-exporter-otlp-json-common' package for OTLP JSON exporters
   ([#4996](https://github.com/open-telemetry/opentelemetry-python/pull/4996))
+- `opentelemetry-exporter-otlp-proto-grpc`: make retryable gRPC error codes configurable for gRPC exporters
+  ([#4917](https://github.com/open-telemetry/opentelemetry-python/pull/4917))
 
 ## Version 1.41.0/0.62b0 (2026-04-09)
 

exporter/opentelemetry-exporter-otlp-proto-grpc/src/opentelemetry/exporter/otlp/proto/grpc/_log_exporter/__init__.py

@@ -1,12 +1,12 @@
 # Copyright The OpenTelemetry Authors
 # SPDX-License-Identifier: Apache-2.0
 
-from collections.abc import Sequence
+from collections.abc import Iterable, Sequence
 from collections.abc import Sequence as TypingSequence
 from os import environ
 from typing import Literal
 
-from grpc import ChannelCredentials, Compression
+from grpc import ChannelCredentials, Compression, StatusCode
 from opentelemetry.exporter.otlp.proto.common._log_encoder import encode_logs
 from opentelemetry.exporter.otlp.proto.grpc.exporter import (
     OTLPExporterMixin,
@@ -62,6 +62,7 @@ def __init__(
         timeout: float | None = None,
         compression: Compression | None = None,
         channel_options: tuple[tuple[str, str]] | None = None,
+        retryable_error_codes: Iterable[StatusCode] | None = None,
         *,
         meter_provider: MeterProvider | None = None,
     ):
@@ -103,6 +104,7 @@ def __init__(
             stub=LogsServiceStub,
             result=LogRecordExportResult,
             channel_options=channel_options,
+            retryable_error_codes=retryable_error_codes,
             component_type=OtelComponentTypeValues.OTLP_GRPC_LOG_EXPORTER,
             signal="logs",
             meter_provider=meter_provider,

exporter/opentelemetry-exporter-otlp-proto-grpc/src/opentelemetry/exporter/otlp/proto/grpc/exporter.py

@@ -9,11 +9,13 @@
 
 """
 
+import os
 import random
 import threading
 from abc import ABC, abstractmethod
 from collections.abc import (
     Callable,
+    Iterable,
     Sequence,  # noqa: F401
 )
 from collections.abc import Sequence as TypingSequence
@@ -82,6 +84,7 @@
 from opentelemetry.sdk._shared_internal import DuplicateFilter
 from opentelemetry.sdk.environment_variables import (
     _OTEL_PYTHON_EXPORTER_OTLP_GRPC_CREDENTIAL_PROVIDER,
+    _OTEL_PYTHON_EXPORTER_OTLP_GRPC_RETRYABLE_ERROR_CODES,
     OTEL_EXPORTER_OTLP_CERTIFICATE,
     OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE,
     OTEL_EXPORTER_OTLP_CLIENT_KEY,
@@ -295,6 +298,7 @@ def __init__(
         timeout: float | None = None,
         compression: Compression | None = None,
         channel_options: tuple[tuple[str, str]] | None = None,
+        retryable_error_codes: Iterable[StatusCode] | None = None,
         *,
         component_type: OtelComponentTypeValues | None = None,
         signal: Literal["traces", "metrics", "logs"] = "traces",
@@ -357,6 +361,22 @@ def __init__(
             else compression
         ) or Compression.NoCompression
 
+        self._retryable_error_codes = retryable_error_codes or os.environ.get(
+            _OTEL_PYTHON_EXPORTER_OTLP_GRPC_RETRYABLE_ERROR_CODES
+        )
+        if isinstance(self._retryable_error_codes, str):
+            self._retryable_error_codes = frozenset(
+                StatusCode[code.strip().upper()]
+                for code in self._retryable_error_codes.split(",")
+                if code.strip()
+            )
+        elif self._retryable_error_codes is not None:
+            self._retryable_error_codes = frozenset(
+                self._retryable_error_codes
+            )
+        else:
+            self._retryable_error_codes = _RETRYABLE_ERROR_CODES
+
         self._channel = None
         self._client = None
 
@@ -481,7 +501,7 @@ def _export(
                         self._initialize_channel_and_stub()
 
                     if (
-                        error.code() not in _RETRYABLE_ERROR_CODES  # type: ignore [reportAttributeAccessIssue]
+                        error.code() not in self._retryable_error_codes  # type: ignore [reportAttributeAccessIssue]
                         or retry_num + 1 == _MAX_RETRYS
                         or backoff_seconds > (deadline_sec - time())
                         or self._shutdown

exporter/opentelemetry-exporter-otlp-proto-grpc/src/opentelemetry/exporter/otlp/proto/grpc/metric_exporter/__init__.py

@@ -9,7 +9,7 @@
 from logging import getLogger
 from os import environ
 
-from grpc import ChannelCredentials, Compression
+from grpc import ChannelCredentials, Compression, StatusCode
 from opentelemetry.exporter.otlp.proto.common._internal.metrics_encoder import (
     OTLPMetricExporterMixin,
 )
@@ -105,6 +105,7 @@ def __init__(
         preferred_aggregation: dict[type, Aggregation] | None = None,
         max_export_batch_size: int | None = None,
         channel_options: tuple[tuple[str, str]] | None = None,
+        retryable_error_codes: Iterable[StatusCode] | None = None,
         *,
         meter_provider: MeterProvider | None = None,
     ):
@@ -151,6 +152,7 @@ def __init__(
             timeout=timeout or environ_timeout,
             compression=compression,
             channel_options=channel_options,
+            retryable_error_codes=retryable_error_codes,
             component_type=OtelComponentTypeValues.OTLP_GRPC_METRIC_EXPORTER,
             signal="metrics",
             meter_provider=meter_provider,

exporter/opentelemetry-exporter-otlp-proto-grpc/src/opentelemetry/exporter/otlp/proto/grpc/trace_exporter/__init__.py

@@ -4,11 +4,11 @@
 """OTLP Span Exporter"""
 
 import logging
-from collections.abc import Sequence
+from collections.abc import Iterable, Sequence
 from collections.abc import Sequence as TypingSequence
 from os import environ
 
-from grpc import ChannelCredentials, Compression
+from grpc import ChannelCredentials, Compression, StatusCode
 from opentelemetry.exporter.otlp.proto.common.trace_encoder import (
     encode_spans,
 )
@@ -90,6 +90,7 @@ def __init__(
         timeout: float | None = None,
         compression: Compression | None = None,
         channel_options: tuple[tuple[str, str]] | None = None,
+        retryable_error_codes: Iterable[StatusCode] | None = None,
         *,
         meter_provider: MeterProvider | None = None,
     ):
@@ -132,6 +133,7 @@ def __init__(
             timeout=timeout or environ_timeout,
             compression=compression,
             channel_options=channel_options,
+            retryable_error_codes=retryable_error_codes,
             component_type=OtelComponentTypeValues.OTLP_GRPC_SPAN_EXPORTER,
             signal="traces",
             meter_provider=meter_provider,

exporter/opentelemetry-exporter-otlp-proto-grpc/tests/test_otlp_exporter_mixin.py

@@ -27,6 +27,7 @@
     encode_spans,
 )
 from opentelemetry.exporter.otlp.proto.grpc.exporter import (  # noqa: F401
+    _RETRYABLE_ERROR_CODES,
     InvalidCompressionValueException,
     OTLPExporterMixin,
     environ_to_compression,
@@ -159,7 +160,7 @@ def join(self, timeout: float | None = None) -> Any:
         return self._return
 
 
-# pylint: disable=too-many-public-methods
+# pylint: disable-next=too-many-public-methods
 class TestOTLPExporterMixin(TestCase):
     def setUp(self):
         self.server = server(ThreadPoolExecutor(max_workers=10))
@@ -695,7 +696,72 @@ def test_unavailable_reconnects(self):
         # Since the initial channel was created in setUp (unpatched), this call
         # must be from the reconnection logic.
         self.assertTrue(mock_insecure_channel.called)
-        # Verify that reconnection enabled flag is set
+
+    def test_retryable_error_codes_initialization(self):
+        # pylint: disable=protected-access
+        self.assertEqual(
+            self.exporter._retryable_error_codes, _RETRYABLE_ERROR_CODES
+        )
+        custom_codes = [StatusCode.INTERNAL, StatusCode.UNKNOWN]
+        exporter = OTLPSpanExporterForTesting(
+            insecure=True, retryable_error_codes=custom_codes
+        )
+        self.assertEqual(
+            exporter._retryable_error_codes, frozenset(custom_codes)
+        )
+
+    @patch.dict(
+        "os.environ",
+        {
+            "OTEL_PYTHON_EXPORTER_OTLP_GRPC_RETRYABLE_ERROR_CODES": ",INTERNAL, unknown,,,dEAdline_Exceeded "
+        },
+    )
+    def test_retryable_error_codes_initialization_from_env(self):
+        expected_codes = frozenset(
+            {
+                StatusCode.INTERNAL,
+                StatusCode.UNKNOWN,
+                StatusCode.DEADLINE_EXCEEDED,
+            }
+        )
+        exporter = OTLPSpanExporterForTesting()
+        # pylint: disable=protected-access
+        self.assertEqual(exporter._retryable_error_codes, expected_codes)
+
+    @unittest.skipIf(
+        system() == "Windows",
+        "For gRPC + windows there's some added delay in the RPCs which breaks the assertion over amount of time passed.",
+    )
+    def test_retryable_error_codes_custom(self):
+        # Test that a custom error code is retried if specified
+        custom_codes = [StatusCode.INTERNAL]
+        mock_trace_service = TraceServiceServicerWithExportParams(
+            StatusCode.INTERNAL,
+            optional_retry_nanos=200000000,  # .2 seconds
+        )
+        add_TraceServiceServicer_to_server(
+            mock_trace_service,
+            self.server,
+        )
+        exporter = OTLPSpanExporterForTesting(
+            insecure=True, retryable_error_codes=custom_codes, timeout=10
+        )
+
+        self.assertEqual(
+            exporter.export([self.span]),
+            SpanExportResult.FAILURE,
+        )
+
+        self.assertEqual(mock_trace_service.num_requests, 6)
+
+        # Test that a default retryable code is NOT retried if not in custom_codes
+        mock_trace_service.num_requests = 0
+        mock_trace_service.export_result = StatusCode.UNAVAILABLE
+        self.assertEqual(
+            exporter.export([self.span]),
+            SpanExportResult.FAILURE,
+        )
+        self.assertEqual(mock_trace_service.num_requests, 1)
 
     def assert_standard_metric_attrs(self, attributes):
         self.assertEqual(

opentelemetry-sdk/src/opentelemetry/sdk/environment_variables/__init__.py

@@ -483,6 +483,19 @@ def channel_credential_provider() -> grpc.ChannelCredentials:
 Note: This environment variable is experimental and subject to change.
 """
 
+_OTEL_PYTHON_EXPORTER_OTLP_GRPC_RETRYABLE_ERROR_CODES = (
+    "OTEL_PYTHON_EXPORTER_OTLP_GRPC_RETRYABLE_ERROR_CODES"
+)
+"""
+.. envvar:: OTEL_PYTHON_EXPORTER_OTLP_GRPC_RETRYABLE_ERROR_CODES
+
+The :envvar:`OTEL_PYTHON_EXPORTER_OTLP_GRPC_RETRYABLE_ERROR_CODES` stores a comma-separated list of human-readable
+gRPC error codes that are considered retryable for the OTLP gRPC exporters (e.g. `UNAVAILABLE, DEADLINE_EXCEEDED`).
+Supported error codes are defined in `grpc.StatusCode` and are parsed in a case-insensitive manner.
+
+Note: This environment variable is experimental and subject to change.
+"""
+
 OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE = "OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE"
 """
 .. envvar:: OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE