tests and doc

Author: antonpirker

sentry_sdk/api.py

@@ -479,10 +479,43 @@ def set_transaction_name(name, source=None):
 def update_current_span(op=None, name=None, attributes=None):
     # type: (Optional[str], Optional[str], Optional[dict[str, Union[str, int, float, bool]]]) -> None
     """
-    Update the current span with the given parameters.
-    :param op: The operation of the span.
-    :param name: The name of the span.
-    :param attributes: The attributes of the span.
+    Update the current active span with the provided parameters.
+
+    This function allows you to modify properties of the currently active span.
+    If no span is currently active, this function will do nothing.
+
+    :param op: The operation name for the span. This is a high-level description
+        of what the span represents (e.g., "http.client", "db.query").
+        You can use predefined constants from :py:class:`sentry_sdk.consts.OP`
+        or provide your own string. If not provided, the span's operation will
+        remain unchanged.
+    :type op: str or None
+
+    :param name: The human-readable name/description for the span. This provides
+        more specific details about what the span represents (e.g., "GET /api/users",
+        "SELECT * FROM users"). If not provided, the span's name will remain unchanged.
+    :type name: str or None
+
+    :param attributes: A dictionary of key-value pairs to add as attributes to the span.
+        Attribute values must be strings, integers, floats, or booleans. These
+        attributes will be merged with any existing span data. If not provided,
+        no attributes will be added.
+    :type attributes: dict[str, Union[str, int, float, bool]] or None
+
+    :returns: None
+
+    .. versionadded:: 2.0.0
+
+    Example::
+
+        import sentry_sdk
+        from sentry_sdk.consts import OP
+
+        sentry_sdk.update_current_span(
+            op=OP.FUNCTION,
+            name="process_user_data",
+            attributes={"user_id": 123, "batch_size": 50}
+        )
     """
     current_span = get_current_span()
 

tests/tracing/test_misc.py

@@ -540,3 +540,48 @@ def test_span_set_data_update_data(sentry_init, capture_events):
         "thread.id": mock.ANY,
         "thread.name": mock.ANY,
     }
+
+
+def test_update_current_span(sentry_init, capture_events):
+    sentry_init(traces_sample_rate=1.0)
+
+    events = capture_events()
+
+    with sentry_sdk.start_transaction(name="test-transaction"):
+        with start_span(op="test-span-op", name="test-span-name"):
+            sentry_sdk.update_current_span(
+                op="updated-span-op",
+                name="updated-span-name",
+                attributes={
+                    "key0": "value0",
+                    "key1": "value1",
+                },
+            )
+
+            sentry_sdk.update_current_span(
+                op="updated-span-op-2",
+            )
+
+            sentry_sdk.update_current_span(
+                name="updated-span-name-3",
+            )
+
+            sentry_sdk.update_current_span(
+                attributes={
+                    "key1": "updated-value-4",
+                    "key2": "value2",
+                },
+            )
+
+    (event,) = events
+    span = event["spans"][0]
+
+    assert span["op"] == "updated-span-op-2"
+    assert span["description"] == "updated-span-name-3"
+    assert span["data"] == {
+        "key0": "value0",
+        "key1": "updated-value-4",
+        "key2": "value2",
+        "thread.id": mock.ANY,
+        "thread.name": mock.ANY,
+    }