Merge branch 'main' into enha/rel-platfomr-cause

Author: denrase

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Features
+
+- Add `FeatureFlagIntegration` ([#2825](https://github.com/getsentry/sentry-dart/pull/2825))
+```dart
+// Manually track a feature flag
+Sentry.addFeatureFlag('my-feature', true);
+```
+
 ### Behavioral changes
 
 - Set log level to `warning` by default when `debug = true` ([#2836](https://github.com/getsentry/sentry-dart/pull/2836))

dart/lib/sentry.dart

@@ -24,6 +24,8 @@ export 'src/noop_isolate_error_integration.dart'
 export 'src/observers.dart';
 export 'src/performance_collector.dart';
 export 'src/protocol.dart';
+export 'src/protocol/sentry_feature_flags.dart';
+export 'src/protocol/sentry_feature_flag.dart';
 export 'src/protocol/sentry_feedback.dart';
 export 'src/protocol/sentry_proxy.dart';
 export 'src/run_zoned_guarded_integration.dart';

dart/lib/src/feature_flags_integration.dart

@@ -0,0 +1,45 @@
+import 'dart:async';
+
+import 'hub.dart';
+import 'integration.dart';
+import 'sentry_options.dart';
+import 'protocol/sentry_feature_flags.dart';
+import 'protocol/sentry_feature_flag.dart';
+
+/// Integration which handles adding feature flags to the scope.
+class FeatureFlagsIntegration extends Integration<SentryOptions> {
+  Hub? _hub;
+
+  @override
+  void call(Hub hub, SentryOptions options) {
+    _hub = hub;
+    options.sdk.addIntegration('FeatureFlagsIntegration');
+  }
+
+  FutureOr<void> addFeatureFlag(String name, bool value) async {
+    final flags =
+        _hub?.scope.contexts[SentryFeatureFlags.type] as SentryFeatureFlags? ??
+            SentryFeatureFlags(values: []);
+    final values = flags.values;
+
+    if (values.length >= 100) {
+      values.removeAt(0);
+    }
+
+    final index = values.indexWhere((element) => element.name == name);
+    if (index != -1) {
+      values[index] = SentryFeatureFlag(name: name, value: value);
+    } else {
+      values.add(SentryFeatureFlag(name: name, value: value));
+    }
+
+    flags.values = values;
+
+    await _hub?.scope.setContexts(SentryFeatureFlags.type, flags);
+  }
+
+  @override
+  FutureOr<void> close() {
+    _hub = null;
+  }
+}

dart/lib/src/protocol.dart

@@ -39,3 +39,5 @@ export 'protocol/sentry_view_hierarchy_element.dart';
 export 'protocol/span_id.dart';
 export 'protocol/span_status.dart';
 export 'sentry_event_like.dart';
+export 'protocol/sentry_feature_flag.dart';
+export 'protocol/sentry_feature_flags.dart';

dart/lib/src/protocol/contexts.dart

@@ -21,6 +21,7 @@ class Contexts extends MapView<String, dynamic> {
     SentryTraceContext? trace,
     SentryResponse? response,
     SentryFeedback? feedback,
+    SentryFeatureFlags? flags,
   }) : super({
           SentryDevice.type: device,
           SentryOperatingSystem.type: operatingSystem,
@@ -32,6 +33,7 @@ class Contexts extends MapView<String, dynamic> {
           SentryTraceContext.type: trace,
           SentryResponse.type: response,
           SentryFeedback.type: feedback,
+          SentryFeatureFlags.type: flags,
         });
 
   /// Deserializes [Contexts] from JSON [Map].
@@ -68,6 +70,9 @@ class Contexts extends MapView<String, dynamic> {
       feedback: data[SentryFeedback.type] != null
           ? SentryFeedback.fromJson(Map.from(data[SentryFeedback.type]))
           : null,
+      flags: data[SentryFeatureFlags.type] != null
+          ? SentryFeatureFlags.fromJson(Map.from(data[SentryFeatureFlags.type]))
+          : null,
     );
 
     data.keys
@@ -151,6 +156,11 @@ class Contexts extends MapView<String, dynamic> {
 
   set feedback(SentryFeedback? value) => this[SentryFeedback.type] = value;
 
+  /// Feature flags context for a feature flag event.
+  SentryFeatureFlags? get flags => this[SentryFeatureFlags.type];
+
+  set flags(SentryFeatureFlags? value) => this[SentryFeatureFlags.type] = value;
+
   /// Produces a [Map] that can be serialized to JSON.
   Map<String, dynamic> toJson() {
     final json = <String, dynamic>{};
@@ -250,6 +260,13 @@ class Contexts extends MapView<String, dynamic> {
 
           break;
 
+        case SentryFeatureFlags.type:
+          final flagsMap = flags?.toJson();
+          if (flagsMap?.isNotEmpty ?? false) {
+            json[SentryFeatureFlags.type] = flagsMap;
+          }
+          break;
+
         default:
           if (value != null) {
             json[key] = value;
@@ -273,6 +290,7 @@ class Contexts extends MapView<String, dynamic> {
       response: response?.clone(),
       runtimes: runtimes.map((runtime) => runtime.clone()).toList(),
       feedback: feedback?.clone(),
+      flags: flags?.clone(),
     )..addEntries(
         entries.where((element) => !_defaultFields.contains(element.key)),
       );
@@ -293,6 +311,7 @@ class Contexts extends MapView<String, dynamic> {
     SentryTraceContext? trace,
     SentryResponse? response,
     SentryFeedback? feedback,
+    SentryFeatureFlags? flags,
   }) =>
       Contexts(
         device: device ?? this.device,
@@ -306,6 +325,7 @@ class Contexts extends MapView<String, dynamic> {
         trace: trace ?? this.trace,
         response: response ?? this.response,
         feedback: feedback ?? this.feedback,
+        flags: flags ?? this.flags,
       )..addEntries(
           entries.where((element) => !_defaultFields.contains(element.key)),
         );
@@ -322,5 +342,6 @@ class Contexts extends MapView<String, dynamic> {
     SentryTraceContext.type,
     SentryResponse.type,
     SentryFeedback.type,
+    SentryFeatureFlags.type,
   ];
 }

dart/lib/src/protocol/sentry_feature_flag.dart

@@ -0,0 +1,51 @@
+import 'package:meta/meta.dart';
+
+import 'access_aware_map.dart';
+
+class SentryFeatureFlag {
+  final String name;
+  final bool value;
+
+  @internal
+  final Map<String, dynamic>? unknown;
+
+  SentryFeatureFlag({
+    required this.name,
+    required this.value,
+    this.unknown,
+  });
+
+  factory SentryFeatureFlag.fromJson(Map<String, dynamic> data) {
+    final json = AccessAwareMap(data);
+
+    return SentryFeatureFlag(
+      name: json['name'],
+      value: json['value'],
+      unknown: json.notAccessed(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      ...?unknown,
+      'name': name,
+      'value': value,
+    };
+  }
+
+  @Deprecated('Assign values directly to the instance.')
+  SentryFeatureFlag copyWith({
+    String? name,
+    bool? value,
+    Map<String, dynamic>? unknown,
+  }) {
+    return SentryFeatureFlag(
+      name: name ?? this.name,
+      value: value ?? this.value,
+      unknown: unknown ?? this.unknown,
+    );
+  }
+
+  @Deprecated('Will be removed in a future version.')
+  SentryFeatureFlag clone() => copyWith();
+}

dart/lib/src/protocol/sentry_feature_flags.dart

@@ -0,0 +1,53 @@
+import 'package:meta/meta.dart';
+import 'sentry_feature_flag.dart';
+import 'access_aware_map.dart';
+
+class SentryFeatureFlags {
+  static const type = 'flags';
+
+  List<SentryFeatureFlag> values;
+
+  @internal
+  Map<String, dynamic>? unknown;
+
+  SentryFeatureFlags({
+    required this.values,
+    this.unknown,
+  });
+
+  factory SentryFeatureFlags.fromJson(Map<String, dynamic> data) {
+    final json = AccessAwareMap(data);
+
+    final valuesValues = json['values'] as List<dynamic>?;
+    final values = valuesValues
+        ?.map((e) => SentryFeatureFlag.fromJson(e))
+        .toList(growable: false);
+
+    return SentryFeatureFlags(
+      values: values ?? [],
+      unknown: json.notAccessed(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      ...?unknown,
+      'values': values.map((e) => e.toJson()).toList(growable: false),
+    };
+  }
+
+  @Deprecated('Assign values directly to the instance.')
+  SentryFeatureFlags copyWith({
+    List<SentryFeatureFlag>? values,
+    Map<String, dynamic>? unknown,
+  }) {
+    return SentryFeatureFlags(
+      values: values ??
+          this.values.map((e) => e.copyWith()).toList(growable: false),
+      unknown: unknown ?? this.unknown,
+    );
+  }
+
+  @Deprecated('Will be removed in a future version.')
+  SentryFeatureFlags clone() => copyWith();
+}

dart/lib/src/sentry.dart

@@ -26,6 +26,7 @@ import 'sentry_run_zoned_guarded.dart';
 import 'tracing.dart';
 import 'transport/data_category.dart';
 import 'transport/task_queue.dart';
+import 'feature_flags_integration.dart';
 
 /// Configuration options callback
 typedef OptionsConfiguration = FutureOr<void> Function(SentryOptions);
@@ -106,6 +107,8 @@ class Sentry {
       options.addIntegration(LoadDartDebugImagesIntegration());
     }
 
+    options.addIntegration(FeatureFlagsIntegration());
+
     options.addEventProcessor(EnricherEventProcessor(options));
     options.addEventProcessor(ExceptionEventProcessor(options));
     options.addEventProcessor(DeduplicationEventProcessor(options));
@@ -361,6 +364,22 @@ class Sentry {
   /// Gets the current active transaction or span bound to the scope.
   static ISentrySpan? getSpan() => _hub.getSpan();
 
+  static Future<void> addFeatureFlag(String name, bool value) async {
+    final featureFlagsIntegration = currentHub.options.integrations
+        .whereType<FeatureFlagsIntegration>()
+        .firstOrNull;
+
+    if (featureFlagsIntegration == null) {
+      currentHub.options.logger(
+        SentryLevel.warning,
+        '$FeatureFlagsIntegration not found. Make sure Sentry is initialized before accessing the addFeatureFlag API.',
+      );
+      return;
+    }
+
+    await featureFlagsIntegration.addFeatureFlag(name, value);
+  }
+
   @internal
   static Hub get currentHub => _hub;
 

dart/test/contexts_test.dart

@@ -47,13 +47,21 @@ void main() {
 
     final gpu = SentryGpu(name: 'Radeon', version: '1');
 
+    final flags = SentryFeatureFlags(
+      values: [
+        SentryFeatureFlag(name: 'feature_flag_1', value: true),
+        SentryFeatureFlag(name: 'feature_flag_2', value: false),
+      ],
+    );
+
     final contexts = Contexts(
       device: testDevice,
       operatingSystem: testOS,
       runtimes: testRuntimes,
       app: testApp,
       browser: testBrowser,
       gpu: gpu,
+      flags: flags,
     )
       ..['theme'] = {'value': 'material'}
       ..['version'] = {'value': 9};
@@ -94,6 +102,12 @@ void main() {
       'testrt2': {'name': 'testRT2', 'type': 'runtime', 'version': '2.3.1'},
       'theme': {'value': 'material'},
       'version': {'value': 9},
+      'flags': {
+        'values': [
+          {'name': 'feature_flag_1', 'value': true},
+          {'name': 'feature_flag_2', 'value': false},
+        ]
+      },
     };
 
     test('serializes to JSON', () {
@@ -122,7 +136,7 @@ void main() {
       expect(
           clone.operatingSystem!.toJson(), contexts.operatingSystem!.toJson());
       expect(clone.gpu!.toJson(), contexts.gpu!.toJson());
-
+      expect(clone.flags!.toJson(), contexts.flags!.toJson());
       for (final element in contexts.runtimes) {
         expect(
           clone.runtimes.where(
@@ -185,6 +199,17 @@ void main() {
       expect(contexts.runtimes.length, 2);
       expect(contexts.runtimes.last.name, 'testRT2');
     });
+
+    test('set flags', () {
+      final contexts = Contexts();
+      contexts.flags = SentryFeatureFlags(
+        values: [
+          SentryFeatureFlag(name: 'feature_flag_1', value: true),
+          SentryFeatureFlag(name: 'feature_flag_2', value: false),
+        ],
+      );
+      expect(contexts.flags!.toJson(), flags.toJson());
+    });
   });
 
   group('parse contexts', () {
@@ -295,7 +320,12 @@ const jsonContexts = '''
       "raw_description":"runtime description RT1 1.0"
    },
    "browser": {"version": "12.3.4"},
-   "gpu": {"name": "Radeon", "version": "1"}
-  
+   "gpu": {"name": "Radeon", "version": "1"},
+   "flags": {
+      "values": [
+        {"name": "feature_flag_1", "value": true},
+        {"name": "feature_flag_2", "value": false}
+      ]
+   }
 }
 ''';