fix(internal): introduce better error logging when we cannot pack a span [backport #5797 to 1.12] (#5806)

Backport of #5797 to 1.12

If we end up with a meta value that is not a string it can raise a
cryptic error that doesn't help deubgging.

This change introduces a new error message that includes the
`repr(span)` that caused the issue.

This change will *not* include the meta for the span, but having the
span name should help narrow things down.

## Checklist

- [x] Change(s) are motivated and described in the PR description.
- [x] Testing strategy is described if automated tests are not included
in the PR.
- [x] Risk is outlined (performance impact, potential for breakage,
maintainability, etc).
- [x] Change is maintainable (easy to change, telemetry, documentation).
- [x] [Library release note
guidelines](https://ddtrace.readthedocs.io/en/stable/contributing.html#Release-Note-Guidelines)
are followed.
- [x] Documentation is included (in-code, generated user docs, [public
corp docs](https://github.com/DataDog/documentation/)).
- [x] PR description includes explicit acknowledgement/acceptance of the
performance implications of this PR as reported in the benchmarks PR
comment.

## Reviewer Checklist

- [x] Title is accurate.
- [x] No unnecessary changes are introduced.
- [x] Description motivates each change.
- [x] Avoids breaking
[API](https://ddtrace.readthedocs.io/en/stable/versioning.html#interfaces)
changes unless absolutely necessary.
- [x] Testing strategy adequately addresses listed risk(s).
- [x] Change is maintainable (easy to change, telemetry, documentation).
- [x] Release note makes sense to a user of the library.
- [x] Reviewer has explicitly acknowledged and discussed the performance
implications of this PR as reported in the benchmarks PR comment.

Author: brettlangdon

ddtrace/internal/_encoding.pyx

@@ -474,8 +474,14 @@ cdef class MsgpackEncoderBase(BufferedEncoder):
             dd_origin = self.get_dd_origin_ref(trace[0].context.dd_origin)
 
         for span in trace:
-            ret = self.pack_span(span, dd_origin)
-            if ret != 0: raise RuntimeError("Couldn't pack span")
+            try:
+                ret = self.pack_span(span, dd_origin)
+            except Exception as e:
+                raise RuntimeError("failed to pack span: {!r}. Exception: {}".format(span, e))
+
+            # No exception was raised, but we got an error code from msgpack
+            if ret != 0:
+                raise RuntimeError("couldn't pack span: {!r}".format(span))
 
         return ret
 

releasenotes/notes/fix-encoding-exception-ff50914f97554744.yaml

@@ -0,0 +1,3 @@
+fixes:
+  - |
+    tracing: Fixes a cryptic encoding exception message when a span tag is not a string.

tests/tracer/test_encoders.py

@@ -1,4 +1,5 @@
 # -*- coding: utf-8 -*-
+import contextlib
 import json
 import random
 import string
@@ -648,6 +649,11 @@ def test_list_string_table():
     assert list(t) == ["", "foobar", "foobaz"]
 
 
+@contextlib.contextmanager
+def _value():
+    yield "value"
+
+
 @pytest.mark.parametrize(
     "data",
     [
@@ -661,6 +667,8 @@ def test_list_string_table():
         {"duration_ns": "duration_time"},
         {"span_type": 100},
         {"_meta": {"num": 100}},
+        # Validating behavior with a context manager is a customer regression
+        {"_meta": {"key": _value()}},
         {"_metrics": {"key": "value"}},
     ],
 )
@@ -672,9 +680,10 @@ def test_encoding_invalid_data(data):
         setattr(span, key, value)
 
     trace = [span]
-    with pytest.raises(TypeError):
+    with pytest.raises(RuntimeError) as e:
         encoder.put(trace)
 
+    assert e.match(r"failed to pack span: <Span\(id="), e
     assert encoder.encode() is None