[Span First #3]: Add active span parenting behaviour and more api scaffolding

packages/dart/lib/src/hub.dart

@@ -11,6 +11,7 @@ import 'protocol/unset_span.dart';
 import 'sentry_tracer.dart';
 import 'sentry_traces_sampler.dart';
 import 'protocol/noop_span.dart';
+import 'protocol/simple_span.dart';
 import 'transport/data_category.dart';
 
 /// Configures the scope through the callback.
@@ -586,12 +587,51 @@ class Hub {
         SentryLevel.warning,
         "Instance is disabled and this 'startSpan' call is a no-op.",
       );
-    } else if (_options.isTracingEnabled()) {
-      // TODO: implementation of span api behaviour according to https://develop.sentry.dev/sdk/telemetry/spans/span-api/
       return NoOpSpan();
     }
 
-    return NoOpSpan();
+    if (!_options.isTracingEnabled()) {
+      return NoOpSpan();
+    }
+
+    // Determine the parent span based on the parentSpan parameter:
+    // - If parentSpan is UnsetSpan (default), use the currently active span
+    // - If parentSpan is a specific Span, use that as the parent
+    // - If parentSpan is null, create a root/segment span (no parent)
+    // ignore: unused_local_variable
+    final Span? resolvedParentSpan;
+    if (parentSpan is UnsetSpan) {
+      // Use the currently active span from scope as parent
+      resolvedParentSpan = scope.getActiveSpan();
+    } else {
+      // Use the explicitly provided parent (can be null for root/segment span)
+      resolvedParentSpan = parentSpan;
+    }
+
+    final span =
+        SimpleSpan(name: name, parentSpan: resolvedParentSpan, hub: this);
+    if (attributes != null) {
+      span.setAttributes(attributes);
+    }
+    if (active) {
+      scope.setActiveSpan(span);
+    }
+
+    return span;
+  }
+
+  void captureSpan(Span span) {
+    if (!_isEnabled) {
+      _options.log(
+        SentryLevel.warning,
+        "Instance is disabled and this 'captureSpan' call is a no-op.",
+      );
+      return;
+    }
+
+    scope.removeActiveSpan(span);
+
+    // TODO: implement span buffer and add the span to the buffer
   }
 
   @internal

packages/dart/lib/src/hub_adapter.dart

@@ -221,4 +221,7 @@ class HubAdapter implements Hub {
 
   @override
   void removeAttribute(String key) => Sentry.currentHub.removeAttribute(key);
+
+  @override
+  void captureSpan(Span span) => Sentry.currentHub.captureSpan(span);
 }

packages/dart/lib/src/noop_hub.dart

@@ -161,4 +161,7 @@ class NoOpHub implements Hub {
     Map<String, SentryAttribute>? attributes,
   }) =>
       NoOpSpan();
+
+  @override
+  void captureSpan(Span span) {}
 }

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

@@ -3,21 +3,36 @@ import '../../sentry.dart';
 class NoOpSpan implements Span {
   const NoOpSpan();
 
+  @override
+  final String name = 'NoOpSpan';
+
+  @override
+  final SpanV2Status status = SpanV2Status.ok;
+
   @override
   void end({DateTime? endTimestamp}) {}
 
+  @override
+  Span? get parentSpan => NoOpSpan();
+
   @override
   void setAttribute(String key, SentryAttribute value) {}
 
   @override
   void setAttributes(Map<String, SentryAttribute> attributes) {}
 
   @override
-  void setName(String name) {}
+  Map<String, dynamic> toJson() => {};
 
   @override
-  void setStatus(SpanV2Status status) {}
+  set name(String name) {}
 
   @override
-  Map<String, dynamic> toJson() => {};
+  set status(SpanV2Status status) {}
+
+  @override
+  Map<String, SentryAttribute> get attributes => {};
+
+  @override
+  DateTime? get endTimestamp => null;
 }

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

@@ -1,29 +1,59 @@
 import '../../sentry.dart';
 
 class SimpleSpan implements Span {
+  final Hub hub;
+  final Map<String, SentryAttribute> _attributes = {};
+
   @override
-  void end({DateTime? endTimestamp}) {
-    // TODO: implement end
+  final Span? parentSpan;
+
+  String _name;
+  SpanV2Status _status = SpanV2Status.ok;
+  DateTime? _endTimestamp;
+
+  SimpleSpan({
+    required String name,
+    this.parentSpan,
+    Hub? hub,
+  })  : hub = hub ?? HubAdapter(),
+        _name = name;
+
+  @override
+  DateTime? get endTimestamp => _endTimestamp;
+
+  @override
+  Map<String, SentryAttribute> get attributes => Map.unmodifiable(_attributes);
+
+  @override
+  String get name => _name;
+
+  @override
+  set name(String value) {
+    _name = value;
   }
 
   @override
-  void setAttribute(String key, SentryAttribute value) {
-    // TODO: implement setAttribute
+  SpanV2Status get status => _status;
+
+  @override
+  set status(SpanV2Status value) {
+    _status = value;
   }
 
   @override
-  void setAttributes(Map<String, SentryAttribute> attributes) {
-    // TODO: implement setAttributes
+  void end({DateTime? endTimestamp}) {
+    _endTimestamp = endTimestamp ?? DateTime.now().toUtc();
+    // TODO: add this span to buffer through hub.captureSpan
   }
 
   @override
-  void setName(String name) {
-    // TODO: implement setName
+  void setAttribute(String key, SentryAttribute value) {
+    _attributes[key] = value;
   }
 
   @override
-  void setStatus(SpanV2Status status) {
-    // TODO: implement setStatus
+  void setAttributes(Map<String, SentryAttribute> attributes) {
+    _attributes.addAll(attributes);
   }
 
   @override

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

@@ -2,15 +2,41 @@ import 'package:meta/meta.dart';
 
 import '../../sentry.dart';
 
-/// Represents the Span model based on https://develop.sentry.dev/sdk/telemetry/spans/span-api/
+// Span specs: https://develop.sentry.dev/sdk/telemetry/spans/span-api/
+
+/// Represents a basic telemetry span.
 abstract class Span {
   @internal
   const Span();
 
+  /// Gets the name of the span.
+  String get name;
+
+  /// Sets the name of the span.
+  set name(String name);
+
+  /// Gets the parent span.
+  /// If null this span has no parent.
+  Span? get parentSpan;
+
+  /// Gets the status of the span.
+  SpanV2Status get status;
+
+  /// Sets the status of the span.
+  set status(SpanV2Status status);
+
+  /// Gets the end timestamp of the span.
+  DateTime? get endTimestamp;
+
+  /// Gets a read-only view of the attributes of the span.
+  ///
+  /// The returned map must not be mutated by callers.
+  Map<String, SentryAttribute> get attributes;
+
   /// Ends the span.
   ///
   /// [endTimestamp] can be used to override the end time.
-  /// If omitted, the span ends using the current time.
+  /// If omitted, the span ends using the current time when end is executed.
   void end({DateTime? endTimestamp});
 
   /// Sets a single attribute.
@@ -23,12 +49,6 @@ abstract class Span {
   /// Overrides if the attributes already exist.
   void setAttributes(Map<String, SentryAttribute> attributes);
 
-  /// Sets the status of the span.
-  void setStatus(SpanV2Status status);
-
-  /// Sets the name of the span.
-  void setName(String name);
-
   @internal
   Map<String, dynamic> toJson();
 }

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

@@ -8,6 +8,14 @@ import '../../sentry.dart';
 class UnsetSpan extends Span {
   const UnsetSpan();
 
+  @override
+  String get name =>
+      throw UnimplementedError('$UnsetSpan methods should not be used');
+
+  @override
+  Span? get parentSpan =>
+      throw UnimplementedError('$UnsetSpan methods should not be used');
+
   @override
   void end({DateTime? endTimestamp}) {
     throw UnimplementedError('$UnsetSpan methods should not be used');
@@ -24,17 +32,26 @@ class UnsetSpan extends Span {
   }
 
   @override
-  void setName(String name) {
+  Map<String, dynamic> toJson() {
     throw UnimplementedError('$UnsetSpan methods should not be used');
   }
 
   @override
-  void setStatus(SpanV2Status status) {
-    throw UnimplementedError('$UnsetSpan methods should not be used');
+  set name(String name) {
+    throw UnimplementedError();
   }
 
   @override
-  Map<String, dynamic> toJson() {
-    throw UnimplementedError('$UnsetSpan methods should not be used');
+  set status(SpanV2Status status) {
+    throw UnimplementedError();
   }
+
+  @override
+  SpanV2Status get status => throw UnimplementedError();
+
+  @override
+  Map<String, SentryAttribute> get attributes => throw UnimplementedError();
+
+  @override
+  DateTime? get endTimestamp => throw UnimplementedError();
 }

packages/dart/lib/src/scope.dart

@@ -43,6 +43,40 @@ class Scope {
   /// Returns active transaction or null if there is no active transaction.
   ISentrySpan? span;
 
+  final List<Span> _activeSpans = [];
+
+  @visibleForTesting
+  List<Span> get activeSpans => List.unmodifiable(_activeSpans);
+
+  /// Returns the currently active span, or `null` if no span is active.
+  ///
+  /// The active span is the most recently set span via [setActiveSpan].
+  /// When starting a new span with `active: true` (the default), the new span
+  /// becomes a child of this active span.
+  @internal
+  Span? getActiveSpan() {
+    return _activeSpans.lastOrNull;
+  }
+
+  /// Sets the given [span] as the currently active span.
+  ///
+  /// Active spans are used to automatically parent new spans.
+  /// When a new span is started with `active: true` (the default), it becomes
+  /// a child of the currently active span.
+  @internal
+  void setActiveSpan(Span span) {
+    _activeSpans.add(span);
+  }
+
+  /// Removes the given [span] from the active spans list.
+  ///
+  /// This should be called when a span ends to remove it from the active
+  /// span hierarchy.
+  @internal
+  void removeActiveSpan(Span span) {
+    _activeSpans.remove(span);
+  }
+
   /// The propagation context for connecting errors and spans to traces.
   /// There should always be a propagation context available at all times.
   ///