apidocs

Author: antonpirker

sentry_sdk/tracing.py

@@ -1358,13 +1358,65 @@ def trace(
 ):
     # type: (Optional[Callable[P, R]], SPANTEMPLATE, Optional[str], Optional[str], Optional[dict[str, Any]]) -> Union[Callable[P, R], Callable[[Callable[P, R]], Callable[P, R]]]
     """
-    Decorator to start a child span.
+    Decorator to start a child span around a function call.
+
+    This decorator automatically creates a new span when the decorated function
+    is called, and finishes the span when the function returns or raises an exception.
+
+    :param func: The function to trace. When used as a decorator without parentheses,
+        this is the function being decorated. When used with parameters (e.g.,
+        ``@trace(op="custom")``, this should be None.
+    :type func: Callable or None
+
+    :param template: The type of span to create. This determines what kind of
+        span instrumentation and data collection will be applied. Use predefined
+        constants from :py:class:`sentry_sdk.consts.SPANTEMPLATE`.
+        The default is `SPANTEMPLATE.SPAN` which is the right choice for most
+        use cases.
+    :type template: :py:class:`sentry_sdk.consts.SPANTEMPLATE`
+
+    :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, a default operation will
+        be assigned based on the template.
+    :type op: str or None
+
+    :param name: The human-readable name/description for the span. If not provided,
+        defaults to the function name. This provides more specific details about
+        what the span represents (e.g., "GET /api/users", "process_user_data").
+    :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 provide additional context about the span's execution.
+    :type attributes: dict[str, Any] or None
+
+    :returns: When used as ``@trace``, returns the decorated function. When used as
+        ``@trace(...)`` with parameters, returns a decorator function.
+    :rtype: Callable or decorator function
+
+    Example::
+
+        import sentry_sdk
+        from sentry_sdk.consts import OP, SPANTEMPLATE
+
+        # Simple usage with default template
+        @sentry_sdk.trace
+        def process_data():
+            # Function implementation
+            pass
 
-    :param func: The function to trace.
-    :param template: The type of span to create.
-    :param op: The operation of the span.
-    :param name: The name of the span. (defaults to the function name)
-    :param attributes: Additional attributes to set on the span.
+        # With custom parameters
+        @sentry_sdk.trace(
+            template=SPANTEMPLATE.AI_CHAT,
+            op=OP.GEN_AI_CHAT,
+            name="user_chat_completion",
+            attributes={"model": "gpt-4", "temperature": 0.7}
+        )
+        def generate_response(prompt):
+            # Function implementation
+            pass
     """
     decorator = create_span_decorator(
         template=template,