feat(tracing): Basic span support with nesting (#634)

.gitignore

@@ -7,6 +7,7 @@ CMakeSettings.json
 /build
 /build*
 leak-build
+unit-build
 
 # Run files
 .sentry-native

Makefile

@@ -12,14 +12,17 @@ build: build/Makefile
 	@cmake --build build --parallel
 .PHONY: build
 
-build/sentry_test_unit: build
-	@cmake --build build --target sentry_test_unit --parallel
-
 test: update-test-discovery test-integration
 .PHONY: test
 
-test-unit: update-test-discovery build/sentry_test_unit
-	./build/sentry_test_unit
+test-unit: update-test-discovery CMakeLists.txt
+	@mkdir -p unit-build
+	@cd unit-build; cmake \
+		-DCMAKE_RUNTIME_OUTPUT_DIRECTORY=$(PWD)/unit-build \
+		-DSENTRY_BACKEND=none \
+		..
+	@cmake --build unit-build --target sentry_test_unit --parallel
+	./unit-build/sentry_test_unit
 .PHONY: test-unit
 
 test-integration: setup-venv

examples/example.c

@@ -97,6 +97,10 @@ main(int argc, char **argv)
     if (has_arg(argc, argv, "capture-transaction")) {
         sentry_options_set_traces_sample_rate(options, 1.0);
     }
+
+    if (has_arg(argc, argv, "child-spans")) {
+        sentry_options_set_max_spans(options, 5);
+    }
 #endif
 
     sentry_init(options);
@@ -217,14 +221,24 @@ main(int argc, char **argv)
 #ifdef SENTRY_PERFORMANCE_MONITORING
     if (has_arg(argc, argv, "capture-transaction")) {
         sentry_value_t tx_ctx
-            = sentry_value_new_transaction_context("I'm a little teapot",
+            = sentry_value_new_transaction_context("little.teapot",
                 "Short and stout here is my handle and here is my spout");
 
         if (has_arg(argc, argv, "unsample-tx")) {
             sentry_transaction_context_set_sampled(tx_ctx, 0);
         }
-
         sentry_value_t tx = sentry_transaction_start(tx_ctx);
+
+        if (has_arg(argc, argv, "child-spans")) {
+            sentry_value_t child_ctx
+                = sentry_span_start_child(tx, "littler.teapot", NULL);
+            sentry_value_t grandchild_ctx
+                = sentry_span_start_child(child_ctx, "littlest.teapot", NULL);
+
+            sentry_span_finish(tx, grandchild_ctx);
+            sentry_span_finish(tx, child_ctx);
+        }
+
         sentry_transaction_finish(tx);
     }
 #endif

include/sentry.h

@@ -1346,6 +1346,47 @@ SENTRY_EXPERIMENTAL_API sentry_uuid_t sentry_transaction_finish(
  * into this function.
  */
 SENTRY_EXPERIMENTAL_API void sentry_set_span(sentry_value_t transaction);
+
+/**
+ * Starts a new Span.
+ *
+ * Either the return value of `sentry_start_transaction` or
+ * `sentry_span_start_child` may be passed in as `parent`.
+ *
+ * Both `operation` and `description` can be null, but it is recommended to
+ * supply the former. See
+ * https://develop.sentry.dev/sdk/performance/span-operations/ for conventions
+ * around operations.
+ *
+ * See https://develop.sentry.dev/sdk/event-payloads/span/ for a description of
+ * the created Span's properties and expectations for `operation` and
+ * `description`.
+ *
+ * Returns a value that should be passed into `sentry_span_finish`. Not
+ * finishing the Span means it will be discarded, and will not be sent to
+ * sentry. `sentry_value_null` will be returned if the child Span could not be
+ * created.
+ */
+SENTRY_EXPERIMENTAL_API sentry_value_t sentry_span_start_child(
+    sentry_value_t parent, char *operation, char *description);
+
+/**
+ * Finishes a Span.
+ *
+ * Returns a value that should be passed into `sentry_span_finish`. Not
+ * finishing the Span means it will be discarded, and will not be sent to
+ * sentry.
+ *
+ * `root_transaction` is either the parent Transaction of the Span, or
+ * the ancestor Transaction of the Span if the Span is not a direct descendant
+ * of a Transaction.
+ *
+ * This takes ownership of `span`, as child Spans must always occur within the
+ * total duration of a parent span and cannot take a longer amount of time to
+ * complete than the parent span they belong to.
+ */
+SENTRY_EXPERIMENTAL_API void sentry_span_finish(
+    sentry_value_t root_transaction, sentry_value_t span);
 #endif
 
 #ifdef __cplusplus

src/sentry_core.c

@@ -803,6 +803,8 @@ sentry_transaction_finish(sentry_value_t tx)
     sentry_value_set_by_key(tx, "timestamp",
         sentry__value_new_string_owned(
             sentry__msec_time_to_iso8601(sentry__msec_time())));
+    // TODO: This might not actually be necessary. Revisit after talking to
+    // the relay team about this.
     sentry_value_set_by_key(tx, "level", sentry_value_new_string("info"));
 
     sentry_value_t name = sentry_value_get_by_key(tx, "transaction");
@@ -843,4 +845,108 @@ sentry_set_span(sentry_value_t transaction)
         scope->span = transaction;
     }
 }
+
+sentry_value_t
+sentry_span_start_child(
+    sentry_value_t parent, char *operation, char *description)
+{
+    size_t max_spans = SENTRY_SPANS_MAX;
+    SENTRY_WITH_OPTIONS (options) {
+        max_spans = options->max_spans;
+    }
+
+    if (sentry_value_is_null(parent)) {
+        SENTRY_DEBUG("no transaction available to create a child under");
+        goto fail;
+    }
+
+    if (!sentry_value_is_null(sentry_value_get_by_key(parent, "timestamp"))) {
+        SENTRY_DEBUG("span's parent is already finished, not creating span");
+        goto fail;
+    }
+
+    // Aggressively discard spans if a transaction is unsampled to avoid
+    // wasting memory
+    sentry_value_t sampled = sentry_value_get_by_key(parent, "sampled");
+    if (!sentry_value_is_true(sampled)) {
+        SENTRY_DEBUG("span's parent is unsampled, not creating span");
+        goto fail;
+    }
+    sentry_value_t spans = sentry_value_get_by_key(parent, "spans");
+    // This only checks that the number of _completed_ spans matches the number
+    // of max spans. This means that the number of in-flight spans can exceed
+    // the max number of spans.
+    if (sentry_value_get_length(spans) >= max_spans) {
+        SENTRY_DEBUG("reached maximum number of spans for transaction, not "
+                     "creating span");
+        goto fail;
+    }
+
+    sentry_value_t child = sentry__value_new_span(parent, operation);
+    sentry_value_set_by_key(
+        child, "description", sentry_value_new_string(description));
+    sentry_value_set_by_key(child, "start_timestamp",
+        sentry__value_new_string_owned(
+            sentry__msec_time_to_iso8601(sentry__msec_time())));
+    sentry_value_set_by_key(child, "sampled", sentry_value_new_bool(1));
+
+    return child;
+
+fail:
+    return sentry_value_new_null();
+}
+
+void
+sentry_span_finish(sentry_value_t root_transaction, sentry_value_t span)
+{
+    if (sentry_value_is_null(root_transaction) || sentry_value_is_null(span)) {
+        SENTRY_DEBUG(
+            "missing root transaction or span to finish, aborting span finish");
+        goto fail;
+    }
+
+    if (!sentry_value_is_null(
+            sentry_value_get_by_key(root_transaction, "timestamp"))) {
+        SENTRY_DEBUG("span's root transaction is already finished, aborting "
+                     "span finish");
+        goto fail;
+    }
+
+    if (!sentry_value_is_null(sentry_value_get_by_key(span, "timestamp"))) {
+        SENTRY_DEBUG("span is already finished, aborting span finish");
+        goto fail;
+    }
+
+    // tough luck if this span actually doesn't belong on the specified
+    // transaction, i.e. its trace id doesn't match the root transaction's trace
+    // id
+    sentry_value_set_by_key(span, "timestamp",
+        sentry__value_new_string_owned(
+            sentry__msec_time_to_iso8601(sentry__msec_time())));
+    sentry_value_remove_by_key(span, "sampled");
+
+    size_t max_spans = SENTRY_SPANS_MAX;
+    SENTRY_WITH_OPTIONS (options) {
+        max_spans = options->max_spans;
+    }
+
+    sentry_value_t spans = sentry_value_get_by_key(root_transaction, "spans");
+
+    if (sentry_value_get_length(spans) >= max_spans) {
+        SENTRY_DEBUG("reached maximum number of spans for transaction, "
+                     "discarding span");
+        goto fail;
+    }
+
+    if (sentry_value_is_null(spans)) {
+        spans = sentry_value_new_list();
+        sentry_value_set_by_key(root_transaction, "spans", spans);
+    }
+    sentry_value_append(spans, span);
+    return;
+
+fail:
+    sentry_value_decref(span);
+    return;
+}
 #endif

src/sentry_core.h

@@ -5,6 +5,7 @@
 #include "sentry_logger.h"
 
 #define SENTRY_BREADCRUMBS_MAX 100
+#define SENTRY_SPANS_MAX 1000
 
 #if defined(__GNUC__) && (__GNUC__ >= 4)
 #    define MUST_USE __attribute__((warn_unused_result))
@@ -121,7 +122,9 @@ void sentry__options_unlock(void);
 // these for now are only needed outside of core for tests
 #ifdef SENTRY_UNITTEST
 bool sentry__roll_dice(double probability);
+#    ifdef SENTRY_PERFORMANCE_MONITORING
 bool sentry__should_send_transaction(sentry_value_t tx_cxt);
+#    endif
 #endif
 
 #endif

src/sentry_tracing.c

@@ -27,6 +27,7 @@ sentry__span_get_trace_context(sentry_value_t span)
     PLACE_VALUE("description", span);
     PLACE_VALUE("status", span);
 
+    // TODO: freeze this
     return trace_context;
 
 #undef PLACE_VALUE

src/sentry_tracing.h

@@ -10,4 +10,6 @@
  * See https://develop.sentry.dev/sdk/event-payloads/transaction/#examples
  */
 sentry_value_t sentry__span_get_trace_context(sentry_value_t span);
+
+sentry_value_t sentry__span_get_span_context(sentry_value_t span);
 #endif

src/sentry_value.c

@@ -1133,15 +1133,26 @@ sentry__value_new_span(sentry_value_t parent, const char *operation)
     sentry_value_t span = sentry_value_new_object();
 
     sentry_transaction_context_set_operation(span, operation);
+
+    sentry_uuid_t span_id = sentry_uuid_new_v4();
+    sentry_value_set_by_key(
+        span, "span_id", sentry__value_new_span_uuid(&span_id));
+
     sentry_value_set_by_key(span, "status", sentry_value_new_string("ok"));
 
+    // Span creation is currently aggressively pruned prior to this function so
+    // once we're in here we definitely know that the span and its parent
+    // transaction are sampled.
+    // Sampling decisions inherited from traces created in other SDKs should be
+    // taken care of `continue_from_headers`, spans don't need to worry about
+    // (inheriting) forced sampling decisions, and transactions cannot be
+    // children of other transactions, so no inheriting of the sampling field is
+    // needed.
     if (!sentry_value_is_null(parent)) {
         sentry_value_set_by_key(span, "trace_id",
             sentry_value_get_by_key_owned(parent, "trace_id"));
         sentry_value_set_by_key(span, "parent_span_id",
             sentry_value_get_by_key_owned(parent, "span_id"));
-        sentry_value_set_by_key(
-            span, "sampled", sentry_value_get_by_key_owned(parent, "sampled"));
     }
 
     return span;
@@ -1152,16 +1163,11 @@ sentry_value_new_transaction_context(const char *name, const char *operation)
 {
     sentry_value_t transaction_context
         = sentry__value_new_span(sentry_value_new_null(), operation);
-    sentry_transaction_context_set_name(transaction_context, name);
 
     sentry_uuid_t trace_id = sentry_uuid_new_v4();
     sentry_value_set_by_key(transaction_context, "trace_id",
         sentry__value_new_internal_uuid(&trace_id));
 
-    sentry_uuid_t span_id = sentry_uuid_new_v4();
-    sentry_value_set_by_key(
-        transaction_context, "span_id", sentry__value_new_span_uuid(&span_id));
-
     sentry_transaction_context_set_name(transaction_context, name);
 
     return transaction_context;