feat(tracing): Drop unfinished spans from a transaction

examples/example.c

@@ -93,6 +93,14 @@ main(int argc, char **argv)
             options, sentry_transport_new(print_envelope));
     }
 
+    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);
+    }
+
     sentry_init(options);
 
     if (!has_arg(argc, argv, "no-setup")) {
@@ -208,6 +216,33 @@ main(int argc, char **argv)
         sentry_capture_event(event);
     }
 
+    if (has_arg(argc, argv, "capture-transaction")) {
+        sentry_value_t tx_ctx
+            = 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_transaction_start(tx_ctx);
+
+        if (has_arg(argc, argv, "child-spans")) {
+            sentry_value_t child_ctx = sentry_span_start_child(
+                sentry_value_new_null(), "littler.teapot", NULL);
+            sentry_value_t grandchild_ctx
+                = sentry_span_start_child(child_ctx, "littlest.teapot", NULL);
+
+            sentry_value_t unfinished_ctx
+                = sentry_span_start_child(child_ctx, "large.teapot", NULL);
+
+            sentry_value_decref(unfinished_ctx);
+            sentry_span_finish(grandchild_ctx);
+            sentry_span_finish(child_ctx);
+        }
+
+        sentry_transaction_finish();
+    }
+
     // make sure everything flushes
     sentry_close();
 

include/sentry.h

@@ -554,13 +554,21 @@ typedef struct sentry_envelope_s sentry_envelope_t;
 SENTRY_API void sentry_envelope_free(sentry_envelope_t *envelope);
 
 /**
- * Given an envelope returns the embedded event if there is one.
+ * Given an Envelope, returns the embedded Event if there is one.
  *
- * This returns a borrowed value to the event in the envelope.
+ * This returns a borrowed value to the Event in the Envelope.
  */
 SENTRY_API sentry_value_t sentry_envelope_get_event(
     const sentry_envelope_t *envelope);
 
+/**
+ * Given an Envelope, returns the embedded Transaction if there is one.
+ *
+ * This returns a borrowed value to the Transaction in the Envelope.
+ */
+SENTRY_EXPERIMENTAL_API sentry_value_t sentry_envelope_get_transaction(
+    const sentry_envelope_t *envelope);
+
 /**
  * Serializes the envelope.
  *
@@ -1230,8 +1238,8 @@ SENTRY_EXPERIMENTAL_API double sentry_options_get_traces_sample_rate(
 /* -- Performance Monitoring/Tracing APIs -- */
 
 /**
- * Constructs a new inert Transaction. The returned value needs to be passed
- * into `sentry_start_transaction` in order to be recorded and sent to sentry.
+ * Constructs a new Transaction Context. The returned value needs to be passed
+ * into `sentry_transaction_start` in order to be recorded and sent to sentry.
  *
  * See
  * https://docs.sentry.io/platforms/native/enriching-events/transaction-name/
@@ -1243,39 +1251,108 @@ SENTRY_EXPERIMENTAL_API double sentry_options_get_traces_sample_rate(
  * for an explanation of `operation`, in addition to other properties and
  * actions that can be performed on a Transaction.
  */
-SENTRY_EXPERIMENTAL_API sentry_value_t sentry_value_new_transaction(
+SENTRY_EXPERIMENTAL_API sentry_value_t sentry_value_new_transaction_context(
     const char *name, const char *operation);
 
 /**
- * Sets the `name` of a Transaction.
+ * Sets the `name` on a Transaction Context, which will be used in the
+ * Transaction constructed off of the context.
  */
-SENTRY_EXPERIMENTAL_API void sentry_transaction_set_name(
+SENTRY_EXPERIMENTAL_API void sentry_transaction_context_set_name(
     sentry_value_t transaction, const char *name);
 
 /**
- * Sets the `operation` of a Transaction.
+ * Sets the `operation` on a Transaction Context, which will be used in the
+ * Transaction constructed off of the context
  *
  * See https://develop.sentry.dev/sdk/performance/span-operations/ for
  * conventions on `operation`s.
  */
-SENTRY_EXPERIMENTAL_API void sentry_transaction_set_operation(
+SENTRY_EXPERIMENTAL_API void sentry_transaction_context_set_operation(
     sentry_value_t transaction, const char *operation);
 
 /**
- * Sets the `sampled` field on a Transaction. When turned on, the Transaction
- * will bypass all sampling options and always be sent to sentry. If this is
- * explicitly turned off in the Transaction, it will never be sent to sentry.
+ * Sets the `sampled` field on a Transaction Context, which will be used in the
+ * Transaction constructed off of the context.
+ *
+ * When passed any value above 0, the Transaction will bypass all sampling
+ * options and always be sent to sentry. If passed 0, this Transaction and its
+ * child spans will never be sent to sentry.
  */
-SENTRY_EXPERIMENTAL_API void sentry_transaction_set_sampled(
+SENTRY_EXPERIMENTAL_API void sentry_transaction_context_set_sampled(
     sentry_value_t transaction, int sampled);
 
 /**
- * Removes the sampled field on a Transaction. The Transaction will use the
- * sampling rate as defined in `sentry_options`.
+ * Removes the sampled field on a Transaction Context, which will be used in the
+ * Transaction constructed off of the context.
+ *
+ * The Transaction will use the sampling rate as defined in `sentry_options`.
  */
-SENTRY_EXPERIMENTAL_API void sentry_transaction_remove_sampled(
+SENTRY_EXPERIMENTAL_API void sentry_transaction_context_remove_sampled(
     sentry_value_t transaction);
 
+/**
+ * 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.
+ *
+ * `sentry_transaction_finish` should be called after this is invoked, otherwise
+ * the Transaction will not be sent to sentry. New spans cannot be created
+ * unless there exists an active Transaction.
+ */
+SENTRY_EXPERIMENTAL_API void sentry_transaction_start(
+    sentry_value_t transaction_context);
+
+/**
+ * Finishes and sends the current active Transaction to sentry. Any unfinished
+ * spans are removed from the Transaction before it is sent over.
+ *
+ * No new spans can be created after this is invoked unless a new Transaction is
+ * started via `sentry_transaction_start`.
+ */
+SENTRY_EXPERIMENTAL_API sentry_uuid_t sentry_transaction_finish();
+
+/**
+ * Starts a new Span.
+ *
+ * If `parent_span` is `sentry_value_null`, then the current active Transaction
+ * is used as the parent for the new Span. An active Transaction must be created
+ * via `sentry_transaction_start` in order for the Span to be successfully
+ * created.
+ *
+ * If `parent_span` is another Span, it must belong to the current active
+ * Transaction in order for Span creation to succeed. This will take ownership
+ * of any `parent_span`s that do reference non-existent Spans in the current
+ * active Transaction.
+ *
+ * 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, and `parent_span`'s ownership
+ * will be taken if the child Span could not be created.
+ */
+SENTRY_EXPERIMENTAL_API sentry_value_t sentry_span_start_child(
+    sentry_value_t parent_span, 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.
+ *
+ * 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 span);
+
 #ifdef __cplusplus
 }
 #endif

src/backends/sentry_backend_inproc.c

@@ -260,6 +260,8 @@ handle_ucontext(const sentry_ucontext_t *uctx)
 
         sentry_envelope_t *envelope
             = sentry__prepare_event(options, event, NULL);
+        // TODO(tracing): Revisit when investigating transaction flushing during
+        // hard crashes.
 
         sentry_session_t *session = sentry__end_current_session_with_status(
             SENTRY_SESSION_STATUS_CRASHED);