docs: Update docs with new Tracing and Scope APIs (#5508)

docs/api.rst

@@ -66,3 +66,7 @@ Managing Scope (advanced)
 .. autofunction:: sentry_sdk.api.push_scope
 
 .. autofunction:: sentry_sdk.api.new_scope
+.. autofunction:: sentry_sdk.api.isolation_scope
+
+.. autofunction:: sentry_sdk.api.get_current_scope
+.. autofunction:: sentry_sdk.api.get_isolation_scope

docs/index.rst

@@ -8,5 +8,6 @@ visit the `GitHub repository <https://github.com/getsentry/sentry-python>`_.
 
 .. toctree::
     api
+    tracing
     integrations
     apidocs

docs/tracing.rst

@@ -0,0 +1,66 @@
+=======
+Tracing
+=======
+
+With Performance Monitoring, Sentry tracks your software's performance, measuring variables such as throughput and latency.
+
+Manual Instrumentation
+=====================
+
+You can manually start transactions and spans to trace custom operations in your application.
+
+Transactions
+------------
+A transaction represents a single instance of a service being called. It forms the root of a trace tree.
+
+.. code-block:: python
+
+    import sentry_sdk
+
+    # Start a transaction as a context manager
+    with sentry_sdk.start_transaction(name="process-order"):
+        # Your application logic here
+        pass
+
+Spans
+-----
+Spans represent individual units of work within a transaction, such as a database query or an API call.
+
+.. code-block:: python
+
+    import sentry_sdk
+
+    # Start a child span under the current transaction
+    with sentry_sdk.start_child_span(op="db.query", name="SELECT * FROM users"):
+        # Your operation here
+        pass
+
+
+Managing Context with Scopes
+============================
+
+Sentry use **Scopes** to manage execution context and event enrichment. In SDK 2.x, top-level APIs replace the deprecated Hub model.
+
+Isolation Scope
+---------------
+The `isolation_scope` should be used for isolating data that belongs to a single request or job lifecycle. It propagates data across child scopes.
+
+.. code-block:: python
+
+    import sentry_sdk
+
+    with sentry_sdk.isolation_scope() as scope:
+        scope.set_tag("user_type", "admin")
+        # Operations triggered here will include the tag
+
+New Scope
+---------
+The `new_scope` forks the current scope for local, short-lived modifications. 
+
+.. code-block:: python
+
+    import sentry_sdk
+
+    with sentry_sdk.new_scope() as scope:
+        scope.set_extra("temp_debug_data", 123)
+        # Changes are discarded when existing the block

sentry_sdk/integrations/asyncpg.py

@@ -169,6 +169,7 @@ async def _inner(*args: "Any", **kwargs: "Any") -> "T":
             origin=AsyncPGIntegration.origin,
         ) as span:
             span.set_data(SPANDATA.DB_SYSTEM, "postgresql")
+            span.set_data("db.driver", "asyncpg")
             addr = kwargs.get("addr")
             if addr:
                 try:
@@ -192,6 +193,7 @@ async def _inner(*args: "Any", **kwargs: "Any") -> "T":
 
 def _set_db_data(span: "Span", conn: "Any") -> None:
     span.set_data(SPANDATA.DB_SYSTEM, "postgresql")
+    span.set_data("db.driver", "asyncpg")
 
     addr = conn._addr
     if addr:

sentry_sdk/integrations/sqlalchemy.py

@@ -137,6 +137,9 @@ def _set_db_data(span: "Span", conn: "Any") -> None:
     if db_system is not None:
         span.set_data(SPANDATA.DB_SYSTEM, db_system)
 
+    if hasattr(conn.engine, "dialect") and hasattr(conn.engine.dialect, "driver"):
+        span.set_data("db.driver", conn.engine.dialect.driver)
+
     if conn.engine.url is None:
         return