feat: Add retrieving Transaction (#1775)

* fix: SDK specific docs

* ref: Update python

* Update python docs

Co-authored-by: Rodolfo Carvalho <rodolfo.carvalho@sentry.io>

src/collections/_documentation/performance-monitoring/configuration/javascript.md

@@ -214,6 +214,24 @@ Sentry.init({
 });
 ```
 
+**Retrieving a Transaction**
+
+In cases where you want to attach Spans to an already ongoing Transaction you can use `Sentry.getCurrentHub().getScope().getTransaction()`. This function will return a `Transaction` in case there is a running Transaction otherwise it returns `undefined`. If you are using our Tracing integration by default we attach the Transaction to the Scope. So you could do something like this:
+
+```javascript
+function myJsFunction() {
+  const transaction = Sentry.getCurrentHub().getScope().getTransaction();
+  if (transaction) {
+    let span = transaction.startChild({
+      op: "encode",
+      description: "parseAvatarImages"
+    });
+    // Do something
+    span.finish();
+  }
+}
+```
+
 **Adding Query Information and Parameters to Spans**
 
 Currently, every tag has a maximum character limit of 200 characters. Tags over the 200 character limit will become truncated, losing potentially important information. To retain this data, you can split data over several tags instead.
@@ -237,7 +255,6 @@ span.setTag("baseUrl", baseUrl);
 span.setTag("endpoint", endpoint);
 span.setTag("parameters", parameters);
 http.get(`${base_url}/${endpoint}/`, data=parameters);
-...
 ```
 
 baseUrl

src/collections/_documentation/performance-monitoring/configuration/node.md

@@ -92,5 +92,23 @@ app.use(function processItems(req, res, next) {
   })
 });
 ```
-
 <!-- ENDWIZARD -->
+
+#### Retrieving a Transaction
+
+In cases where you want to attach Spans to an already ongoing Transaction you can use `Sentry.getCurrentHub().getScope().getTransaction()`. This function will return a `Transaction` in case there is a running Transaction otherwise it returns `undefined`. If you are using our Express integration by default we attach the Transaction to the Scope. So you could do something like this:
+
+```javascript
+app.get("/success", function successHandler(req, res) {
+  const transaction = Sentry.getCurrentHub().getScope().getTransaction();
+  if (transaction) {
+    let span = transaction.startChild({
+      op: "encode",
+      description: "parseAvatarImages"
+    });
+    // Do something
+    span.finish();
+  }
+  res.status(200).end();
+});
+```

src/collections/_documentation/performance-monitoring/configuration/python.md

@@ -70,36 +70,91 @@ To manually instrument certain regions of your code, you can create a transactio
 The following example creates a transaction for a scope that contains an expensive operation (for example, `process_item`), and sends the result to Sentry:
 
 ```python
-import sentry_sdk
+from sentry_sdk import start_transaction
 
 while True:
   item = get_from_queue()
 
-  with sentry_sdk.start_transaction(op="task", name=item.get_transaction_name()):
+  with start_transaction(op="task", name=item.get_transaction_name()):
       # process_item may create more spans internally (see next examples)
       process_item(item)
 ```
 
 **Adding More Spans to the Transaction**
 
-The next example contains the implementation of the hypothetical `process_item` function called from the code snippet in the previous section. Our SDK can determine if there is currently an open transaction and add all newly created spans as child operations to that transaction. Keep in mind that each individual span also needs to be manually finished; otherwise, spans will not show up in the transaction.
+The next example contains the implementation of the hypothetical `process_item` function called from the code snippet in the previous section. Our SDK can determine if there is currently an open transaction and add all newly created spans as child operations to that transaction. Keep in mind that each individual span also needs to be manually finished; otherwise, spans will not show up in the transaction. When using spans and transactions as context managers, they are automatically finished at the end of the `with` block.
+
+In cases where you want to attach Spans to an already ongoing Transaction you can use `Hub.current.scope.transaction`. This property will return a `Transaction` in case there is a running Transaction otherwise it returns `None`.
+
+Alternatively, instead of adding to the top-level transaction, you can make a child span of the current span, if there is one. Use ``Hub.current.scope.span` in that case.
 
 You can choose the value of `op` and `description`.
 
 ```python
-import sentry_sdk
+from sentry_sdk import Hub
 
 def process_item(item):
+    transaction = Hub.current.scope.transaction
+    # omitted code...
+    with transaction.start_child(op="http", description="GET /") as span:
+        response = my_custom_http_library.request("GET", "/")
+        span.set_tag("http.status_code", response.status_code)
+        span.set_data("http.foobarsessionid", get_foobar_sessionid())
+```
+
+The alternative to make a tree of spans:
 
-  # omitted code...
-  with sentry_sdk.start_span(op="http", description="GET /") as span:
-      response = my_custom_http_library.request("GET", "/")
-      span.set_tag("http.status_code", response.status_code)
-      span.set_data("http.foobarsessionid", get_foobar_sessionid())
+```python
+from sentry_sdk import Hub
+
+def process_item(item):
+    parent_span = Hub.current.scope.span
+    # omitted code...
+    with parent_span.start_child(op="http", description="GET /") as span:
+        response = my_custom_http_library.request("GET", "/")
+        span.set_tag("http.status_code", response.status_code)
+        span.set_data("http.foobarsessionid", get_foobar_sessionid())
 ```
 
 <!-- ENDWIZARD -->
 
+#### Retrieving a Transaction
+
+In cases where you want to attach Spans to an already ongoing Transaction you can use `Hub.current.scope.transaction`. This property will return a `Transaction` in case there is a running Transaction otherwise it returns `None`.
+
+```python
+from sentry_sdk import Hub
+
+transaction = Hub.current.scope.transaction
+
+if transaction is None:
+    with start_transaction(name="task"):
+        do_task()
+else:
+    transaction.name = "new name"
+    with transaction.start_child(op="task"):
+        do_task()
+```
+
+#### Retrieving the current Span
+
+Started spans are stored in the scope, and can be fetched off the scope:
+
+```python
+from sentry_sdk import Hub
+
+span = Hub.current.scope.span
+
+if span is None:
+    # no span in progress, create new transaction
+    with start_transaction(name="task"):
+        do_task()
+else:
+    # new task span as child of current span
+    with span.start_child(op="task"):
+        do_task()
+```
+
 **Adding Query Information and Parameters to Spans**
 
 Currently, every tag has a maximum character limit of 200 characters. Tags over the 200 character limit will become truncated, losing potentially important information. To retain this data, you can split data over several tags instead.
@@ -116,10 +171,10 @@ Instead, using `span.set_tag` splits the details of this query over several tags
 ```python
 import sentry_sdk
 ...
-with sentry_sdk.start_span(op="request", transaction="setup form") as span:
-    span.set_tag("base_url", base_url)
-    span.set_tag("endpoint", endpoint)
-    span.set_tag("parameters", parameters)
+with sentry_sdk.start_transaction(op="request", name="setup form") as transaction:
+    transaction.set_tag("base_url", base_url)
+    transaction.set_tag("endpoint", endpoint)
+    transaction.set_tag("parameters", parameters)
     make_request(
         "{base_url}/{endpoint}/".format(
             base_url=base_url,