spike: MAUI idle transactions over Activities — shim battle-test + direct prototype (experiment, do not merge)

.claude/settings.json

@@ -27,7 +27,8 @@
       "WebFetch(domain:docs.sentry.io)",
       "WebFetch(domain:develop.sentry.dev)",
       "Bash(grep:*)",
-      "Bash(mv:*)"
+      "Bash(mv:*)",
+      "Bash(pwsh ./scripts/accept-verifier-changes.ps1)"
     ],
     "deny": []
   },

samples/Sentry.Samples.Maui/MauiProgram.cs

@@ -43,6 +43,9 @@ public static MauiApp CreateMauiApp()
                 // capture a certain percentage)
                 options.TracesSampleRate = 1.0F;
 
+                // Automatically create traces for navigation and user-interaction events
+                options.EnableAutoTransactions = true;
+
                 // Automatically create traces for async relay commands in the MVVM Community Toolkit
                 options.AddCommunityToolkitIntegration();
 
@@ -77,6 +80,7 @@ public static MauiApp CreateMauiApp()
             {
                 fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                 fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
+                fonts.AddFont("fa-solid-900.ttf", "FontAwesomeSolid");
             });
 
         // Configure Logging, including Structured Logs sent to Sentry (see 'EnableLogs = true')

samples/Sentry.Samples.Maui/SubmitFeedback.xaml

@@ -17,8 +17,16 @@
             <Button Text="Attach Screenshot" Clicked="OnAttachScreenshotClicked" Margin="0,20,0,0" />
 
             <StackLayout Orientation="Horizontal" HorizontalOptions="EndAndExpand" Margin="0,20,0,0" Spacing="10">
-                <Button Text="Cancel" Clicked="OnCancelClicked" BackgroundColor="Red" TextColor="White" />
-                <Button Text="Submit" Clicked="OnSubmitClicked" BackgroundColor="Green" TextColor="White" />
+                <ImageButton x:Name="CancelBtn" Clicked="OnCancelClicked" BackgroundColor="Red" HeightRequest="44" WidthRequest="44" Padding="10" SemanticProperties.Description="Cancel">
+                    <ImageButton.Source>
+                        <FontImageSource FontFamily="FontAwesomeSolid" Glyph="&#xF00D;" Color="White" Size="18" />
+                    </ImageButton.Source>
+                </ImageButton>
+                <ImageButton x:Name="SubmitBtn" Clicked="OnSubmitClicked" BackgroundColor="Green" HeightRequest="44" WidthRequest="44" Padding="10" SemanticProperties.Description="Submit">
+                    <ImageButton.Source>
+                        <FontImageSource FontFamily="FontAwesomeSolid" Glyph="&#xF00C;" Color="White" Size="18" />
+                    </ImageButton.Source>
+                </ImageButton>
             </StackLayout>
         </StackLayout>
     </ContentPage.Content>

src/Sentry.DiagnosticSource/Internal/Tracing/ActivityShim.cs

@@ -24,4 +24,5 @@ internal static class ShimKeys
 {
     public const string SpanStatus = "sentry.shim.status";
     public const string CustomSamplingContext = "sentry.shim.custom_sampling_context";
+    public const string IdleTimeout = "sentry.shim.idle_timeout";
 }

src/Sentry.DiagnosticSource/Internal/Tracing/ActivityTracingExtensions.cs

@@ -0,0 +1,60 @@
+// Alias required because Android TFMs of the core Sentry package otherwise see an ambiguous reference
+// between System.Diagnostics.Activity (global using) and Android.App.Activity (Android implicit usings).
+using Activity = System.Diagnostics.Activity;
+
+namespace Sentry.Internal.Tracing;
+
+/// <summary>
+/// The API surface Sentry's own integrations use when instrumenting directly with Activities (i.e. without
+/// the <see cref="ActivityTransactionShim"/>). These helpers cover the Sentry-specific semantics that raw
+/// <see cref="ActivitySource"/> calls don't express: starting an independent root (transaction), idle
+/// timeouts, rich span statuses.
+/// </summary>
+internal static class ActivityTracingExtensions
+{
+    /// <summary>
+    /// Starts an Activity that is an independent trace root - the Sentry-transaction equivalent.
+    /// Detaches from any ambient Activity first (Sentry semantics: a transaction begins a new trace),
+    /// and optionally carries an idle timeout, which the <see cref="SentryActivityProcessor"/> hands to
+    /// the shadow tracer so the transaction auto-finishes (or is discarded when trivial) after inactivity.
+    /// </summary>
+    public static Activity? StartRootActivity(
+        this ActivitySource source, string operation, string name, TimeSpan? idleTimeout = null)
+    {
+        Activity.Current = null;
+
+        var activity = source.CreateActivity(operation, ActivityKind.Internal);
+        if (activity is null)
+        {
+            // No listener is subscribed to this source.
+            return null;
+        }
+
+        activity.DisplayName = name;
+        if (idleTimeout is not null)
+        {
+            activity.SetFused(ShimKeys.IdleTimeout, idleTimeout);
+        }
+
+        activity.Start();
+        return activity;
+    }
+
+    /// <summary>
+    /// Resets the idle timeout of a root Activity started with an idle timeout (see
+    /// <see cref="StartRootActivity"/>), e.g. on user interaction.
+    /// </summary>
+    public static void ResetIdleTimeout(this Activity activity) =>
+        (activity.GetFused<ISpan>() as IAutoTimeoutTracer)?.ResetIdleTimeout();
+
+    /// <summary>
+    /// Stops the Activity with a rich Sentry <see cref="SpanStatus"/> - statuses like Cancelled have no
+    /// <see cref="ActivityStatusCode"/> equivalent and travel via the fused side-channel instead.
+    /// </summary>
+    public static void Stop(this Activity activity, SpanStatus status)
+    {
+        activity.SetFused(ShimKeys.SpanStatus, status);
+        activity.SetStatus(status == SpanStatus.Ok ? ActivityStatusCode.Ok : ActivityStatusCode.Error);
+        activity.Stop();
+    }
+}

src/Sentry.DiagnosticSource/Internal/Tracing/ActivityTransactionShim.cs

@@ -10,7 +10,7 @@ namespace Sentry.Internal.Tracing;
 /// <c>Hub.StartTransaction</c> invokes (via <c>SentryOptions.ActivityShimFactory</c>) for Sentry-API
 /// transactions when Activity-based tracing is enabled.
 /// </summary>
-internal sealed class ActivityTransactionShim : ActivitySpanShim, ITransactionTracer
+internal sealed class ActivityTransactionShim : ActivitySpanShim, ITransactionTracer, IAutoTimeoutTracer
 {
     private readonly ITransactionTracer _inner;
 
@@ -33,7 +33,8 @@ private ActivityTransactionShim(Activity activity, ITransactionTracer inner, IHu
         IHub hub,
         ITransactionContext context,
         IReadOnlyDictionary<string, object?> customSamplingContext,
-        DynamicSamplingContext? dynamicSamplingContext)
+        DynamicSamplingContext? dynamicSamplingContext,
+        TimeSpan? idleTimeout)
     {
         // Continue an inbound (remote) trace, propagating the upstream sampling decision.
         ActivityContext parentContext = default;
@@ -44,16 +45,27 @@ private ActivityTransactionShim(Activity activity, ITransactionTracer inner, IHu
                 context.TraceId.AsActivityTraceId(), parentSpanId.AsActivitySpanId(), flags, isRemote: true);
         }
 
+        // Sentry semantics: StartTransaction begins a new trace (unless explicitly continuing a remote one).
+        // Detach from any ambient Activity so the new activity does not become an implicit child of it -
+        // e.g. a second UI click must be an independent transaction, not a child of the (still idling) first.
+        var ambientActivity = Activity.Current;
+        Activity.Current = null;
+
         var activity = SentryActivitySources.Shim.CreateActivity(
             context.Operation, ActivityKind.Internal, parentContext);
         if (activity is null)
         {
             // No listener is subscribed to the Sentry ActivitySource.
+            Activity.Current = ambientActivity;
             return null;
         }
 
         activity.DisplayName = context.Name;
         activity.SetFused(ShimKeys.CustomSamplingContext, customSamplingContext);
+        if (idleTimeout is not null)
+        {
+            activity.SetFused(ShimKeys.IdleTimeout, idleTimeout);
+        }
         if (dynamicSamplingContext is not null)
         {
             activity.SetFused(dynamicSamplingContext);
@@ -65,10 +77,15 @@ private ActivityTransactionShim(Activity activity, ITransactionTracer inner, IHu
         {
             // The listener saw the activity but did not map it (e.g. the hub was disabled mid-flight).
             activity.Dispose();
+            Activity.Current = ambientActivity;
             return null;
         }
 
         var shim = new ActivityTransactionShim(activity, inner, hub);
+
+        // Note: out-of-band tracer finishes (idle timer) stop the backing Activity via the OnFinished
+        // hook the processor installs on every activity-derived transaction.
+
         // The processor put the shadow tracer on the scope; replace it with the shim so that
         // integrations calling hub.GetSpan()/scope.Transaction route child spans through Activities.
         hub.ConfigureScope(static (scope, s) => scope.Transaction = s, shim);
@@ -167,6 +184,8 @@ public string? TransactionName
 
     public SdkVersion Sdk => _inner.Sdk;
 
+    void IAutoTimeoutTracer.ResetIdleTimeout() => (_inner as IAutoTimeoutTracer)?.ResetIdleTimeout();
+
     public string? Platform
     {
         get => _inner.Platform;

src/Sentry.DiagnosticSource/Internal/Tracing/SentryActivityProcessor.cs

@@ -1,10 +1,9 @@
 // Alias required because Android TFMs of the core Sentry package otherwise see an ambiguous reference
 // between System.Diagnostics.Activity (global using) and Android.App.Activity (Android implicit usings).
-using Activity = System.Diagnostics.Activity;
-
 using Sentry.Extensibility;
 using Sentry.Internal.Extensions;
 using Sentry.Internal.OpenTelemetry;
+using Activity = System.Diagnostics.Activity;
 
 namespace Sentry.Internal.Tracing;
 
@@ -171,13 +170,25 @@ private void CreateRootSpan(Activity data)
         var baggageHeader = data.Baggage.AsBaggageHeader();
         var dynamicSamplingContext = data.GetFused<DynamicSamplingContext>()
                                      ?? baggageHeader.CreateDynamicSamplingContext(_replaySession);
+        var idleTimeout = data.GetFused<TimeSpan?>(ShimKeys.IdleTimeout);
         var transaction = _hub.StartTransaction(
-            transactionContext, customSamplingContext, dynamicSamplingContext
+            transactionContext, customSamplingContext, dynamicSamplingContext, idleTimeout
         );
         if (transaction is TransactionTracer tracer)
         {
             tracer.Contexts.Trace.Origin = OpenTelemetryOrigin;
             tracer.StartTimestamp = data.StartTimeUtc;
+
+            // If the tracer finishes out-of-band (e.g. its idle timer fires, capturing or discarding
+            // without the Activity lifecycle being involved), the backing Activity must be stopped too -
+            // otherwise it leaks and stays Activity.Current, silently re-parenting later spans.
+            tracer.OnFinished = () =>
+            {
+                if (!data.IsStopped)
+                {
+                    data.Stop();
+                }
+            };
         }
         _hub.ConfigureScope(static (scope, transaction) => scope.Transaction = transaction, transaction);
         transaction.SetFused(data);

src/Sentry.Maui/BindableSentryMauiOptions.cs

@@ -10,6 +10,9 @@ internal class BindableSentryMauiOptions : BindableSentryLoggingOptions
     public bool? IncludeBackgroundingStateInBreadcrumbs { get; set; }
     public bool? CreateElementEventsBreadcrumbs { get; set; } = false;
     public bool? AttachScreenshot { get; set; }
+    public bool? EnableAutoTransactions { get; set; }
+    public TimeSpan? AutoTransactionIdleTimeout { get; set; }
+    public bool? EnableUserInteractionTracing { get; set; }
 
     public void ApplyTo(SentryMauiOptions options)
     {
@@ -19,5 +22,8 @@ public void ApplyTo(SentryMauiOptions options)
         options.IncludeBackgroundingStateInBreadcrumbs = IncludeBackgroundingStateInBreadcrumbs ?? options.IncludeBackgroundingStateInBreadcrumbs;
         options.CreateElementEventsBreadcrumbs = CreateElementEventsBreadcrumbs ?? options.CreateElementEventsBreadcrumbs;
         options.AttachScreenshot = AttachScreenshot ?? options.AttachScreenshot;
+        options.EnableAutoTransactions = EnableAutoTransactions ?? options.EnableAutoTransactions;
+        options.AutoTransactionIdleTimeout = AutoTransactionIdleTimeout ?? options.AutoTransactionIdleTimeout;
+        options.EnableUserInteractionTracing = EnableUserInteractionTracing ?? options.EnableUserInteractionTracing;
     }
 }

src/Sentry.Maui/Internal/Extensions.cs

@@ -82,4 +82,20 @@ public static string ToStringOrTypeName(this object o)
         var s = o.ToString();
         return s == null || s == t.FullName ? t.Name : s;
     }
+
+    internal static Page? FindContainingPage(this Element? element)
+    {
+        const int hopLimit = 32;
+        var hops = 0;
+        var current = element;
+        while (current is not null && hops++ < hopLimit)
+        {
+            if (current is Page page)
+            {
+                return page;
+            }
+            current = current.Parent;
+        }
+        return null;
+    }
 }