From c852bc248494570149147755b8548001a512e78b Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Thu, 7 Aug 2025 20:25:35 +0200 Subject: [PATCH 1/4] feat(native): transactions as automatic trace boundaries --- .../performance/add-spans-example/native.mdx | 51 ++++++++++++++++--- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/platform-includes/performance/add-spans-example/native.mdx b/platform-includes/performance/add-spans-example/native.mdx index ec91b653be182..8f1f6e8babc7b 100644 --- a/platform-includes/performance/add-spans-example/native.mdx +++ b/platform-includes/performance/add-spans-example/native.mdx @@ -38,26 +38,65 @@ void perform_checkout() { This example will send a transaction named `checkout` to Sentry. The transaction will contain a `validation` span that measures how long `validate_shopping_cart()` took and a `process` span that measures `process_shopping_cart()`. Finally, the call to `sentry_transaction_finish()` will finish the transaction and send it to Sentry. -## Trace Boundaries -By default, events, transactions, and spans will inherit the `trace_id` from the `propagation_context` as generated during SDK initialization. These values can be overridden by a downstream SDK that calls `sentry_set_trace(trace_id, parent_span_id)`, or by a user who can manually create a trace boundary using `sentry_generate_trace()`: +## Automatic Trace Boundaries -```c +By default, events, transactions, and spans will inherit the `trace_id` from the `propagation_context` as generated during SDK initialization. + +Transactions act as automatic trace boundaries, meaning whenever you create a transaction, it will start a new trace, which the SDK will apply as soon as you scope it. Once you finish the transaction, the SDK will move the trace to the `propagation_context`, from which the trace will affect any event until you scope a new transaction: + +```C // Upon init, generates a random trace_id and span_id in the propagation_context sentry_options_t *options = sentry_options_new(); sentry_init(options); -// Events, transactions and spans will inherit the trace data from this propagation_context -initialize_store(); + +// Events, transactions, and spans will inherit the trace data from this propagation_context + +// the transaction inside perform_checkout() will lead to a new trace in the propgation_context +perform_checkout(); + +// After perform_checkout() events will inherit the trace created in perform_checkout() from the propagation_context +``` + +## Manual Trace Boundaries + +The SDK will turn off managing automatic trace boundaries via transactions once manual management of trace boundaries +was requested by either a downstream SDK (using `sentry_set_trace(trace_id, parent_span_id)`) or a direct user of the +Native SDK (via `sentry_regenerate_trace()`): + +```C +sentry_options_t *options = sentry_options_new(); +sentry_init(options); // trace_id and parent_span_id usually originate from a downstream SDK // (which should be the one calling `sentry_set_trace`) const char *trace_id = "2674eb52d5874b13b560236d6c79ce8a"; const char *parent_span_id = "a0f9fdf04f1a63df"; -// Set the trace propagation_context with the given data +// Set the trace propagation_context with the given data. +// Downstream SDKs should do this as early as possible. sentry_set_trace(trace_id, parent_span_id); + +// Events, transactions and spans inside authenticate_user() will be part +// of a different trace than the one created during initialization. authenticate_user(); +``` + +```C +sentry_options_t *options = sentry_options_new(); +sentry_init(options); // Generates a new random trace and span id onto the propagation_context sentry_regenerate_trace(); +authenticate_user(); + +sentry_regenerate_trace(); +// Events, transactions, and spans inside perform_checkout() will be part of +// a different trace than the ones inside authenticate_user() perform_checkout(); ``` + +After the client called either function, the following transactions inherit that trace from the `propagation_context` and no longer act as trace boundaries. + + +If you interact with the Native SDK in the context of a downstream SDK (for instance Android, .NET, Unity, or Unreal), we urge you not to use `sentry_regenerate_trace()` since it would interfere with the traces managed from those SDKs. + From 99b9ee658f4c30cb98eaf9ba255356f41adb426b Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Fri, 8 Aug 2025 07:48:52 +0200 Subject: [PATCH 2/4] prettier --- platform-includes/performance/add-spans-example/native.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/platform-includes/performance/add-spans-example/native.mdx b/platform-includes/performance/add-spans-example/native.mdx index 8f1f6e8babc7b..0bae073db19ec 100644 --- a/platform-includes/performance/add-spans-example/native.mdx +++ b/platform-includes/performance/add-spans-example/native.mdx @@ -98,5 +98,8 @@ perform_checkout(); After the client called either function, the following transactions inherit that trace from the `propagation_context` and no longer act as trace boundaries. -If you interact with the Native SDK in the context of a downstream SDK (for instance Android, .NET, Unity, or Unreal), we urge you not to use `sentry_regenerate_trace()` since it would interfere with the traces managed from those SDKs. + If you interact with the Native SDK in the context of a downstream SDK (for + instance Android, .NET, Unity, or Unreal), we urge you not to use + `sentry_regenerate_trace()` since it would interfere with the traces managed + from those SDKs. From 05eb8a110c4a8ff3f28828ae2ab38413471cbffc Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Fri, 8 Aug 2025 11:09:19 +0200 Subject: [PATCH 3/4] Update platform-includes/performance/add-spans-example/native.mdx Co-authored-by: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com> --- platform-includes/performance/add-spans-example/native.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/performance/add-spans-example/native.mdx b/platform-includes/performance/add-spans-example/native.mdx index 0bae073db19ec..25480e9aa98fd 100644 --- a/platform-includes/performance/add-spans-example/native.mdx +++ b/platform-includes/performance/add-spans-example/native.mdx @@ -40,7 +40,7 @@ This example will send a transaction named `checkout` to Sentry. The transaction ## Automatic Trace Boundaries -By default, events, transactions, and spans will inherit the `trace_id` from the `propagation_context` as generated during SDK initialization. +By default, events will inherit the `trace_id` from the `propagation_context` as generated during SDK initialization. Transactions act as automatic trace boundaries, meaning whenever you create a transaction, it will start a new trace, which the SDK will apply as soon as you scope it. Once you finish the transaction, the SDK will move the trace to the `propagation_context`, from which the trace will affect any event until you scope a new transaction: From 8d94f06d24053e3f0c67b02e7f4d65dc83fe9f79 Mon Sep 17 00:00:00 2001 From: Mischan Toosarani-Hausberger Date: Fri, 8 Aug 2025 11:09:27 +0200 Subject: [PATCH 4/4] Update platform-includes/performance/add-spans-example/native.mdx Co-authored-by: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com> --- platform-includes/performance/add-spans-example/native.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/performance/add-spans-example/native.mdx b/platform-includes/performance/add-spans-example/native.mdx index 25480e9aa98fd..056b3ff43cb52 100644 --- a/platform-includes/performance/add-spans-example/native.mdx +++ b/platform-includes/performance/add-spans-example/native.mdx @@ -49,7 +49,7 @@ Transactions act as automatic trace boundaries, meaning whenever you create a tr sentry_options_t *options = sentry_options_new(); sentry_init(options); -// Events, transactions, and spans will inherit the trace data from this propagation_context +// Events will inherit the trace data from this propagation_context // the transaction inside perform_checkout() will lead to a new trace in the propgation_context perform_checkout();