feat: trace connected metrics

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+### Features
+
+- Trace connected metrics ([#3450](https://github.com/getsentry/sentry-dart/pull/3450))
+  - This feature is enabled by default.
+  - To send metrics use the following APIs:
+    - `Sentry.metrics.gauge(...)`
+    - `Sentry.metrics.count(...)`
+    - `Sentry.metrics.distribution(...)`
+
 ### Dependencies
 
 - Bump Android SDK from v8.28.0 to v8.30.0 ([#3451](https://github.com/getsentry/sentry-dart/pull/3451))

packages/dart/lib/sentry.dart

@@ -61,5 +61,6 @@ export 'src/utils/url_details.dart';
 // ignore: invalid_export_of_internal_element
 export 'src/utils/breadcrumb_log_level.dart';
 export 'src/sentry_logger.dart';
+export 'src/telemetry/metric/metrics.dart';
 // ignore: invalid_export_of_internal_element
 export 'src/utils/internal_logger.dart' show SentryInternalLogger;

packages/dart/lib/src/client_reports/discarded_event.dart

@@ -70,6 +70,8 @@ extension _DataCategoryExtension on DataCategory {
         return 'feedback';
       case DataCategory.metricBucket:
         return 'metric_bucket';
+      case DataCategory.metric:
+        return 'trace_metric';
     }
   }
 }

packages/dart/lib/src/constants.dart

@@ -39,3 +39,80 @@ class SentrySpanDescriptions {
   static String dbOpen({required String dbName}) => 'Open database $dbName';
   static String dbClose({required String dbName}) => 'Close database $dbName';
 }
+
+/// Semantic attributes for telemetry.
+///
+/// Not all attributes apply to every telemetry type.
+///
+/// See https://getsentry.github.io/sentry-conventions/generated/attributes/
+/// for more details.
+@internal
+abstract class SemanticAttributesConstants {
+  SemanticAttributesConstants._();
+
+  /// The source of a span, also referred to as transaction source.
+  ///
+  /// Known values are:  `'custom'`, `'url'`, `'route'`, `'component'`, `'view'`, `'task'`.
+  static const sentrySpanSource = 'sentry.span.source';
+
+  /// Attributes that holds the sample rate that was locally applied to a span.
+  /// If this attribute is not defined, it means that the span inherited a sampling decision.
+  ///
+  /// NOTE: Is only defined on root spans.
+  static const sentrySampleRate = 'sentry.sample_rate';
+
+  /// Use this attribute to represent the origin of a span.
+  static const sentryOrigin = 'sentry.origin';
+
+  /// The release version of the application
+  static const sentryRelease = 'sentry.release';
+
+  /// The environment name (e.g., "production", "staging", "development")
+  static const sentryEnvironment = 'sentry.environment';
+
+  /// The segment name (e.g., "GET /users")
+  static const sentrySegmentName = 'sentry.segment.name';
+
+  /// The span id of the segment that this span belongs to.
+  static const sentrySegmentId = 'sentry.segment.id';
+
+  /// The name of the Sentry SDK (e.g., "sentry.dart.flutter")
+  static const sentrySdkName = 'sentry.sdk.name';
+
+  /// The version of the Sentry SDK
+  static const sentrySdkVersion = 'sentry.sdk.version';
+
+  /// The replay ID.
+  static const sentryReplayId = 'sentry.replay_id';
+
+  /// Whether the replay is buffering (onErrorSampleRate).
+  static const sentryInternalReplayIsBuffering =
+      'sentry._internal.replay_is_buffering';
+
+  /// The user ID (gated by `sendDefaultPii`).
+  static const userId = 'user.id';
+
+  /// The user email (gated by `sendDefaultPii`).
+  static const userEmail = 'user.email';
+
+  /// The user IP address (gated by `sendDefaultPii`).
+  static const userIpAddress = 'user.ip_address';
+
+  /// The user username (gated by `sendDefaultPii`).
+  static const userName = 'user.name';
+
+  /// The operating system name.
+  static const osName = 'os.name';
+
+  /// The operating system version.
+  static const osVersion = 'os.version';
+
+  /// The device brand (e.g., "Apple", "Samsung").
+  static const deviceBrand = 'device.brand';
+
+  /// The device model identifier (e.g., "iPhone14,2").
+  static const deviceModel = 'device.model';
+
+  /// The device family (e.g., "iOS", "Android").
+  static const deviceFamily = 'device.family';
+}

packages/dart/lib/src/hub.dart

@@ -9,6 +9,7 @@ import 'client_reports/discard_reason.dart';
 import 'profiling.dart';
 import 'sentry_tracer.dart';
 import 'sentry_traces_sampler.dart';
+import 'telemetry/metric/metric.dart';
 import 'transport/data_category.dart';
 
 /// Configures the scope through the callback.
@@ -317,6 +318,38 @@ class Hub {
     }
   }
 
+  Future<void> captureMetric(SentryMetric metric) async {
+    if (!_isEnabled) {
+      _options.log(
+        SentryLevel.warning,
+        "Instance is disabled and this 'captureMetric' call is a no-op.",
+      );
+    } else {
+      final item = _peek();
+      late Scope scope;
+      final s = _cloneAndRunWithScope(item.scope, null);
+      if (s is Future<Scope>) {
+        scope = await s;
+      } else {
+        scope = s;
+      }
+
+      try {
+        await item.client.captureMetric(
+          metric,
+          scope: scope,
+        );
+      } catch (exception, stacktrace) {
+        _options.log(
+          SentryLevel.error,
+          'Error while capturing metric',
+          exception: exception,
+          stackTrace: stacktrace,
+        );
+      }
+    }
+  }
+
   FutureOr<Scope> _cloneAndRunWithScope(
       Scope scope, ScopeCallback? withScope) async {
     if (withScope != null) {

packages/dart/lib/src/hub_adapter.dart

@@ -11,6 +11,7 @@ import 'scope.dart';
 import 'sentry.dart';
 import 'sentry_client.dart';
 import 'sentry_options.dart';
+import 'telemetry/metric/metric.dart';
 import 'tracing.dart';
 
 /// Hub adapter to make Integrations testable
@@ -200,6 +201,10 @@ class HubAdapter implements Hub {
   @override
   FutureOr<void> captureLog(SentryLog log) => Sentry.currentHub.captureLog(log);
 
+  @override
+  Future<void> captureMetric(SentryMetric metric) =>
+      Sentry.currentHub.captureMetric(metric);
+
   @override
   void setAttributes(Map<String, SentryAttribute> attributes) =>
       Sentry.currentHub.setAttributes(attributes);

packages/dart/lib/src/noop_hub.dart

@@ -10,6 +10,7 @@ import 'protocol/sentry_feedback.dart';
 import 'scope.dart';
 import 'sentry_client.dart';
 import 'sentry_options.dart';
+import 'telemetry/metric/metric.dart';
 import 'tracing.dart';
 
 class NoOpHub implements Hub {
@@ -97,6 +98,9 @@ class NoOpHub implements Hub {
   @override
   FutureOr<void> captureLog(SentryLog log) async {}
 
+  @override
+  Future<void> captureMetric(SentryMetric metric) async {}
+
   @override
   ISentrySpan startTransaction(
     String name,

packages/dart/lib/src/noop_sentry_client.dart

@@ -7,6 +7,7 @@ import 'scope.dart';
 import 'sentry_client.dart';
 import 'sentry_envelope.dart';
 import 'sentry_trace_context_header.dart';
+import 'telemetry/metric/metric.dart';
 
 class NoOpSentryClient implements SentryClient {
   NoOpSentryClient._();
@@ -69,4 +70,7 @@ class NoOpSentryClient implements SentryClient {
 
   @override
   FutureOr<void> captureLog(SentryLog log, {Scope? scope}) async {}
+
+  @override
+  Future<void> captureMetric(SentryMetric metric, {Scope? scope}) async {}
 }

packages/dart/lib/src/sdk_lifecycle_hooks.dart

@@ -3,6 +3,7 @@ import 'dart:async';
 import 'package:meta/meta.dart';
 
 import '../sentry.dart';
+import 'telemetry/metric/metric.dart';
 
 @internal
 typedef SdkLifecycleCallback<T extends SdkLifecycleEvent> = FutureOr<void>
@@ -96,3 +97,10 @@ class OnSpanFinish extends SdkLifecycleEvent {
 
   final ISentrySpan span;
 }
+
+@internal
+class OnProcessMetric extends SdkLifecycleEvent {
+  final SentryMetric metric;
+
+  OnProcessMetric(this.metric);
+}

packages/dart/lib/src/sentry.dart

@@ -23,6 +23,8 @@ import 'sentry_attachment/sentry_attachment.dart';
 import 'sentry_client.dart';
 import 'sentry_options.dart';
 import 'sentry_run_zoned_guarded.dart';
+import 'telemetry/metric/metrics_setup_integration.dart';
+import 'telemetry/metric/metrics.dart';
 import 'telemetry/processing/processor_integration.dart';
 import 'tracing.dart';
 import 'transport/data_category.dart';
@@ -110,6 +112,7 @@ class Sentry {
       options.addIntegration(LoadDartDebugImagesIntegration());
     }
 
+    options.addIntegration(MetricsSetupIntegration());
     options.addIntegration(FeatureFlagsIntegration());
     options.addIntegration(LogsEnricherIntegration());
     options.addIntegration(InMemoryTelemetryProcessorIntegration());
@@ -450,4 +453,6 @@ class Sentry {
       );
 
   static SentryLogger get logger => currentHub.options.logger;
+
+  static SentryMetrics get metrics => currentHub.options.metrics;
 }

packages/dart/lib/src/sentry_client.dart

@@ -18,6 +18,8 @@ import 'sentry_exception_factory.dart';
 import 'sentry_options.dart';
 import 'sentry_stack_trace_factory.dart';
 import 'sentry_trace_context_header.dart';
+import 'telemetry/metric/metric.dart';
+import 'telemetry/metric/metric_capture_pipeline.dart';
 import 'transport/client_report_transport.dart';
 import 'transport/data_category.dart';
 import 'transport/http_transport.dart';
@@ -42,14 +44,16 @@ String get defaultIpAddress => _defaultIpAddress;
 class SentryClient {
   final SentryOptions _options;
   final Random? _random;
+  final MetricCapturePipeline _metricCapturePipeline;
 
   static final _emptySentryId = Future.value(SentryId.empty());
 
   SentryExceptionFactory get _exceptionFactory => _options.exceptionFactory;
   SentryStackTraceFactory get _stackTraceFactory => _options.stackTraceFactory;
 
   /// Instantiates a client using [SentryOptions]
-  factory SentryClient(SentryOptions options) {
+  factory SentryClient(SentryOptions options,
+      {MetricCapturePipeline? metricCapturePipeline}) {
     if (options.sendClientReports) {
       options.recorder = ClientReportRecorder(options.clock);
     }
@@ -74,11 +78,12 @@ class SentryClient {
     if (enableFlutterSpotlight) {
       options.transport = SpotlightHttpTransport(options, options.transport);
     }
-    return SentryClient._(options);
+    return SentryClient._(
+        options, metricCapturePipeline ?? MetricCapturePipeline(options));
   }
 
   /// Instantiates a client using [SentryOptions]
-  SentryClient._(this._options)
+  SentryClient._(this._options, this._metricCapturePipeline)
       : _random = _options.sampleRate == null ? null : Random();
 
   /// Reports an [event] to Sentry.io.
@@ -583,6 +588,9 @@ class SentryClient {
     }
   }
 
+  Future<void> captureMetric(SentryMetric metric, {Scope? scope}) =>
+      _metricCapturePipeline.captureMetric(metric, scope: scope);
+
   FutureOr<void> close() {
     final flush = _options.telemetryProcessor.flush();
     if (flush is Future<void>) {

packages/dart/lib/src/sentry_envelope.dart

@@ -129,6 +129,21 @@ class SentryEnvelope {
     );
   }
 
+  /// Create a [SentryEnvelope] containing raw metric data payload.
+  /// This is used by the log batcher to send pre-encoded metric batches.
+  @internal
+  factory SentryEnvelope.fromMetricsData(
+    List<List<int>> encodedMetrics,
+    SdkVersion sdkVersion,
+  ) =>
+      SentryEnvelope(
+        SentryEnvelopeHeader(null, sdkVersion),
+        [
+          SentryEnvelopeItem.fromMetricsData(
+              _buildItemsPayload(encodedMetrics), encodedMetrics.length)
+        ],
+      );
+
   /// Stream binary data representation of `Envelope` file encoded.
   Stream<List<int>> envelopeStream(SentryOptions options) async* {
     yield utf8JsonEncoder.convert(header.toJson());
@@ -160,6 +175,20 @@ class SentryEnvelope {
     }
   }
 
+  /// Builds a payload in the format {"items": [item1, item2, ...]}
+  static Uint8List _buildItemsPayload(List<List<int>> encodedItems) {
+    final builder = BytesBuilder(copy: false);
+    builder.add(utf8.encode('{"items":['));
+    for (int i = 0; i < encodedItems.length; i++) {
+      if (i > 0) {
+        builder.add(utf8.encode(','));
+      }
+      builder.add(encodedItems[i]);
+    }
+    builder.add(utf8.encode(']}'));
+    return builder.takeBytes();
+  }
+
   /// Add an envelope item containing client report data.
   void addClientReport(ClientReport? clientReport) {
     if (clientReport != null) {

packages/dart/lib/src/sentry_envelope_item.dart

@@ -94,6 +94,22 @@ class SentryEnvelopeItem {
     );
   }
 
+  /// Create a [SentryEnvelopeItem] which holds pre-encoded metric data.
+  /// This is used by the buffer to send pre-encoded metric batches.
+  @internal
+  factory SentryEnvelopeItem.fromMetricsData(
+      List<int> payload, int metricsCount) {
+    return SentryEnvelopeItem(
+      SentryEnvelopeItemHeader(
+        SentryItemType.metric,
+        itemCount: metricsCount,
+        contentType: 'application/vnd.sentry.items.trace-metric+json',
+      ),
+      () => payload,
+      originalObject: null,
+    );
+  }
+
   /// Header with info about type and length of data in bytes.
   final SentryEnvelopeItemHeader header;
 

packages/dart/lib/src/sentry_item_type.dart

@@ -6,5 +6,6 @@ class SentryItemType {
   static const String profile = 'profile';
   static const String statsd = 'statsd';
   static const String log = 'log';
+  static const String metric = 'trace_metric';
   static const String unknown = '__unknown__';
 }