feat(tracing): Allow users to bind a transaction to the global scope

include/sentry.h

@@ -1300,23 +1300,52 @@ SENTRY_EXPERIMENTAL_API void sentry_transaction_context_remove_sampled(
 /**
  * Starts a new Transaction based on the provided context, restored from an
  * external integration (i.e. a span from a different SDK) or manually
- * constructed by a user.
+ * constructed by a user. Returns a Transaction, which is expected to be
+ * manually managed by the caller. Manual management involves ensuring that
+ * `sentry_transaction_finish` is invoked for the Transaction, and that the
+ * caller manually starts and finishes any child Spans as needed on the
+ * Transaction.
+ *
+ * `sentry_transaction_finish` must be called in order for this Transaction to
+ * be sent to sentry.
+ *
+ * To ensure that any Events or Message Events are associated with this
+ * Transaction while it is active, invoke and pass in the Transaction returned
+ * by this function to `sentry_set_span`. Further documentation on this can be
+ * found in `sentry_set_span`'s docstring.
  *
  * Takes ownership of `transaction_context`.
  */
 SENTRY_EXPERIMENTAL_API sentry_value_t sentry_transaction_start(
     sentry_value_t transaction_context);
 
 /**
- * Finishes and sends a transaction to sentry. The event ID of the transaction
+ * Finishes and sends a Transaction to sentry. The event ID of the Transaction
  * will be returned if this was successful; A nil UUID will be returned
  * otherwise.
  *
  * Always takes ownership of `transaction`, regardless of whether the operation
- * was successful or not.
+ * was successful or not. If `sentry_set_span` was invoked with `transaction`,
+ * this will remove the
  */
 SENTRY_EXPERIMENTAL_API sentry_uuid_t sentry_transaction_finish(
     sentry_value_t transaction);
+
+/**
+ * Sets the Span (actually Transaction) so any Events sent while the Transaction
+ * is active will be associated with the Transaction.
+ *
+ * If the Transaction being passed in is unsampled, it will still be associated
+ * with any new Events. This will lead to some Events pointing to orphan or
+ * missing traces in sentry, see
+ * https://docs.sentry.io/product/sentry-basics/tracing/trace-view/#orphan-traces-and-broken-subtraces
+ *
+ * This increases the number of references pointing to the transaction.
+ * Invoke `sentry_transaction_finish` to remove the Span set by this function as
+ * well as its reference by passing in the same Transaction as the one passed
+ * into this function.
+ */
+SENTRY_EXPERIMENTAL_API void sentry_set_span(sentry_value_t transaction);
 #endif
 
 #ifdef __cplusplus

src/sentry_core.c

@@ -522,7 +522,7 @@ sentry__prepare_transaction(const sentry_options_t *options,
     sentry_envelope_t *envelope = NULL;
 
     SENTRY_WITH_SCOPE (scope) {
-        SENTRY_TRACE("merging scope into event");
+        SENTRY_TRACE("merging scope into transaction");
         // Don't include debugging info
         sentry_scope_mode_t mode = SENTRY_SCOPE_ALL & ~SENTRY_SCOPE_MODULES
             & ~SENTRY_SCOPE_STACKTRACES;
@@ -540,6 +540,7 @@ sentry__prepare_transaction(const sentry_options_t *options,
     return envelope;
 
 fail:
+    SENTRY_WARN("dropping transaction");
     sentry_envelope_free(envelope);
     sentry_value_decref(transaction);
     return NULL;
@@ -740,7 +741,6 @@ sentry_transaction_start(sentry_value_t tx_cxt)
     sentry_value_t tx = sentry_value_new_event();
     sentry_value_remove_by_key(tx, "timestamp");
 
-    // TODO(tracing): stuff transaction into the scope
     bool should_sample = sentry__should_send_transaction(tx_cxt);
     sentry_value_set_by_key(
         tx, "sampled", sentry_value_new_bool(should_sample));
@@ -757,7 +757,7 @@ sentry_transaction_start(sentry_value_t tx_cxt)
     sentry_value_set_by_key(
         tx, "trace_id", sentry_value_get_by_key_owned(tx_cxt, "trace_id"));
     sentry_value_set_by_key(
-        tx, "span_id", sentry_value_get_by_key_owned(tx_cxt, "trace_id"));
+        tx, "span_id", sentry_value_get_by_key_owned(tx_cxt, "span_id"));
     sentry_value_set_by_key(tx, "transaction",
         sentry_value_get_by_key_owned(tx_cxt, "transaction"));
     sentry_value_set_by_key(
@@ -767,24 +767,42 @@ sentry_transaction_start(sentry_value_t tx_cxt)
             sentry__msec_time_to_iso8601(sentry__msec_time())));
 
     sentry_value_decref(tx_cxt);
-
     return tx;
 }
 
 sentry_uuid_t
 sentry_transaction_finish(sentry_value_t tx)
 {
-    // The sampling decision should already be made for transactions during
-    // their construction. No need to recalculate here. See
+    if (sentry_value_is_null(tx)) {
+        SENTRY_DEBUG("no transaction available to finish");
+        goto fail;
+    }
+
+    SENTRY_WITH_SCOPE_MUT_NO_FLUSH (scope) {
+        const char *tx_id
+            = sentry_value_as_string(sentry_value_get_by_key(tx, "trace_id"));
+        const char *scope_tx_id = sentry_value_as_string(
+            sentry_value_get_by_key(scope->span, "trace_id"));
+        if (sentry__string_eq(tx_id, scope_tx_id)) {
+            sentry_value_decref(scope->span);
+            scope->span = sentry_value_new_null();
+        }
+    }
+    // immediately flush the scope so the transaction doesn't get attached to
+    // any new events
+    SENTRY_WITH_SCOPE_MUT (scope) {
+        (void)scope;
+    }
+    // The sampling decision should already be made for transactions
+    // during their construction. No need to recalculate here. See
     // `sentry__should_skip_transaction`.
     sentry_value_t sampled = sentry_value_get_by_key(tx, "sampled");
-    if (!sentry_value_is_null(sampled) && !sentry_value_is_true(sampled)) {
+    if (!sentry_value_is_true(sampled)) {
         SENTRY_DEBUG("throwing away transaction due to sample rate or "
                      "user-provided sampling value in transaction context");
-        sentry_value_decref(tx);
-        // TODO(tracing): remove from scope
-        return sentry_uuid_nil();
+        goto fail;
     }
+    sentry_value_remove_by_key(tx, "sampled");
 
     sentry_value_set_by_key(tx, "type", sentry_value_new_string("transaction"));
     sentry_value_set_by_key(tx, "timestamp",
@@ -815,5 +833,19 @@ sentry_transaction_finish(sentry_value_t tx)
     // This takes ownership of the transaction, generates an event ID, merges
     // scope
     return sentry__capture_event(tx);
+
+fail:
+    sentry_value_decref(tx);
+    return sentry_uuid_nil();
+}
+
+void
+sentry_set_span(sentry_value_t transaction)
+{
+    SENTRY_WITH_SCOPE_MUT (scope) {
+        sentry_value_decref(scope->span);
+        sentry_value_incref(transaction);
+        scope->span = transaction;
+    }
 }
 #endif

src/sentry_core.h

@@ -118,7 +118,7 @@ void sentry__options_unlock(void);
     for (const sentry_options_t *Options = sentry__options_getref(); Options;  \
          sentry_options_free((sentry_options_t *)Options), Options = NULL)
 
-// these for now are only needed for tests
+// these for now are only needed outside of core for tests
 #ifdef SENTRY_UNITTEST
 bool sentry__roll_dice(double probability);
 bool sentry__should_send_transaction(sentry_value_t tx_cxt);

src/sentry_scope.c

@@ -238,13 +238,16 @@ sentry__symbolize_stacktrace(sentry_value_t stacktrace)
 }
 
 #ifdef SENTRY_PERFORMANCE_MONITORING
-void
-sentry__scope_set_span(sentry_value_t span)
+#    ifdef SENTRY_UNITTEST
+sentry_value_t
+sentry__scope_get_span()
 {
-    // TODO: implement this function and get rid of this line.
-    (void)span;
-    return;
+    SENTRY_WITH_SCOPE (scope) {
+        return scope->span;
+    }
+    return sentry_value_new_null();
 }
+#    endif
 #endif
 
 void

src/sentry_scope.h

@@ -78,12 +78,6 @@ void sentry__scope_apply_to_event(const sentry_scope_t *scope,
     const sentry_options_t *options, sentry_value_t event,
     sentry_scope_mode_t mode);
 
-/**
- * Sets the span (actually transaction) on the scope. An internal way to pass
- * around contextual information needed from a transaction into other events.
- */
-void sentry__scope_set_span(sentry_value_t span);
-
 /**
  * These are convenience macros to automatically lock/unlock a scope inside a
  * code block.
@@ -99,3 +93,10 @@ void sentry__scope_set_span(sentry_value_t span);
          sentry__scope_unlock(), Scope = NULL)
 
 #endif
+
+#ifdef SENTRY_PERFORMANCE_MONITORING
+// this is only used in unit tests
+#ifdef SENTRY_UNITTEST
+sentry_value_t sentry__scope_get_span();
+#endif
+#endif

tests/unit/test_tracing.c

@@ -1,3 +1,4 @@
+#include "sentry_scope.h"
 #include "sentry_testsupport.h"
 #include "sentry_tracing.h"
 #include "sentry_uuid.h"
@@ -214,7 +215,7 @@ SENTRY_TEST(transport_sampling_transactions)
 
     sentry_close();
 
-    // well, its random after all
+    // exact value is nondeterministic because of rng
     TEST_CHECK(called_transport > 50 && called_transport < 100);
     TEST_CHECK(called_transport == sent_transactions);
 }
@@ -258,5 +259,58 @@ SENTRY_TEST(transactions_skip_before_send)
     TEST_CHECK_INT_EQUAL(called_beforesend, 0);
 }
 
+static void
+before_transport(sentry_envelope_t *envelope, void *data)
+{
+    uint64_t *called = data;
+    *called += 1;
+
+    sentry_envelope_free(envelope);
+}
+
+SENTRY_TEST(multiple_transactions)
+{
+    uint64_t called_transport = 0;
+
+    sentry_options_t *options = sentry_options_new();
+    sentry_options_set_dsn(options, "https://[email protected]/42");
+
+    sentry_transport_t *transport = sentry_transport_new(before_transport);
+    sentry_transport_set_state(transport, &called_transport);
+    sentry_options_set_transport(options, transport);
+
+    sentry_options_set_traces_sample_rate(options, 1.0);
+    sentry_init(options);
+
+    sentry_value_t tx_cxt = sentry_value_new_transaction_context("wow!", NULL);
+    sentry_value_t tx = sentry_transaction_start(tx_cxt);
+    sentry_set_span(tx);
+
+    sentry_value_t scope_tx = sentry__scope_get_span();
+    CHECK_STRING_PROPERTY(scope_tx, "transaction", "wow!");
+
+    sentry_uuid_t event_id = sentry_transaction_finish(tx);
+    scope_tx = sentry__scope_get_span();
+    TEST_CHECK(sentry_value_is_null(scope_tx));
+    TEST_CHECK(!sentry_uuid_is_nil(&event_id));
+
+    // Set transaction on scope twice, back-to-back without finishing the first
+    // one
+    tx_cxt = sentry_value_new_transaction_context("whoa!", NULL);
+    tx = sentry_transaction_start(tx_cxt);
+    sentry_set_span(tx);
+    sentry_value_decref(tx);
+    tx_cxt = sentry_value_new_transaction_context("wowee!", NULL);
+    tx = sentry_transaction_start(tx_cxt);
+    sentry_set_span(tx);
+    scope_tx = sentry__scope_get_span();
+    CHECK_STRING_PROPERTY(scope_tx, "transaction", "wowee!");
+    event_id = sentry_transaction_finish(tx);
+    TEST_CHECK(!sentry_uuid_is_nil(&event_id));
+
+    sentry_close();
+
+    TEST_CHECK_INT_EQUAL(called_transport, 2);
+}
 #undef IS_NULL
 #undef CHECK_STRING_PROPERTY

tests/unit/tests.inc

@@ -30,6 +30,7 @@ XX(module_finder)
 XX(mpack_newlines)
 XX(mpack_removed_tags)
 XX(multiple_inits)
+XX(multiple_transactions)
 XX(os)
 XX(page_allocator)
 XX(path_basics)