Warn when transaction entered without calling start_transaction

sentry_sdk/tracing.py

@@ -695,8 +695,31 @@ def __repr__(self):
             )
         )
 
+    def _possibly_started(self):
+        # type: () -> bool
+        """Returns whether the transaction might have been started.
+
+        If this returns False, we know that the transaction was not started
+        with sentry_sdk.start_transaction, and therefore the transaction will
+        be discarded.
+        """
+
+        # We must explicitly check self.sampled is False since self.sampled can be None
+        return self._span_recorder is not None or self.sampled is False
+
     def __enter__(self):
         # type: () -> Transaction
+        if not self._possibly_started():
+            logger.warning(
+                """Transaction was entered without being started with sentry_sdk.start_transaction.
+                   The transaction will not be sent to Sentry. To fix, start the transaction by
+                   passing it to sentry_sdk.start_transaction, like so:
+
+                   with sentry_sdk.start_transaction(transaction):
+                       # code here
+                """
+            )
+
         super().__enter__()
 
         if self._profile is not None:
@@ -747,9 +770,14 @@ def finish(self, hub=None, end_timestamp=None):
             # We have no active client and therefore nowhere to send this transaction.
             return None
 
-        # This is a de facto proxy for checking if sampled = False
         if self._span_recorder is None:
-            logger.debug("Discarding transaction because sampled = False")
+            # Explicit check against False needed because self.sampled might be None
+            if self.sampled is False:
+                logger.debug("Discarding transaction because sampled = False")
+            else:
+                logger.debug(
+                    "Discarding transaction because it was not started with sentry_sdk.start_transaction"
+                )
 
             # This is not entirely accurate because discards here are not
             # exclusively based on sample rate but also traces sampler, but

tests/tracing/test_misc.py

@@ -362,3 +362,62 @@ def test_start_transaction_updates_scope_name_source(sentry_init):
     with start_transaction(name="foobar", source="route"):
         assert scope._transaction == "foobar"
         assert scope._transaction_info == {"source": "route"}
+
+
+@pytest.mark.parametrize("sampled", (True, None))
+def test_transaction_dropped_debug_not_started(sentry_init, sampled):
+    sentry_init(enable_tracing=True)
+
+    tx = Transaction(sampled=sampled)
+
+    with mock.patch("sentry_sdk.tracing.logger") as mock_logger:
+        with tx:
+            pass
+
+    mock_logger.debug.assert_any_call(
+        "Discarding transaction because it was not started with sentry_sdk.start_transaction"
+    )
+
+    with pytest.raises(AssertionError):
+        # We should NOT see the "sampled = False" message here
+        mock_logger.debug.assert_any_call(
+            "Discarding transaction because sampled = False"
+        )
+
+
+def test_transaction_dropeed_sampled_false(sentry_init):
+    sentry_init(enable_tracing=True)
+
+    tx = Transaction(sampled=False)
+
+    with mock.patch("sentry_sdk.tracing.logger") as mock_logger:
+        with sentry_sdk.start_transaction(tx):
+            pass
+
+    mock_logger.debug.assert_any_call("Discarding transaction because sampled = False")
+
+    with pytest.raises(AssertionError):
+        # We should not see the "not started" message here
+        mock_logger.debug.assert_any_call(
+            "Discarding transaction because it was not started with sentry_sdk.start_transaction"
+        )
+
+
+def test_transaction_not_started_warning(sentry_init):
+    sentry_init(enable_tracing=True)
+
+    tx = Transaction()
+
+    with mock.patch("sentry_sdk.tracing.logger") as mock_logger:
+        with tx:
+            pass
+
+    mock_logger.warning.assert_any_call(
+        """Transaction was entered without being started with sentry_sdk.start_transaction.
+                   The transaction will not be sent to Sentry. To fix, start the transaction by
+                   passing it to sentry_sdk.start_transaction, like so:
+
+                   with sentry_sdk.start_transaction(transaction):
+                       # code here
+                """
+    )