Telemetry Processor (1): Add basic APIs for processing telemetry types e.g log, span

packages/dart/lib/src/protocol/noop_span.dart

@@ -41,4 +41,10 @@ class NoOpSpan implements Span {
 
   @override
   Map<String, dynamic> toJson() => {};
+
+  @override
+  Span get segmentSpan => this;
+
+  @override
+  SentryId get traceId => SentryId.empty();
 }

packages/dart/lib/src/protocol/sentry_log.dart

@@ -1,8 +1,9 @@
+import '../telemetry_processing/json_encodable.dart';
 import 'sentry_attribute.dart';
 import 'sentry_id.dart';
 import 'sentry_log_level.dart';
 
-class SentryLog {
+class SentryLog implements JsonEncodable {
   DateTime timestamp;
   SentryId traceId;
   SentryLogLevel level;
@@ -21,6 +22,7 @@ class SentryLog {
     this.severityNumber,
   }) : traceId = traceId ?? SentryId.empty();
 
+  @override
   Map<String, dynamic> toJson() {
     return {
       'timestamp': timestamp.toIso8601String(),

packages/dart/lib/src/protocol/simple_span.dart

@@ -6,6 +6,9 @@ class SimpleSpan implements Span {
   @override
   final Span? parentSpan;
   final Map<String, SentryAttribute> _attributes = {};
+  late final DateTime _startTimestamp;
+  late final Span _segmentSpan;
+  late final SentryId _traceId;
 
   String _name;
   SpanV2Status _status = SpanV2Status.ok;
@@ -18,7 +21,16 @@ class SimpleSpan implements Span {
     Hub? hub,
   })  : _spanId = SpanId.newId(),
         _hub = hub ?? HubAdapter(),
-        _name = name;
+        _name = name {
+    _segmentSpan = parentSpan?.segmentSpan ?? this;
+    _startTimestamp = _hub.options.clock();
+    _traceId = parentSpan != null
+        ? parentSpan!.traceId
+        : _hub.scope.propagationContext.traceId;
+  }
+
+  @override
+  SentryId get traceId => _traceId;
 
   @override
   SpanId get spanId => _spanId;
@@ -44,6 +56,9 @@ class SimpleSpan implements Span {
   @override
   bool get isFinished => _isFinished;
 
+  @override
+  Span get segmentSpan => _segmentSpan;
+
   @override
   void setAttribute(String key, SentryAttribute value) {
     _attributes[key] = value;
@@ -59,14 +74,29 @@ class SimpleSpan implements Span {
     if (_isFinished) {
       return;
     }
-    _endTimestamp = (endTimestamp ?? DateTime.now()).toUtc();
+    _endTimestamp = (endTimestamp?.toUtc() ?? _hub.options.clock());
     _isFinished = true;
     _hub.captureSpan(this);
   }
 
   @override
   Map<String, dynamic> toJson() {
-    // TODO: implement toJson
-    throw UnimplementedError();
+    double toUnixSeconds(DateTime timestamp) =>
+        timestamp.microsecondsSinceEpoch / 1000000;
+
+    return {
+      'trace_id': _traceId.toString(),
+      'span_id': _spanId.toString(),
+      'is_segment': parentSpan == null,
+      'name': _name,
+      'status': _status.name,
+      'end_timestamp':
+          _endTimestamp == null ? null : toUnixSeconds(_endTimestamp!),
+      'start_timestamp': toUnixSeconds(_startTimestamp),
+      if (parentSpan != null) 'parent_span_id': parentSpan?.spanId.toString(),
+      if (_attributes.isNotEmpty)
+        'attributes':
+            _attributes.map((key, value) => MapEntry(key, value.toJson())),
+    };
   }
 }

packages/dart/lib/src/protocol/span.dart

@@ -1,14 +1,18 @@
 import 'package:meta/meta.dart';
 
 import '../../sentry.dart';
+import '../telemetry_processing/json_encodable.dart';
 
 // Span specs: https://develop.sentry.dev/sdk/telemetry/spans/span-api/
 
 /// Represents a basic telemetry span.
-abstract class Span {
+abstract class Span implements JsonEncodable {
   @internal
   const Span();
 
+  /// Gets the id of the trace this span belongs to.
+  SentryId get traceId;
+
   /// Gets the id of the span.
   SpanId get spanId;
 
@@ -51,9 +55,13 @@ abstract class Span {
   /// Overrides if the attributes already exist.
   void setAttributes(Map<String, SentryAttribute> attributes);
 
+  @internal
+  Span get segmentSpan;
+
   @internal
   bool get isFinished;
 
   @internal
+  @override
   Map<String, dynamic> toJson();
 }

packages/dart/lib/src/protocol/unset_span.dart

@@ -8,59 +8,51 @@ import '../../sentry.dart';
 class UnsetSpan extends Span {
   const UnsetSpan();
 
+  static Never _throw() =>
+      throw UnimplementedError('$UnsetSpan APIs should not be used');
+
+  @override
+  SpanId get spanId => _throw();
+
+  @override
+  String get name => _throw();
+
   @override
-  SpanId get spanId =>
-      throw UnimplementedError('$UnsetSpan apis should not be used');
+  set name(String name) => _throw();
 
   @override
-  String get name =>
-      throw UnimplementedError('$UnsetSpan apis should not be used');
+  SpanV2Status get status => _throw();
 
   @override
-  set name(String name) =>
-      throw UnimplementedError('$UnsetSpan apis should not be used');
+  set status(SpanV2Status status) => _throw();
 
   @override
-  SpanV2Status get status =>
-      throw UnimplementedError('$UnsetSpan apis should not be used');
+  Span? get parentSpan => _throw();
 
   @override
-  set status(SpanV2Status status) =>
-      throw UnimplementedError('$UnsetSpan apis should not be used');
+  DateTime? get endTimestamp => _throw();
 
   @override
-  Span? get parentSpan =>
-      throw UnimplementedError('$UnsetSpan apis should not be used');
+  Map<String, SentryAttribute> get attributes => _throw();
 
   @override
-  DateTime? get endTimestamp =>
-      throw UnimplementedError('$UnsetSpan apis should not be used');
+  bool get isFinished => _throw();
 
   @override
-  Map<String, SentryAttribute> get attributes =>
-      throw UnimplementedError('$UnsetSpan apis should not be used');
+  void setAttribute(String key, SentryAttribute value) => _throw();
 
   @override
-  bool get isFinished =>
-      throw UnimplementedError('$UnsetSpan apis should not be used');
+  void setAttributes(Map<String, SentryAttribute> attributes) => _throw();
 
   @override
-  void setAttribute(String key, SentryAttribute value) {
-    throw UnimplementedError('$UnsetSpan apis should not be used');
-  }
+  void end({DateTime? endTimestamp}) => _throw();
 
   @override
-  void setAttributes(Map<String, SentryAttribute> attributes) {
-    throw UnimplementedError('$UnsetSpan apis should not be used');
-  }
+  Map<String, dynamic> toJson() => _throw();
 
   @override
-  void end({DateTime? endTimestamp}) {
-    throw UnimplementedError('$UnsetSpan apis should not be used');
-  }
+  Span get segmentSpan => _throw();
 
   @override
-  Map<String, dynamic> toJson() {
-    throw UnimplementedError('$UnsetSpan apis should not be used');
-  }
+  SentryId get traceId => _throw();
 }

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_processing/telemetry_buffer.dart';
+import 'telemetry_processing/telemetry_processor.dart';
 import 'transport/client_report_transport.dart';
 import 'transport/data_category.dart';
 import 'transport/http_transport.dart';
@@ -78,6 +80,10 @@ class SentryClient {
     if (options.enableLogs) {
       options.logBatcher = SentryLogBatcher(options);
     }
+    options.telemetryProcessor = DefaultTelemetryProcessor(options.log,
+        logBuffer: InMemoryTelemetryBuffer(),
+        spanBuffer: InMemoryTelemetryBuffer());
+    // TODO(next-pr): remove log batcher
     return SentryClient._(options);
   }
 
@@ -588,6 +594,7 @@ class SentryClient {
   }
 
   FutureOr<void> close() {
+    // TODO(next-pr): replace with telemetry processor
     final flush = _options.logBatcher.flush();
     if (flush is Future<void>) {
       return flush.then((_) => _options.httpClient.close());

packages/dart/lib/src/sentry_options.dart

@@ -12,6 +12,7 @@ import 'noop_client.dart';
 import 'platform/platform.dart';
 import 'sentry_exception_factory.dart';
 import 'sentry_stack_trace_factory.dart';
+import 'telemetry_processing/telemetry_processor.dart';
 import 'transport/noop_transport.dart';
 import 'version.dart';
 import 'sentry_log_batcher.dart';
@@ -543,6 +544,9 @@ class SentryOptions {
   @internal
   SentryLogBatcher logBatcher = NoopLogBatcher();
 
+  @internal
+  TelemetryProcessor telemetryProcessor = NoOpTelemetryProcessor();
+
   SentryOptions({String? dsn, Platform? platform, RuntimeChecker? checker}) {
     this.dsn = dsn;
     if (platform != null) {

packages/dart/lib/src/telemetry_processing/json_encodable.dart

@@ -0,0 +1,3 @@
+abstract interface class JsonEncodable {
+  Map<String, dynamic> toJson();
+}

packages/dart/lib/src/telemetry_processing/telemetry_buffer.dart

@@ -0,0 +1,42 @@
+import 'dart:async';
+
+import '../../sentry.dart';
+import 'json_encodable.dart';
+
+/// A buffer that batches telemetry items for efficient transmission to Sentry.
+///
+/// Collects items of type [T] and sends them in batches rather than
+/// individually, reducing network overhead.
+abstract class TelemetryBuffer<T> {
+  /// Adds an item to the buffer.
+  void add(T item);
+
+  /// When executed immediately sends all buffered items to Sentry and clears the buffer.
+  FutureOr<void> clear();
+}
+
+/// Pairs an item with its encoded bytes for size tracking and transmission.
+class BufferedItem<T> {
+  final T item;
+  final List<int> encoded;
+
+  BufferedItem(this.item, this.encoded);
+}
+
+/// In-memory buffer with time and size-based flushing.
+class InMemoryTelemetryBuffer<T extends JsonEncodable>
+    extends TelemetryBuffer<T> {
+  InMemoryTelemetryBuffer();
+
+  @override
+  void add(T item) {
+    final encoded = utf8JsonEncoder.convert(item.toJson());
+    final _ = BufferedItem(item, encoded);
+    // TODO(next-pr): finish this impl
+  }
+
+  @override
+  FutureOr<void> clear() {
+    // TODO(next-pr): finish this impl
+  }
+}