PYTHON-5947 Add OpenTelemetry operation spans

Give every public API call an operation span containing one command span
per command sent to the server, per the OpenTelemetry driver specification.

The span covers all retry attempts of one _retry_internal call, so retries
appear as sibling command spans rather than being collapsed into one.
killCursors and endSessions bypass the retry layer and start their spans at
the call site instead, as does an unacknowledged client bulk write, which
never reaches the command-span code that would fill in its namespace.

Cursor-creating operations (find, aggregate, listCollections, listIndexes)
are covered here, but only for the command that creates the cursor. Spans
for caller-driven getMores come in a later change, as do transaction spans.

_otel.py also takes over the specification's naming and attribute rules, so
_telemetry.py deals only with span lifecycles and a specification change
need not touch it. Namespace parsing moves to helpers_shared._split_namespace.

Author: blink1073

.evergreen/generated_configs/variants.yml

@@ -445,7 +445,10 @@ buildvariants:
   # Otel tests
   - name: otel-rhel8
     tasks:
-      - name: .test-non-standard .standalone-noauth-nossl
+      - name: .test-non-standard .replica_set-noauth-ssl
+      - name: .test-non-standard .sharded_cluster-auth-ssl .python-3.14
+      - name: .test-non-standard .sharded_cluster-auth-ssl .python-pypy3.11
+      - name: .test-non-standard .standalone-noauth-nossl .python-3.10
     display_name: OTel RHEL8
     run_on:
       - rhel87-small

.evergreen/scripts/generate_config.py

@@ -458,7 +458,23 @@ def create_otel_variants():
     expansions = dict(TEST_NAME="otel", COVERAGE="1")
     return [
         create_variant(
-            [".test-non-standard .standalone-noauth-nossl"],
+            [
+                # All three topologies, subset to keep the task count at 22.
+                #
+                # Replica set in full: the only topology where transaction spans
+                # run at all (they are skipped on standalone and sharded), and
+                # the only one covering free-threaded Python.
+                ".test-non-standard .replica_set-noauth-ssl",
+                # Sharded adds mongos, which rewrites commands and reports a
+                # different server.address, plus auth and ssl, which exercise
+                # sensitive-command redaction. Newest CPython across server
+                # versions, and PyPy for the alternate implementation.
+                ".test-non-standard .sharded_cluster-auth-ssl .python-3.14",
+                ".test-non-standard .sharded_cluster-auth-ssl .python-pypy3.11",
+                # Standalone only for its min-deps tasks, which resolve
+                # opentelemetry-api down to the floor in requirements/.
+                ".test-non-standard .standalone-noauth-nossl .python-3.10",
+            ],
             get_variant_name("OTel", host),
             host=host,
             tags=["pr"],

bson/json_util.py

@@ -1115,20 +1115,18 @@ def _truncate_documents(obj: Any, max_length: int) -> tuple[Any, int]:
     if hasattr(obj, "items"):
         truncated: Any = {}
         for k, v in obj.items():
-            truncated_v, remaining = _truncate_documents(v, remaining)
-            if truncated_v:
-                truncated[k] = truncated_v
             if remaining <= 0:
                 break
+            truncated_v, remaining = _truncate_documents(v, remaining)
+            truncated[k] = truncated_v
         return truncated, remaining
     elif hasattr(obj, "__iter__") and not isinstance(obj, (str, bytes)):
         truncated: Any = []  # type:ignore[no-redef]
         for v in obj:
-            truncated_v, remaining = _truncate_documents(v, remaining)
-            if truncated_v:
-                truncated.append(truncated_v)
             if remaining <= 0:
                 break
+            truncated_v, remaining = _truncate_documents(v, remaining)
+            truncated.append(truncated_v)
         return truncated, remaining
     else:
         return _truncate(obj, remaining)

doc/changelog.rst

@@ -29,11 +29,14 @@ PyMongo 4.18 brings a number of changes including:
   attempts, so consumers can correlate a retried operation's events. As a
   result, ``operation_id`` is no longer equal to the per-attempt ``request_id``
   for these operations.
-- Added optional OpenTelemetry command-span support, conforming to the
+- Added optional OpenTelemetry tracing support, conforming to the
   `OpenTelemetry driver specification <https://github.com/mongodb/specifications/blob/master/source/open-telemetry/open-telemetry.md>`_.
-  Enable it with the ``tracing`` :class:`~pymongo.mongo_client.MongoClient`
-  option or the ``OTEL_PYTHON_INSTRUMENTATION_MONGODB_ENABLED`` environment
-  variable. Install the ``opentelemetry-api`` package, or use the
+  Every public API call produces an operation span, which contains one span
+  per command sent to the server. Inside a transaction, those operation spans
+  nest under a ``transaction`` span. Enable it with the
+  ``tracing`` :class:`~pymongo.mongo_client.MongoClient` option or the
+  ``OTEL_PYTHON_INSTRUMENTATION_MONGODB_ENABLED`` environment variable.
+  Install the ``opentelemetry-api`` package, or use the
   ``pymongo[opentelemetry]`` extra, to enable this feature.
 - Fixed a potential out-of-bounds read in the C extension when decoding an
   array of BSON documents. An embedded document whose declared length exceeds