Handle HTTP 413 responses in OTLP HTTP exporters by splitting and retrying

When a backend returns HTTP 413 (Payload Too Large), the trace and log
exporters now split the batch in half and recursively retry each half.
This prevents silent data loss when batch sizes exceed backend limits.

The splitting includes deadline guards to prevent infinite recursion,
short-circuits on first-half failure to avoid wasting time on the
second half, and drops individual items that are genuinely too large.

Fixes #4533

Author: Krishnachaitanyakc

exporter/opentelemetry-exporter-otlp-proto-http/src/opentelemetry/exporter/otlp/proto/http/_common/__init__.py

@@ -31,6 +31,10 @@ def _is_retryable(resp: requests.Response) -> bool:
     return False
 
 
+def _is_payload_too_large(resp: requests.Response) -> bool:
+    return resp.status_code == 413
+
+
 def _load_session_from_envvar(
     cred_envvar: Literal[
         "OTEL_PYTHON_EXPORTER_OTLP_HTTP_LOGS_CREDENTIAL_PROVIDER",

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

@@ -31,6 +31,7 @@
     Compression,
 )
 from opentelemetry.exporter.otlp.proto.http._common import (
+    _is_payload_too_large,
     _is_retryable,
     _load_session_from_envvar,
 )
@@ -183,8 +184,14 @@ def export(
             _logger.warning("Exporter already shutdown, ignoring batch")
             return LogRecordExportResult.FAILURE
 
-        serialized_data = encode_logs(batch).SerializeToString()
         deadline_sec = time() + self._timeout
+        return self._export_batch(batch, deadline_sec)
+
+    def _export_batch(
+        self, batch: Sequence[ReadableLogRecord], deadline_sec: float
+    ) -> LogRecordExportResult:
+        serialized_data = encode_logs(batch).SerializeToString()
+
         for retry_num in range(_MAX_RETRYS):
             # multiplying by a random number between .8 and 1.2 introduces a +/20% jitter to each backoff.
             backoff_seconds = 2**retry_num * random.uniform(0.8, 1.2)
@@ -201,6 +208,35 @@ def export(
                 retryable = _is_retryable(resp)
                 status_code = resp.status_code
 
+                if _is_payload_too_large(resp):
+                    # 413 handling always returns here; will not fall through
+                    # to the 'if not retryable' check below.
+                    if len(batch) <= 1:
+                        _logger.error(
+                            "Single log record exceeds backend payload size limit, dropping log record"
+                        )
+                        return LogRecordExportResult.FAILURE
+                    if time() >= deadline_sec:
+                        _logger.error(
+                            "Payload too large but deadline expired, dropping %d log records",
+                            len(batch),
+                        )
+                        return LogRecordExportResult.FAILURE
+                    mid = len(batch) // 2
+                    _logger.warning(
+                        "Payload too large (%d log records), splitting into two batches",
+                        len(batch),
+                    )
+                    first = self._export_batch(
+                        list(batch[:mid]), deadline_sec
+                    )
+                    if first != LogRecordExportResult.SUCCESS:
+                        return LogRecordExportResult.FAILURE
+                    second = self._export_batch(
+                        list(batch[mid:]), deadline_sec
+                    )
+                    return second
+
             if not retryable:
                 _logger.error(
                     "Failed to export logs batch code: %s, reason: %s",

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

@@ -33,6 +33,7 @@
     Compression,
 )
 from opentelemetry.exporter.otlp.proto.http._common import (
+    _is_payload_too_large,
     _is_retryable,
     _load_session_from_envvar,
 )
@@ -176,8 +177,14 @@ def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
             _logger.warning("Exporter already shutdown, ignoring batch")
             return SpanExportResult.FAILURE
 
-        serialized_data = encode_spans(spans).SerializePartialToString()
         deadline_sec = time() + self._timeout
+        return self._export_batch(spans, deadline_sec)
+
+    def _export_batch(
+        self, spans: Sequence[ReadableSpan], deadline_sec: float
+    ) -> SpanExportResult:
+        serialized_data = encode_spans(spans).SerializePartialToString()
+
         for retry_num in range(_MAX_RETRYS):
             # multiplying by a random number between .8 and 1.2 introduces a +/20% jitter to each backoff.
             backoff_seconds = 2**retry_num * random.uniform(0.8, 1.2)
@@ -194,6 +201,35 @@ def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
                 retryable = _is_retryable(resp)
                 status_code = resp.status_code
 
+                if _is_payload_too_large(resp):
+                    # 413 handling always returns here; will not fall through
+                    # to the 'if not retryable' check below.
+                    if len(spans) <= 1:
+                        _logger.error(
+                            "Single span exceeds backend payload size limit, dropping span"
+                        )
+                        return SpanExportResult.FAILURE
+                    if time() >= deadline_sec:
+                        _logger.error(
+                            "Payload too large but deadline expired, dropping %d spans",
+                            len(spans),
+                        )
+                        return SpanExportResult.FAILURE
+                    mid = len(spans) // 2
+                    _logger.warning(
+                        "Payload too large (%d spans), splitting into two batches",
+                        len(spans),
+                    )
+                    first = self._export_batch(
+                        list(spans[:mid]), deadline_sec
+                    )
+                    if first != SpanExportResult.SUCCESS:
+                        return SpanExportResult.FAILURE
+                    second = self._export_batch(
+                        list(spans[mid:]), deadline_sec
+                    )
+                    return second
+
             if not retryable:
                 _logger.error(
                     "Failed to export span batch code: %s, reason: %s",

exporter/opentelemetry-exporter-otlp-proto-http/tests/test_proto_log_exporter.py

@@ -562,3 +562,136 @@ def test_shutdown_interrupts_retry_backoff(self, mock_post):
             )
 
             assert after - before < 0.2
+
+    @patch.object(Session, "post")
+    def test_413_splits_batch_and_succeeds(self, mock_post):
+        """When backend returns 413, the exporter should split the batch in half and retry each half."""
+        exporter = OTLPLogExporter(timeout=10)
+
+        resp_413 = Response()
+        resp_413.status_code = 413
+        resp_413.reason = "Request Entity Too Large"
+
+        resp_ok = Response()
+        resp_ok.status_code = 200
+
+        mock_post.side_effect = [resp_413, resp_ok, resp_ok]
+
+        log_data = self._get_sdk_log_data()
+
+        with self.assertLogs(level=WARNING) as warning:
+            result = exporter.export(log_data)
+
+        self.assertEqual(result, LogRecordExportResult.SUCCESS)
+        # 1 initial call (413) + 2 split calls
+        self.assertEqual(mock_post.call_count, 3)
+        self.assertTrue(
+            any(
+                "Payload too large" in record.message
+                for record in warning.records
+            )
+        )
+
+    @patch.object(Session, "post")
+    def test_413_single_log_returns_failure(self, mock_post):
+        """When a single log record is too large, the exporter should return FAILURE."""
+        exporter = OTLPLogExporter(timeout=10)
+
+        resp_413 = Response()
+        resp_413.status_code = 413
+        resp_413.reason = "Request Entity Too Large"
+
+        mock_post.return_value = resp_413
+
+        log_data = self._get_sdk_log_data()[:1]
+
+        with self.assertLogs(level=WARNING) as warning:
+            result = exporter.export(log_data)
+
+        self.assertEqual(result, LogRecordExportResult.FAILURE)
+        self.assertEqual(mock_post.call_count, 1)
+        self.assertTrue(
+            any(
+                "Single log record exceeds backend payload size limit"
+                in record.message
+                for record in warning.records
+            )
+        )
+
+    @patch.object(Session, "post")
+    def test_413_recursive_splitting(self, mock_post):
+        """When a split half still returns 413, the exporter should continue splitting recursively."""
+        exporter = OTLPLogExporter(timeout=10)
+
+        resp_413 = Response()
+        resp_413.status_code = 413
+        resp_413.reason = "Request Entity Too Large"
+
+        resp_ok = Response()
+        resp_ok.status_code = 200
+
+        log_data = self._get_sdk_log_data()  # returns 3 logs
+
+        # 3 logs: first 413 → split [0],[1,2]
+        # [0] → ok
+        # [1,2] → 413 → split [1],[2] → ok, ok
+        mock_post.side_effect = [resp_413, resp_ok, resp_413, resp_ok, resp_ok]
+
+        with self.assertLogs(level=WARNING):
+            result = exporter.export(log_data)
+
+        self.assertEqual(result, LogRecordExportResult.SUCCESS)
+        self.assertEqual(mock_post.call_count, 5)
+
+    @patch.object(Session, "post")
+    def test_413_partial_failure(self, mock_post):
+        """When the first half fails with a non-retryable error, the second half is not attempted (short-circuit)."""
+        exporter = OTLPLogExporter(timeout=10)
+
+        resp_413 = Response()
+        resp_413.status_code = 413
+        resp_413.reason = "Request Entity Too Large"
+
+        resp_400 = Response()
+        resp_400.status_code = 400
+        resp_400.reason = "Bad Request"
+
+        log_data = self._get_sdk_log_data()
+
+        # First call returns 413, first half gets 400 → short-circuit
+        mock_post.side_effect = [resp_413, resp_400]
+
+        with self.assertLogs(level=WARNING):
+            result = exporter.export(log_data)
+
+        self.assertEqual(result, LogRecordExportResult.FAILURE)
+        self.assertEqual(mock_post.call_count, 2)
+
+    @patch(
+        "opentelemetry.exporter.otlp.proto.http._log_exporter.time",
+    )
+    @patch.object(Session, "post")
+    def test_413_deadline_expired_returns_failure(self, mock_post, mock_time):
+        """When a 413 is received but the deadline has expired, return FAILURE without splitting."""
+        mock_time.side_effect = [100.0, 100.0, 100.6]
+        exporter = OTLPLogExporter(timeout=0.5)
+
+        resp_413 = Response()
+        resp_413.status_code = 413
+        resp_413.reason = "Request Entity Too Large"
+
+        mock_post.return_value = resp_413
+
+        log_data = self._get_sdk_log_data()
+
+        with self.assertLogs(level=WARNING) as warning:
+            result = exporter.export(log_data)
+
+        self.assertEqual(result, LogRecordExportResult.FAILURE)
+        self.assertEqual(mock_post.call_count, 1)
+        self.assertTrue(
+            any(
+                "deadline expired" in record.message
+                for record in warning.records
+            )
+        )