PYTHON-5947 Add OpenTelemetry operation spans

.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 keeps every task: 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"],

.github/workflows/test-python.yml

@@ -305,3 +305,36 @@ jobs:
             source .venv/bin/activate
             uv pip install -e ".[test]" --resolution=lowest-direct --force-reinstall
             pytest -v test/test_srv_polling.py test/test_dns.py test/asynchronous/test_srv_polling.py test/asynchronous/test_dns.py
+
+  # TEMPORARY, remove before merging the PYTHON-5947 stack.
+  #
+  # Evergreen only runs on PRs whose base is a configured branch, so the upper
+  # PRs in this stack (based on each other rather than on otel) get no Evergreen
+  # coverage at all, and the otel tests only run in Evergreen's otel variant.
+  # This job runs them on every branch in the stack instead. A replica set is
+  # requested because the transaction span tests require one. Actions are pinned
+  # to commit hashes here, unlike the rest of this file, to satisfy the
+  # mutable-action-tag scanners on newly added lines.
+  otel:
+    runs-on: ubuntu-latest
+    name: OTel Tests (temporary)
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          python-version: "3.11"
+      - id: setup-mongodb
+        uses: mongodb-labs/drivers-evergreen-tools@c70d29e2102cd048ad800932209776499553870c # v1.0.1
+        with:
+          version: "8.0"
+          topology: "replica_set"
+      - name: Install just
+        run: uv tool install rust-just
+      - name: Setup tests
+        run: TEST_NAME=otel just setup-tests
+      - name: Run tests
+        run: just run-tests

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