feat(tracing): Basic transaction context creation

include/sentry.h

@@ -1226,6 +1226,57 @@ SENTRY_EXPERIMENTAL_API void sentry_options_set_traces_sample_rate(
 SENTRY_EXPERIMENTAL_API double sentry_options_get_traces_sample_rate(
     sentry_options_t *opts);
 
+/* -- Performance Monitoring/Tracing APIs -- */
+
+/**
+ * Constructs a new transaction context to be passed
+ * into `sentry_start_transaction`.
+ *
+ * See
+ * https://docs.sentry.io/platforms/native/enriching-events/transaction-name/
+ * for an explanation of a transaction's `name`, and
+ * https://develop.sentry.dev/sdk/performance/span-operations/ for conventions
+ * around an operation's name.
+ *
+ * Also see https://develop.sentry.dev/sdk/event-payloads/transaction/#anatomy
+ * for an explanation of `operation`, in addition to other properties and
+ * actions that can be performed with a transaction.
+ */
+SENTRY_EXPERIMENTAL_API sentry_value_t sentry_value_new_transaction_context(
+    const char *name, const char *operation);
+
+/**
+ * Sets the name of a transaction on a `transaction_context`.
+ */
+SENTRY_EXPERIMENTAL_API void sentry_transaction_context_set_name(
+    sentry_value_t transaction_context, const char *name);
+
+/**
+ * Sets the operation of a transaction on a `transaction_context`.
+ *
+ * See https://develop.sentry.dev/sdk/performance/span-operations/ for
+ * conventions on `operation`s.
+ */
+SENTRY_EXPERIMENTAL_API void sentry_transaction_context_set_operation(
+    sentry_value_t transaction_context, const char *operation);
+
+/**
+ * Sets the sampled field on a `transaction_context`. When turned on, the
+ * transaction constructed from the `transaction_context` will bypass all
+ * sampling options and always be sent to sentry. If this is explicitly turned
+ * off in the `transaction_context`, the transaction will never be sent to
+ * sentry.
+ */
+SENTRY_EXPERIMENTAL_API void sentry_transaction_context_set_sampled(
+    sentry_value_t transaction_context, int sampled);
+
+/**
+ * Removes the sampled field on a `transaction_context`. The transaction
+ * contructed from it will use the sampling rate as defined in `sentry_options`.
+ */
+SENTRY_EXPERIMENTAL_API void sentry_transaction_context_remove_sampled(
+    sentry_value_t transaction_context);
+
 #ifdef __cplusplus
 }
 #endif

src/sentry_value.c

@@ -1124,6 +1124,53 @@ sentry_value_new_stacktrace(void **ips, size_t len)
     return stacktrace;
 }
 
+sentry_value_t
+sentry_value_new_transaction_context(const char *name, const char *operation)
+{
+    sentry_value_t transaction_context = sentry_value_new_object();
+
+    sentry_transaction_context_set_name(transaction_context, name);
+    sentry_transaction_context_set_operation(transaction_context, operation);
+
+    return transaction_context;
+}
+
+void
+sentry_transaction_context_set_name(
+    sentry_value_t transaction_context, const char *name)
+{
+    sentry_value_t sv_name = sentry_value_new_string(name);
+    // TODO: Consider doing this checking right before sending or flushing
+    // the transaction.
+    if (sentry_value_is_null(sv_name) || sentry__string_eq(name, "")) {
+        sentry_value_decref(sv_name);
+        sv_name = sentry_value_new_string("<unlabeled transaction>");
+    }
+    sentry_value_set_by_key(transaction_context, "name", sv_name);
+}
+
+void
+sentry_transaction_context_set_operation(
+    sentry_value_t transaction_context, const char *operation)
+{
+    sentry_value_set_by_key(
+        transaction_context, "op", sentry_value_new_string(operation));
+}
+
+void
+sentry_transaction_context_set_sampled(
+    sentry_value_t transaction_context, int sampled)
+{
+    sentry_value_set_by_key(
+        transaction_context, "sampled", sentry_value_new_bool(sampled));
+}
+
+void
+sentry_transaction_context_remove_sampled(sentry_value_t transaction_context)
+{
+    sentry_value_remove_by_key(transaction_context, "sampled");
+}
+
 static sentry_value_t
 sentry__get_or_insert_values_list(sentry_value_t parent, const char *key)
 {

tests/unit/test_tracing.c

@@ -33,3 +33,43 @@ SENTRY_TEST(basic_tracing_context)
     sentry_value_decref(trace_context);
     sentry_value_decref(span);
 }
+
+SENTRY_TEST(basic_transaction_context)
+{
+    sentry_value_t tx_cxt = sentry_value_new_transaction_context(NULL, NULL);
+    TEST_CHECK(!sentry_value_is_null(tx_cxt));
+    const char *tx_name
+        = sentry_value_as_string(sentry_value_get_by_key(tx_cxt, "name"));
+    TEST_CHECK_STRING_EQUAL(tx_name, "<unlabeled transaction>");
+    const char *tx_op
+        = sentry_value_as_string(sentry_value_get_by_key(tx_cxt, "op"));
+    TEST_CHECK_STRING_EQUAL(tx_op, "");
+
+    sentry_value_decref(tx_cxt);
+    tx_cxt = sentry_value_new_transaction_context("", "");
+    TEST_CHECK(!sentry_value_is_null(tx_cxt));
+    tx_name = sentry_value_as_string(sentry_value_get_by_key(tx_cxt, "name"));
+    TEST_CHECK_STRING_EQUAL(tx_name, "<unlabeled transaction>");
+    TEST_CHECK_STRING_EQUAL(tx_op, "");
+
+    sentry_value_decref(tx_cxt);
+    tx_cxt = sentry_value_new_transaction_context("honk.beep", "beepbeep");
+    tx_name = sentry_value_as_string(sentry_value_get_by_key(tx_cxt, "name"));
+    TEST_CHECK_STRING_EQUAL(tx_name, "honk.beep");
+    tx_op = sentry_value_as_string(sentry_value_get_by_key(tx_cxt, "op"));
+    TEST_CHECK_STRING_EQUAL(tx_op, "beepbeep");
+
+    sentry_transaction_context_set_name(tx_cxt, "");
+    tx_name = sentry_value_as_string(sentry_value_get_by_key(tx_cxt, "name"));
+    TEST_CHECK_STRING_EQUAL(tx_name, "<unlabeled transaction>");
+
+    sentry_transaction_context_set_operation(tx_cxt, "");
+    tx_op = sentry_value_as_string(sentry_value_get_by_key(tx_cxt, "op"));
+    TEST_CHECK_STRING_EQUAL(tx_op, "");
+
+    sentry_transaction_context_set_sampled(tx_cxt, 1);
+    TEST_CHECK(
+        sentry_value_is_true(sentry_value_get_by_key(tx_cxt, "sampled")) == 1);
+
+    sentry_value_decref(tx_cxt);
+}

tests/unit/tests.inc

@@ -5,6 +5,7 @@ XX(basic_http_request_preparation_for_event)
 XX(basic_http_request_preparation_for_event_with_attachment)
 XX(basic_http_request_preparation_for_minidump)
 XX(basic_tracing_context)
+XX(basic_transaction_context)
 XX(buildid_fallback)
 XX(concurrent_init)
 XX(count_sampled_events)