fix: use negative limit for traceback.print_exception() (#12705)

Since `traceback.print_exception()` prints the exception with the "most
recent call last" format, while using a positive integer for the limit
parameter, our `error.stack` tag will be trimmed on the most interesting
part if trimming is needed.

By switching to a negative number (introduced in Python 3.5), the
traceback will be trimmed on the other side, see relevant docs:
https://docs.python.org/3/library/traceback.html#traceback.print_tb

Screenshot of the bug in action:

![screenshot_2025-03-12_at_12 47
46](https://github.com/user-attachments/assets/18d3dbbd-eb02-4289-9ac8-3f5a54d12161)


## Checklist
- [x] PR author has checked that all the criteria below are met
- The PR description includes an overview of the change
- The PR description articulates the motivation for the change
- The change includes tests OR the PR description describes a testing
strategy
- The PR description notes risks associated with the change, if any
- Newly-added code is easy to change
- The change follows the [library release note
guidelines](https://ddtrace.readthedocs.io/en/stable/releasenotes.html)
- The change includes or references documentation updates if necessary
- Backport labels are set (if
[applicable](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting))

## Reviewer Checklist
- [x] Reviewer has checked that all the criteria below are met 
- Title is accurate
- All changes are related to the pull request's stated goal
- Avoids breaking
[API](https://ddtrace.readthedocs.io/en/stable/versioning.html#interfaces)
changes
- Testing strategy adequately addresses listed risks
- Newly-added code is easy to change
- Release note makes sense to a user of the library
- If necessary, author has acknowledged and discussed the performance
implications of this PR as reported in the benchmarks PR comment
- Backport labels are set in a manner that is consistent with the
[release branch maintenance
policy](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting)

Author: gnufede

ddtrace/_trace/span.py

@@ -16,6 +16,7 @@
 from typing import cast
 
 from ddtrace import config
+from ddtrace._trace._limits import MAX_SPAN_META_VALUE_LEN
 from ddtrace._trace._span_link import SpanLink
 from ddtrace._trace._span_link import SpanLinkKind
 from ddtrace._trace._span_pointer import _SpanPointer
@@ -500,19 +501,68 @@ def set_traceback(self, limit: Optional[int] = None):
         """If the current stack has an exception, tag the span with the
         relevant error info. If not, tag it with the current python stack.
         """
-        if limit is None:
-            limit = config._span_traceback_max_size
-
         (exc_type, exc_val, exc_tb) = sys.exc_info()
 
         if exc_type and exc_val and exc_tb:
-            self.set_exc_info(exc_type, exc_val, exc_tb)
+            if limit:
+                limit = -abs(limit)
+            self.set_exc_info(exc_type, exc_val, exc_tb, limit=limit)
         else:
+            if limit is None:
+                limit = config._span_traceback_max_size
             tb = "".join(traceback.format_stack(limit=limit + 1)[:-1])
             self._meta[ERROR_STACK] = tb
 
+    def _get_traceback(
+        self,
+        exc_type: Type[BaseException],
+        exc_val: BaseException,
+        exc_tb: Optional[TracebackType],
+        limit: Optional[int] = None,
+    ) -> str:
+        """
+        Return a formatted traceback as a string.
+        If the traceback is too long, it will be truncated to the limit parameter,
+        but from the end of the traceback (keeping the most recent frames).
+
+        If the traceback surpasses the MAX_SPAN_META_VALUE_LEN limit, it will
+        try to reduce the traceback size by half until it fits
+        within this limit (limit for tag values).
+
+        :param exc_type: the exception type
+        :param exc_val: the exception value
+        :param exc_tb: the exception traceback
+        :param limit: the maximum number of frames to keep
+        :return: the formatted traceback as a string
+        """
+        # If limit is None, use the default value from the configuration
+        if limit is None:
+            limit = config._span_traceback_max_size
+        # Ensure the limit is negative for traceback.print_exception (to keep most recent frames)
+        limit: int = -abs(limit)  # type: ignore[no-redef]
+
+        # Create a buffer to hold the traceback
+        buff = StringIO()
+        # Print the exception traceback to the buffer with the specified limit
+        traceback.print_exception(exc_type, exc_val, exc_tb, file=buff, limit=limit)
+        tb = buff.getvalue()
+
+        # Check if the traceback exceeds the maximum allowed length
+        while len(tb) > MAX_SPAN_META_VALUE_LEN and abs(limit) > 1:
+            # Reduce the limit by half and print the traceback again
+            limit //= 2
+            buff = StringIO()
+            traceback.print_exception(exc_type, exc_val, exc_tb, file=buff, limit=limit)
+            tb = buff.getvalue()
+
+        return tb
+
     def set_exc_info(
-        self, exc_type: Type[BaseException], exc_val: BaseException, exc_tb: Optional[TracebackType]
+        self,
+        exc_type: Type[BaseException],
+        exc_val: BaseException,
+        exc_tb: Optional[TracebackType],
+        limit: Optional[int] = None,
     ) -> None:
         """Tag the span with an error tuple as from `sys.exc_info()`."""
         if not (exc_type and exc_val and exc_tb):
@@ -527,10 +577,7 @@ def set_exc_info(
 
         self.error = 1
 
-        # get the traceback
-        buff = StringIO()
-        traceback.print_exception(exc_type, exc_val, exc_tb, file=buff, limit=config._span_traceback_max_size)
-        tb = buff.getvalue()
+        tb = self._get_traceback(exc_type, exc_val, exc_tb, limit=limit)
 
         # readable version of type (e.g. exceptions.ZeroDivisionError)
         exc_type_str = "%s.%s" % (exc_type.__module__, exc_type.__name__)
@@ -579,10 +626,7 @@ def record_exception(
         if escaped:
             self.set_exc_info(exc_type, exc_val, exc_tb)
 
-        # get the traceback
-        buff = StringIO()
-        traceback.print_exception(exc_type, exc_val, exc_tb, file=buff, limit=config._span_traceback_max_size)
-        tb = buff.getvalue()
+        tb = self._get_traceback(exc_type, exc_val, exc_tb)
 
         # Set exception attributes in a manner that is consistent with the opentelemetry sdk
         # https://github.com/open-telemetry/opentelemetry-python/blob/v1.24.0/opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py#L998

releasenotes/notes/fix-traceback-in-span-a9481b15907d9887.yaml

@@ -0,0 +1,4 @@
+---
+fixes:
+  - |
+    internal: Fixes an issue where trimming a traceback to attach it to the span could result in the loss of the most recent frames.

tests/tracer/test_span.py

@@ -3,6 +3,7 @@
 import re
 import sys
 import time
+import traceback
 from unittest.case import SkipTest
 
 import mock
@@ -19,6 +20,7 @@
 from ddtrace.constants import VERSION_KEY
 from ddtrace.ext import SpanTypes
 from ddtrace.internal import core
+from ddtrace.internal.compat import PYTHON_VERSION_INFO
 from ddtrace.trace import Span
 from tests.subprocesstest import run_in_subprocess
 from tests.utils import TracerTestCase
@@ -286,11 +288,21 @@ def wrapper():
             assert stack, "No error stack collected"
             # one header "Traceback (most recent call last):" and one footer "ZeroDivisionError: division by zero"
             header_and_footer_lines = 2
-            # Python 3.13 adds extra lines to the traceback:
-            #   File dd-trace-py/tests/tracer/test_span.py", line 279, in test_custom_traceback_size_with_error
-            #     wrapper()
-            #     ~~~~~~~^^
-            multiplier = 3 if "~~" in stack else 2
+            multiplier = 2
+            if PYTHON_VERSION_INFO >= (3, 13):
+                # Python 3.13 adds extra lines to the traceback:
+                #   File dd-trace-py/tests/tracer/test_span.py", line 279, in test_custom_traceback_size_with_error
+                #     wrapper()
+                #     ~~~~~~~^^
+                multiplier = 3
+            elif PYTHON_VERSION_INFO >= (3, 11):
+                # Python 3.11 adds one extra line to the traceback:
+                #   File dd-trace-py/tests/tracer/test_span.py", line 272, in divide_by_zero
+                #      1 / 0
+                #      ~~^~~
+                #      ZeroDivisionError: division by zero
+                header_and_footer_lines += 1
+
             assert (
                 len(stack.splitlines()) == tb_length_limit * multiplier + header_and_footer_lines
             ), "stacktrace should contain two lines per entry"
@@ -954,3 +966,81 @@ def _(span, *exc_info):
         raise AssertionError("should have raised")
     finally:
         core.reset_listeners("span.exception")
+
+
+def test_get_traceback_exceeds_max_value_length():
+    """Test with a long traceback that should be truncated."""
+
+    def deep_error(n):
+        if n > 0:
+            deep_error(n - 1)
+        else:
+            raise RuntimeError("Deep recursion error")
+
+    exc_type, exc_val, exc_tb = None, None, None
+    try:
+        deep_error(100)  # Create a large traceback
+    except Exception as e:
+        exc_type, exc_val, exc_tb = e.__class__, e, e.__traceback__
+
+    span = Span("test.span")
+    with mock.patch("ddtrace._trace.span.MAX_SPAN_META_VALUE_LEN", 260):
+        result = span._get_traceback(exc_type, exc_val, exc_tb, limit=100)
+    assert "Deep recursion error" in result
+    assert len(result) <= 260  # Should be truncated
+
+
+def test_get_traceback_exact_limit():
+    """Test a case where the traceback length is exactly at the limit."""
+
+    def deep_error(n):
+        if n > 0:
+            deep_error(n - 1)
+        else:
+            raise RuntimeError("Deep recursion error")
+
+    exc_type, exc_val, exc_tb = None, None, None
+    try:
+        deep_error(100)  # Create a large traceback
+    except Exception as e:
+        exc_type, exc_val, exc_tb = e.__class__, e, e.__traceback__
+
+    span = Span("test.span")
+    formatted_exception = traceback.format_exception(exc_type, exc_val, exc_tb)
+    formatted_exception = [s + "\n" for item in formatted_exception for s in item.split("\n") if s]
+    exc_len = len(formatted_exception)
+    result = span._get_traceback(exc_type, exc_val, exc_tb, limit=exc_len)
+    split_result = result.splitlines()
+    split_result = [s + "\n" for item in split_result for s in item.split("\n") if s]
+
+    if PYTHON_VERSION_INFO >= (3, 11):
+        exc_len -= 1  # From Python 3.11, adds an extra line to the traceback
+
+    assert len(split_result) == exc_len - 2  # Should be exactly the same length as the traceback
+
+
+def test_get_traceback_honors_config_traceback_max_size():
+    class CustomConfig:
+        _span_traceback_max_size = 2  # Force a zero limit
+
+    def deep_error(n):
+        if n > 0:
+            deep_error(n - 1)
+        else:
+            raise RuntimeError("Deep recursion error")
+
+    exc_type, exc_val, exc_tb = None, None, None
+    try:
+        deep_error(100)  # Create a large traceback
+    except Exception as e:
+        exc_type, exc_val, exc_tb = e.__class__, e, e.__traceback__
+
+    span = Span("test.span")
+    with mock.patch("ddtrace._trace.span.config", CustomConfig):
+        result = span._get_traceback(exc_type, exc_val, exc_tb)
+
+    assert isinstance(result, str)
+    split_result = result.splitlines()
+    split_result = [s + "\n" for item in split_result for s in item.split("\n") if s]
+    assert len(split_result) < 8  # Value is 5 for Python 3.10
+    assert len(result) < 410  # Value is 377 for Python 3.10