feat: prepare profiler interfaces and hub integration

Author: vaind

dart/lib/src/hub.dart

@@ -2,6 +2,7 @@ import 'dart:async';
 import 'dart:collection';
 
 import 'package:meta/meta.dart';
+import 'profiling.dart';
 import 'transport/data_category.dart';
 
 import '../sentry.dart';
@@ -433,12 +434,12 @@ class Hub {
     } else {
       final item = _peek();
 
-      final samplingContext = SentrySamplingContext(
-          transactionContext, customSamplingContext ?? {});
-
       // if transactionContext has no sampled decision, run the traces sampler
-      if (transactionContext.samplingDecision == null) {
-        final samplingDecision = _tracesSampler.sample(samplingContext);
+      var samplingDecision = transactionContext.samplingDecision;
+      if (samplingDecision == null) {
+        final samplingContext = SentrySamplingContext(
+            transactionContext, customSamplingContext ?? {});
+        samplingDecision = _tracesSampler.sample(samplingContext);
         transactionContext =
             transactionContext.copyWith(samplingDecision: samplingDecision);
       }
@@ -449,6 +450,12 @@ class Hub {
         );
       }
 
+      Profiler? profiler;
+      if (_profilerFactory != null &&
+          _tracesSampler.sampleProfiling(samplingDecision)) {
+        profiler = _profilerFactory?.startProfiling(transactionContext);
+      }
+
       final tracer = SentryTracer(
         transactionContext,
         this,
@@ -457,6 +464,7 @@ class Hub {
         autoFinishAfter: autoFinishAfter,
         trimEnd: trimEnd ?? false,
         onFinish: onFinish,
+        profiler: profiler,
       );
       if (bindToScope ?? false) {
         item.scope.span = tracer;
@@ -552,6 +560,11 @@ class Hub {
   ) =>
       _throwableToSpan.add(throwable, span, transaction);
 
+  @internal
+  set profilerFactory(ProfilerFactory? value) => _profilerFactory = value;
+
+  ProfilerFactory? _profilerFactory;
+
   SentryEvent _assignTraceContext(SentryEvent event) {
     // assign trace context
     if (event.throwable != null && event.contexts.trace == null) {

dart/lib/src/hub_adapter.dart

@@ -4,6 +4,7 @@ import 'package:meta/meta.dart';
 import 'hint.dart';
 
 import 'hub.dart';
+import 'profiling.dart';
 import 'protocol.dart';
 import 'sentry.dart';
 import 'sentry_client.dart';
@@ -166,4 +167,9 @@ class HubAdapter implements Hub {
     String transaction,
   ) =>
       Sentry.currentHub.setSpanContext(throwable, span, transaction);
+
+  @internal
+  @override
+  set profilerFactory(ProfilerFactory? value) =>
+      Sentry.currentHub.profilerFactory = value;
 }

dart/lib/src/noop_hub.dart

@@ -4,6 +4,7 @@ import 'package:meta/meta.dart';
 
 import 'hint.dart';
 import 'hub.dart';
+import 'profiling.dart';
 import 'protocol.dart';
 import 'sentry_client.dart';
 import 'sentry_options.dart';
@@ -118,4 +119,8 @@ class NoOpHub implements Hub {
 
   @override
   void setSpanContext(throwable, ISentrySpan span, String transaction) {}
+
+  @internal
+  @override
+  set profilerFactory(ProfilerFactory? value) {}
 }

dart/lib/src/profiling.dart

@@ -0,0 +1,22 @@
+import 'dart:async';
+
+import 'package:meta/meta.dart';
+
+import '../sentry.dart';
+
+@internal
+abstract class ProfilerFactory {
+  Profiler startProfiling(SentryTransactionContext context);
+}
+
+@internal
+abstract class Profiler {
+  Future<ProfileInfo> finishFor(SentryTransaction transaction);
+  void dispose();
+}
+
+// See https://develop.sentry.dev/sdk/profiles/
+@internal
+abstract class ProfileInfo {
+  FutureOr<SentryEnvelopeItem> asEnvelopeItem();
+}

dart/lib/src/protocol/sentry_transaction.dart

@@ -1,5 +1,6 @@
 import 'package:meta/meta.dart';
 
+import '../profiling.dart';
 import '../protocol.dart';
 import '../sentry_tracer.dart';
 import '../utils.dart';
@@ -14,6 +15,9 @@ class SentryTransaction extends SentryEvent {
   late final Map<String, SentryMeasurement> measurements;
   late final SentryTransactionInfo? transactionInfo;
 
+  @internal
+  late final ProfileInfo? profileInfo;
+
   SentryTransaction(
     this._tracer, {
     SentryId? eventId,

dart/lib/src/sentry_options.dart

@@ -289,6 +289,23 @@ class SentryOptions {
   /// to be sent to Sentry.
   TracesSamplerCallback? tracesSampler;
 
+  double? _profilesSampleRate;
+
+  /// The sample rate for profiling traces in the range [0.0, 1.0].
+  /// This is relative to tracesSampleRate - it is a ratio of profiled traces out of all sampled traces.
+  /// At the moment, only apps targeting iOS and macOS are supported.
+  @experimental
+  double? get profilesSampleRate => _profilesSampleRate;
+
+  /// The sample rate for profiling traces in the range [0.0, 1.0].
+  /// This is relative to tracesSampleRate - it is a ratio of profiled traces out of all sampled traces.
+  /// At the moment, only apps targeting iOS and macOS are supported.
+  @experimental
+  set profilesSampleRate(double? value) {
+    assert(value == null || (value >= 0 && value <= 1));
+    _profilesSampleRate = value;
+  }
+
   /// Send statistics to sentry when the client drops events.
   bool sendClientReports = true;
 

dart/lib/src/sentry_tracer.dart

@@ -3,6 +3,7 @@ import 'dart:async';
 import 'package:meta/meta.dart';
 
 import '../sentry.dart';
+import 'profiling.dart';
 import 'sentry_tracer_finish_status.dart';
 import 'utils/sample_rate_format.dart';
 
@@ -31,6 +32,8 @@ class SentryTracer extends ISentrySpan {
 
   SentryTraceContextHeader? _sentryTraceContextHeader;
 
+  late final Profiler? profiler;
+
   /// If [waitForChildren] is true, this transaction will not finish until all
   /// its children are finished.
   ///
@@ -52,6 +55,7 @@ class SentryTracer extends ISentrySpan {
     Duration? autoFinishAfter,
     bool trimEnd = false,
     OnTransactionFinish? onFinish,
+    this.profiler,
   }) {
     _rootSpan = SentrySpan(
       this,
@@ -77,8 +81,13 @@ class SentryTracer extends ISentrySpan {
     final commonEndTimestamp = endTimestamp ?? _hub.options.clock();
     _autoFinishAfterTimer?.cancel();
     _finishStatus = SentryTracerFinishStatus.finishing(status);
-    if (!_rootSpan.finished &&
-        (!_waitForChildren || _haveAllChildrenFinished())) {
+    if (_rootSpan.finished) {
+      return;
+    }
+    if (_waitForChildren && !_haveAllChildrenFinished()) {
+      return;
+    }
+    try {
       _rootSpan.status ??= status;
 
       // remove span where its endTimestamp is before startTimestamp
@@ -131,10 +140,19 @@ class SentryTracer extends ISentrySpan {
 
       final transaction = SentryTransaction(this);
       transaction.measurements.addAll(_measurements);
+
+      if (profiler != null) {
+        if (status == null || status == SpanStatus.ok()) {
+          transaction.profileInfo = await profiler?.finishFor(transaction);
+        }
+      }
+
       await _hub.captureTransaction(
         transaction,
         traceContext: traceContext(),
       );
+    } finally {
+      profiler!.dispose();
     }
   }
 

dart/lib/src/sentry_traces_sampler.dart

@@ -67,5 +67,13 @@ class SentryTracesSampler {
     return SentryTracesSamplingDecision(false);
   }
 
+  bool sampleProfiling(SentryTracesSamplingDecision tracesSamplingDecision) {
+    double? optionsRate = _options.profilesSampleRate;
+    if (optionsRate == null || !tracesSamplingDecision.sampled) {
+      return false;
+    }
+    return _sample(optionsRate);
+  }
+
   bool _sample(double result) => !(result < _random.nextDouble());
 }

dart/pubspec.yaml

@@ -18,6 +18,7 @@ dependencies:
   uuid: ^3.0.0
 
 dev_dependencies:
+  build_runner: ^2.4.2
   mockito: ^5.1.0
   lints: ^2.0.0
   test: ^1.21.1

dart/test/hub_test.dart

@@ -1,11 +1,14 @@
 import 'package:collection/collection.dart';
+import 'package:mockito/mockito.dart';
 import 'package:sentry/sentry.dart';
 import 'package:sentry/src/client_reports/discard_reason.dart';
+import 'package:sentry/src/profiling.dart';
 import 'package:sentry/src/sentry_tracer.dart';
 import 'package:sentry/src/transport/data_category.dart';
 import 'package:test/test.dart';
 
 import 'mocks.dart';
+import 'mocks.mocks.dart';
 import 'mocks/mock_client_report_recorder.dart';
 import 'mocks/mock_sentry_client.dart';
 
@@ -374,6 +377,61 @@ void main() {
       expect(
           fixture.client.captureTransactionCalls.first.traceContext, context);
     });
+
+    test('profiler is not started by default', () async {
+      final hub = fixture.getSut();
+      final tr = hub.startTransaction('name', 'op');
+      expect(tr, isA<SentryTracer>());
+      expect((tr as SentryTracer).profiler, isNull);
+    });
+
+    test('profiler is started according to the sampling rate', () async {
+      final hub = fixture.getSut();
+      final factory = MockProfilerFactory();
+      when(factory.startProfiling(fixture._context)).thenReturn(MockProfiler());
+      hub.profilerFactory = factory;
+
+      var tr = hub.startTransactionWithContext(fixture._context);
+      expect((tr as SentryTracer).profiler, isNull);
+      verifyZeroInteractions(factory);
+
+      hub.options.profilesSampleRate = 1.0;
+      tr = hub.startTransactionWithContext(fixture._context);
+      expect((tr as SentryTracer).profiler, isNotNull);
+      verify(factory.startProfiling(fixture._context)).called(1);
+    });
+
+    test('profiler.finish() is called', () async {
+      final hub = fixture.getSut();
+      final factory = MockProfilerFactory();
+      final profiler = MockProfiler();
+      final expected = MockProfileInfo();
+      when(factory.startProfiling(fixture._context)).thenReturn(profiler);
+      when(profiler.finishFor(any)).thenAnswer((_) async => expected);
+
+      hub.profilerFactory = factory;
+      hub.options.profilesSampleRate = 1.0;
+      final tr = hub.startTransactionWithContext(fixture._context);
+      await tr.finish();
+      verify(profiler.finishFor(any)).called(1);
+      verify(profiler.dispose()).called(1);
+    });
+
+    test('profiler.dispose() is called even if not captured', () async {
+      final hub = fixture.getSut();
+      final factory = MockProfilerFactory();
+      final profiler = MockProfiler();
+      final expected = MockProfileInfo();
+      when(factory.startProfiling(fixture._context)).thenReturn(profiler);
+      when(profiler.finishFor(any)).thenAnswer((_) async => expected);
+
+      hub.profilerFactory = factory;
+      hub.options.profilesSampleRate = 1.0;
+      final tr = hub.startTransactionWithContext(fixture._context);
+      await tr.finish(status: SpanStatus.aborted());
+      verify(profiler.dispose()).called(1);
+      verifyNever(profiler.finishFor(any));
+    });
   });
 
   group('Hub scope', () {
@@ -641,10 +699,12 @@ class Fixture {
 
     final hub = Hub(options);
 
+    // A fully configured context - won't trigger a copy in startTransaction().
     _context = SentryTransactionContext(
       'name',
       'op',
       samplingDecision: SentryTracesSamplingDecision(sampled!),
+      origin: SentryTraceOrigins.manual,
     );
 
     tracer = SentryTracer(_context, hub);