…3391)

Co-authored-by: GitHub <[email protected]>

* [Span First #1]: Add simple span API (#3360)

* Add setAttributeS

* Update

* Update

* Add removeAttribute

* Add scope test

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Merge scope

* Update

* Fix analyzer

* Fix analyzer

* Add Spanv2 protocol

* Add Spanv2 protocol

* Update

* Rename

* Update

* Update

* Update

* Update

* Update

* Analyze

* Consistency

* Update API

* Update API

* Remove debug print

* Fix analyze

* [Span First #2]: Add envelope type to Dart layer (#3366)

* Add setAttributeS

* Update

* Update

* Add removeAttribute

* Add scope test

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Merge scope

* Update

* Fix analyzer

* Fix analyzer

* Add Spanv2 protocol

* Add Spanv2 protocol

* Update

* Rename

* Update

* Update

* Update

* Add support for spans protocol

* Add envelope structure

* Update

* Update

* Remove buffer

* Update

* Update

* Update

* Dedupe item payload creation

* Analze

* Analyze

* Update

* Update

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

* Update

* Updateg

* Update

* Update

* Update

* Remove unnecessary import

* Remove unnecessary import

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Update

* Refactor Span implementations to standardize spanId handling and improve attribute management. Added spanId to SimpleSpan and NoOpSpan, and updated UnsetSpan to throw errors for unimplemented methods. Enhanced tests to verify spanId creation.

* Add tests for finished spans as parents and handling of disabled tracing

- Introduced a test to verify that a finished span can be used as a parent for a new span.
- Added a test to ensure that when tracing is disabled, starting a span results in a NoOpSpan and does not affect active spans.

* Implement idempotent behavior for ending spans and enhance tests for span finalization

- Added a check in the `end` method of `SimpleSpan` to prevent multiple calls from altering the end timestamp after the span is finished.
- Introduced a new test to verify that calling `end` on an already finished span does not change its state or timestamp.
- Updated existing tests to use a consistent method for obtaining the hub instance.

* Fix end method in SimpleSpan to ensure captureSpan is called after setting isFinished flag

* Update scope_test to use getActiveSpan method for retrieving the last active span

* Refactor Span documentation and clean up tests

- Removed redundant comment about parent span being null in the Span interface.
- Enhanced documentation for the attributes getter to specify the use of Map.unmodifiable.
- Cleaned up the hub_span_test by removing an incomplete test case regarding finished spans as parents.
- Updated scope_test to include assertions for active spans in the cloned state.

* Update TODO comment for clarity

* Update TODO comment for span processing

* Rename test for setting span status to improve clarity

* Fix end method in SimpleSpan to ensure endTimestamp is set as UTC

- Updated the end method to convert the endTimestamp to UTC correctly.
- Added a test to verify that endTimestamp is set as UTC when the end method is called.

* Update span_test to ensure endTimestamp is set as UTC in tests

- Modified the test to convert the end timestamp to UTC before passing it to the span's end method, ensuring consistency with the expected behavior.

* chore: update packages/flutter/scripts/update-android.sh to 8.28.0 (#3391)

Co-authored-by: GitHub <[email protected]>

* fix(jni): dart to native type conversion (#3372)

* Update

* Update

* Fix test

* Update

* Update

* Update

* Update

* Add JNI utility tests for Dart to Java object conversion

This commit introduces a new test file for verifying the conversion of Dart objects to JNI types, including primitives, lists, and maps. The tests ensure that null values are dropped appropriately and that nested structures are handled correctly. The tests are designed to run on the Android platform only.

* Rename native FFI JNI utility test file to native JNI utility test for clarity

* Refactor JNI utility tests to improve clarity and consistency

This commit updates the JNI utility tests by renaming assertion functions for better readability and consistency. The changes include replacing direct assertions with dedicated helper functions that check for equality, ensuring null checks are performed, and enhancing the overall structure of the test cases. This refactor aims to improve maintainability and clarity in the test suite.

* Remove null checks from setContexts and setExtra methods in SentryNativeJava class for cleaner code.

* Refactor JNI utility tests to enhance structure and readability

This commit updates the JNI utility tests by restructuring the test cases for better clarity and maintainability. Key changes include the introduction of local variables for input data, improved assertion handling with arena management, and the renaming of helper functions for consistency. These modifications aim to streamline the testing process and ensure accurate validation of Dart to JNI object conversions.

* Enhance JNI utility tests by adding missing line breaks for improved readability

This commit introduces line breaks in the JNI utility test file to enhance the overall readability of the code. The changes aim to improve the visual structure of the test cases, making it easier to follow the logic and organization of the tests.

* Pin prepare action release to specific commit

* release: 9.9.0-beta.4

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

* feat(telemetry): Enhance telemetry processing with buffer registration and mock implementation

- Updated `DefaultTelemetryProcessor` to include a method for registering telemetry buffers.
- Refactored the constructor to accept a logger callback instead of Sentry options.
- Introduced `MockTelemetryBuffer` for testing purposes, allowing simulation of buffer behavior.
- Added comprehensive tests for the `DefaultTelemetryProcessor`, covering initialization, item addition, and buffer flushing.

* refactor(tests): Remove unused initialization tests from telemetry processor tests

- Deleted the initialization test group in `telemetry_processor_test.dart` as the tests were marked with TODOs and not implemented. This cleanup improves the clarity and focus of the test suite.

* feat(telemetry): Integrate telemetry processing into SentryOptions

- Added a `telemetryProcessor` field to `SentryOptions`, initialized with a `NoOpTelemetryProcessor`.
- Enhanced `DefaultTelemetryProcessor` to manage span and log buffers based on Sentry options.
- Implemented methods for adding spans and logs, along with flushing buffers for telemetry data transmission.
- Introduced a `NoOpTelemetryProcessor` for scenarios where telemetry is not enabled.

* refactor(telemetry): Simplify telemetry buffer handling in DefaultTelemetryProcessor

- Removed unnecessary comments regarding buffer creation based on options.
- Updated tests to reflect changes in method names for adding spans and logs.
- Enhanced test coverage for handling cases where buffers may not be registered, ensuring no exceptions are thrown.
- Introduced a test subclass to facilitate mock buffer creation for testing purposes.

* feat(telemetry): Implement in-memory telemetry buffer for span and log processing

- Introduced `InMemoryTelemetryBuffer` class for managing telemetry items with time and size-based flushing.
- Updated `DefaultTelemetryProcessor` to utilize `InMemoryTelemetryBuffer` for span and log buffering.
- Removed obsolete buffer creation methods to streamline buffer initialization.
- Adjusted tests to instantiate `DefaultTelemetryProcessor` directly, enhancing clarity and consistency.

* fix(span): Ensure child span inherits traceId from parent correctly

- Updated the SimpleSpan constructor to inherit traceId from the parent span if available, ensuring consistent trace propagation.
- Removed the condition that set 'is_segment' to true when there is no parent span, simplifying the span representation.
- Added a test to verify that child spans correctly inherit the traceId from their parent, even after resetting the propagation context.

* fix(noop_span): Correct segmentSpan implementation to return the current instance

- Updated the segmentSpan getter in NoOpSpan to return the current instance instead of a new NoOpSpan, ensuring proper span behavior and consistency in span hierarchy.

* Formatting

* feat(telemetry): Enhance DefaultTelemetryProcessor with customizable buffer factories

- Introduced `TelemetryBufferFactory` type for creating telemetry buffers, allowing for custom buffer implementations.
- Updated `DefaultTelemetryProcessor` constructor to accept optional buffer factory parameters for spans and logs, defaulting to `InMemoryTelemetryBuffer`.
- Modified tests to utilize mock buffers, improving test flexibility and clarity in buffer handling.

* refactor(span): Update SimpleSpan to use configurable clock for timestamps

- Changed the initialization of _startTimestamp to use a configurable clock from the Hub options instead of the current UTC time.
- Updated the _endTimestamp assignment to also utilize the Hub's clock, ensuring consistent time handling across spans.

* refactor(telemetry): Simplify DefaultTelemetryProcessor by removing buffer factory parameters

- Removed the optional buffer factory parameters from the DefaultTelemetryProcessor constructor, directly accepting span and log buffers instead.
- Streamlined the addSpan and addLog methods to utilize a common _add method for handling telemetry items.
- Updated tests to reflect changes in the DefaultTelemetryProcessor instantiation, enhancing clarity in buffer management.

* refactor(telemetry): Remove unused telemetry item import from NoOpSpan

- Eliminated the import of `telemetry_item.dart` in `noop_span.dart` as it is no longer needed.
- Streamlined the `NoOpSpan` class to focus on its core functionality without unnecessary dependencies.

* refactor(telemetry): Replace TelemetryItem with SentryEncodable interface

- Updated SentryLog and Span classes to implement the new SentryEncodable interface instead of the deprecated TelemetryItem.
- Refactored TelemetryBuffer and related classes to work with SentryEncodable, enhancing type safety and consistency across telemetry processing.
- Introduced SentryEncodable interface to define a common method for JSON serialization, streamlining the encoding process for telemetry items.

* docs(telemetry): Add documentation for SentryEncodable and TelemetryBuffer

- Introduced a description for the SentryEncodable interface, clarifying its purpose for JSON serialization.
- Added documentation for the TelemetryBuffer class, explaining its functionality in batching telemetry items for efficient transmission to Sentry.

* refactor(span): Improve traceId inheritance logic in SimpleSpan constructor

- Updated the SimpleSpan constructor to conditionally inherit traceId from the parent span only if it is not empty, enhancing trace propagation accuracy.
- Simplified the logic for determining the traceId, ensuring clearer and more reliable span behavior.

* fix(span): Ensure endTimestamp is stored in UTC format in SimpleSpan

- Updated the assignment of _endTimestamp in SimpleSpan to convert endTimestamp to UTC if provided, ensuring consistent timestamp handling across spans.

* feat(telemetry): Prevent NoOpSpan and UnsetSpan from being added to the buffer

- Updated the addSpan method in DefaultTelemetryProcessor to ignore NoOpSpan and UnsetSpan instances, ensuring they are not added to the telemetry buffer.
- Added unit tests to verify that NoOpSpan and UnsetSpan cannot be added to the buffer, enhancing the robustness of span handling.

* docs(telemetry): Enhance documentation for TelemetryProcessor methods

- Added documentation comments for the addSpan, addLog, and flush methods in the TelemetryProcessor interface, clarifying their functionality and usage.
- Improved code readability and maintainability by providing clear descriptions of method behaviors and expected outcomes.

* docs(telemetry): Remove outdated flush method documentation in DefaultTelemetryProcessor

- Deleted the documentation comments for the flush method in DefaultTelemetryProcessor, as they were no longer relevant.
- This change helps maintain clarity and accuracy in the codebase by ensuring that documentation reflects the current implementation.

* docs(telemetry): Remove outdated constructor documentation in DefaultTelemetryProcessor

- Deleted the documentation comment for the constructor in DefaultTelemetryProcessor, as it was no longer relevant.
- This change helps maintain clarity and accuracy in the codebase by ensuring that documentation reflects the current implementation.

* refactor(telemetry): Remove SentryEncodable interface and simplify related classes

- Eliminated the SentryEncodable interface, removing its implementation from SentryLog and Span classes.
- Updated TelemetryBuffer and its subclasses to no longer depend on SentryEncodable, enhancing type flexibility.
- Adjusted related methods to accommodate the removal of the interface, streamlining the telemetry processing codebase.

* refactor(telemetry): Rename BufferedItem to EncodedItem and update related types

- Renamed BufferedItem class to EncodedItem to better reflect its purpose of pairing items with their encoded bytes for size tracking and transmission.
- Updated InMemoryTelemetryBuffer to use an ItemEncoder type instead of a serializer function, enhancing clarity in item encoding.
- Adjusted the add method to utilize the new encoder, streamlining the telemetry processing workflow.

* refactor(span): Simplify traceId assignment in SimpleSpan constructor

- Updated the traceId assignment logic in the SimpleSpan constructor to enhance clarity by removing unnecessary null checks.
- Added an override for the toJson method, ensuring proper JSON serialization of the SimpleSpan instance.

* refactor(telemetry): Integrate telemetry processing into SentryClient

- Added telemetry processing capabilities to SentryClient by introducing DefaultTelemetryProcessor and InMemoryTelemetryBuffer for log and span handling.
- Updated the constructor to initialize the telemetry processor, preparing for future removal of the log batcher.
- Renamed EncodedItem to BufferedItem to better represent its role in telemetry data management.

* refactor(telemetry): Implement JsonEncodable interface for telemetry classes

- Introduced JsonEncodable interface to standardize JSON serialization across telemetry-related classes.
- Updated SentryLog and Span classes to implement the new interface, ensuring consistent toJson method implementation.
- Simplified InMemoryTelemetryBuffer by removing the encoder parameter, directly utilizing the toJson method for item encoding.

* refactor(telemetry): Update telemetry buffer implementation and enhance SentryClient tests

- Removed unused import from sentry_client.dart to clean up the code.
- Updated InMemoryTelemetryBuffer's add method to use a temporary variable for BufferedItem, improving clarity.
- Enhanced SentryClient tests by adding a new group to verify the default telemetry processor initialization, ensuring proper setup during client instantiation.

* refactor(telemetry): Rename flush methods to clear for clarity

- Updated TelemetryBuffer and its implementations to rename the flush method to clear, reflecting its functionality of sending and clearing buffered items.
- Adjusted SentryClient to include a TODO for future telemetry processor integration.
- Enhanced documentation to clarify the purpose of the clear method in telemetry processing.

* refactor(telemetry): Rename flush method to clear in MockTelemetryBuffer

- Updated MockTelemetryBuffer to rename the flush method to clear, aligning with its intended functionality of clearing buffered items.
- Adjusted related test cases to reflect the method name change, ensuring consistency across the telemetry processing tests.

* refactor(telemetry): Update futures type in telemetry processor

- Changed the type of futures in DefaultTelemetryProcessor from Future<void> to Future, allowing for more flexibility in handling future results.
- This adjustment improves the clarity and usability of the telemetry processing logic.

* refactor(telemetry): Rename asyncFlush to asyncClear in MockTelemetryBuffer

- Updated the MockTelemetryBuffer class to rename the asyncFlush parameter to asyncClear, aligning with the method's functionality of clearing items.
- Adjusted related test cases to reflect this change, ensuring consistency in the telemetry processing tests.

* Telemetry Processor (2): In memory buffer implementation (#3409)

* feat(telemetry): Enhance InMemoryTelemetryBuffer with envelope builders and logging

- Introduced `EnvelopeBuilder` interface and implementations for log and span items, facilitating structured telemetry data handling.
- Updated `InMemoryTelemetryBuffer` to utilize envelope builders for encoding and sending telemetry items, improving data transmission efficiency.
- Enhanced logging capabilities within `InMemoryTelemetryBuffer` to capture encoding errors and buffer flushing events.
- Added comprehensive tests for `InMemoryTelemetryBuffer`, ensuring correct behavior for item addition, flushing, and error handling.

* refactor(telemetry): Rename clear method to flush for consistency

- Updated the TelemetryBuffer interface and its implementations to rename the `clear` method to `flush`, aligning with its functionality of sending buffered items.
- Adjusted the InMemoryTelemetryBuffer and DefaultTelemetryProcessor classes to reflect this change, ensuring consistent terminology across the codebase.
- Modified related tests to use the new `flush` method, maintaining test integrity and clarity.

* feat(telemetry): Introduce TelemetryBufferPolicy and enhance InMemoryTelemetryBuffer

- Added a new `TelemetryBufferPolicy` class to define flushing behavior with configurable parameters such as `flushTimeout`, `maxBufferSizeBytes`, and `maxItemCount`.
- Updated `InMemoryTelemetryBuffer` to utilize `TelemetryBufferPolicy`, allowing for more flexible buffer management based on item count and size.
- Enhanced the SentryClient initialization to include a maximum item count for telemetry buffering, improving data handling efficiency.

* feat(telemetry): Integrate TelemetryBufferPolicy into SentryClient initialization

- Updated SentryClient to utilize the new TelemetryBufferPolicy for managing telemetry item count, enhancing buffer management.
- This change improves the efficiency of telemetry data handling by allowing for configurable item limits during client setup.

* fix(telemetry): Correct defaultMaxBufferSizeBytes initialization

- Updated the initialization of defaultMaxBufferSizeBytes in TelemetryBufferPolicy to use a more concise expression, improving code clarity and consistency.

* refactor(telemetry): Simplify InMemoryTelemetryBuffer initialization

- Removed the policy parameter from InMemoryTelemetryBuffer initialization in SentryClient, streamlining the constructor and improving code clarity.
- This change prepares for future enhancements related to telemetry processing.

* refactor(telemetry): Rename TelemetryBufferPolicy to TelemetryBufferConfig

- Renamed the TelemetryBufferPolicy class to TelemetryBufferConfig for improved clarity and consistency in naming.
- Updated references in InMemoryTelemetryBuffer and related tests to reflect the new class name, ensuring seamless integration and functionality.

* refactor(telemetry): Update InMemoryTelemetryBuffer to use TelemetryBufferConfig

- Replaced references to TelemetryBufferPolicy with TelemetryBufferConfig in InMemoryTelemetryBuffer and its tests, ensuring consistent naming and improved clarity.
- Adjusted the constructor and internal logic to utilize the new configuration class for buffer management parameters.

* feat(telemetry): Reject items exceeding max buffer size in InMemoryTelemetryBuffer

- Implemented a check in InMemoryTelemetryBuffer to drop items that exceed the maximum buffer size, preventing oversized items from being added.
- Updated tests to verify that items exceeding the buffer size are correctly rejected and not sent to the transport.

* feat(span-first): Refactor telemetry spans to `SentrySpanV2` (#3422)

* Refactor telemetry spans to use SentrySpanV2

- Updated span-related classes to implement SentrySpanV2, enhancing the telemetry system's structure and consistency.
- Replaced instances of Span with SentrySpanV2 across Hub, NoOpHub, and related classes to unify span handling.
- Introduced new span types: RecordingSentrySpanV2, NoOpSentrySpanV2, and UnsetSentrySpanV2 for improved span management.
- Removed obsolete span classes and methods, streamlining the codebase and enhancing clarity.
- Updated tests to reflect changes in span handling, ensuring robust coverage for new implementations.

* Remove unnecessary comment from in_memory_telemetry_buffer.dart and update DefaultTelemetryProcessor to remove outdated TODO comment regarding item type.

* Refactor in_memory_telemetry_buffer.dart to enhance error logging and type safety

- Updated OnFlushCallback type parameter from S to T for improved clarity.
- Enhanced error logging to include runtime type information and stack traces for better debugging.
- Simplified item count increment logic for consistency.

* Refactor telemetry buffer classes for improved clarity and functionality

- Changed abstract class declaration to use 'abstract base' for better type safety.
- Updated InMemoryTelemetryBuffer and GroupedInMemoryTelemetryBuffer to use 'final' for class declarations, enhancing immutability.
- Simplified error handling in the onFlush method by using a more generic Future type.
- Improved item storage logic in GroupedInMemoryTelemetryBuffer by utilizing putIfAbsent for clarity.
- Removed unnecessary imports from telemetry_buffer.dart to streamline the codebase.

* Refactor span handling and telemetry logging for improved clarity

- Updated span-related classes to replace 'defaultTraceId' with 'traceId' and 'onSpanEnded' with 'onSpanEnd' for consistency in naming conventions.
- Enhanced logging in RecordingSentrySpanV2 to include warnings for invalid span states, improving error tracking.
- Removed unnecessary imports from sentry_client.dart to streamline the codebase.
- Updated tests to reflect changes in span initialization and logging, ensuring robust coverage for new implementations.

* Enhance span logging for invalid states in Hub class

- Added a warning log for invalid span states in the captureSpan method, improving error tracking and debugging capabilities.
- Removed redundant telemetryProcessor call for NoOpSentrySpanV2, streamlining span handling logic.

* Refactor MutableAttributesMixin declaration for clarity

- Changed the declaration of MutableAttributesMixin from 'abstract mixin class' to 'mixin', enhancing code clarity and consistency in the telemetry attributes implementation.

* Refactor telemetry imports and span handling for improved clarity

- Replaced imports from 'telemetry/telemetry.dart' with 'telemetry/span/sentry_span_v2.dart' across multiple files to streamline the codebase and enhance clarity in span management.
- Updated span-related classes to utilize the new SentrySpanV2 structure, improving consistency in telemetry span handling.
- Removed obsolete 'attributes_mixin.dart' and 'telemetry.dart' files, consolidating span functionality into a more cohesive structure.
- Adjusted tests to reflect changes in span initialization and imports, ensuring robust coverage for new implementations.

* Enhance error logging in InMemoryTelemetryBuffer and streamline span key extraction

- Updated error logging in _BaseInMemoryTelemetryBuffer to include the type parameter T for improved clarity in encoding failures.
- Moved the spanGroupKeyExtractor declaration in DefaultTelemetryProcessorIntegration to a more appropriate location, ensuring better organization and visibility for testing purposes.

* Add spanId initialization to RecordingSentrySpanV2 in tests

- Updated the createSpan method in telemetry_processor_integration_test.dart, telemetry_processor_test.dart, and span_test.dart to include spanId initialization using SpanId.newId().
- This change ensures consistent span identification across test cases, enhancing the reliability of telemetry span handling.

* Update spanGroupKeyExtractor to use segmentSpan for improved span identification

- Modified the spanGroupKeyExtractor in DefaultTelemetryProcessorIntegration to utilize segmentSpan.spanId instead of spanId, enhancing the accuracy of span grouping in telemetry processing.

* Remove test for empty attributes map in span_test.dart to streamline test coverage

* Add spanId initialization in createSpan method for consistent span identification

- Updated the createSpan method in scope_test.dart to include spanId initialization using SpanId.newId(), ensuring uniformity in span identification across tests.

* Refactor telemetry processing classes for improved organization and functionality

- Updated import paths in sentry_options.dart to reflect new structure.
- Introduced new classes for telemetry buffering and processing, including TelemetryBuffer, InMemoryTelemetryBuffer, and DefaultTelemetryProcessor, enhancing the management of telemetry data.
- Added TelemetryBufferConfig for configurable buffer settings.
- Streamlined test imports to align with the new class structure, ensuring consistency across the codebase.

* Refactor _BaseInMemoryTelemetryBuffer for improved organization

- Rearranged member variable declarations in _BaseInMemoryTelemetryBuffer to enhance code readability and maintainability. This change does not affect functionality but improves the overall structure of the class.

* Clarify attributes getter documentation

Updated the documentation for the attributes getter to clarify that it returns a read-only view using Map.unmodifiable and that the map must not be mutated.

* Refactor spanId handling in RecordingSentrySpanV2 and related classes

- Removed spanId parameter from the RecordingSentrySpanV2 constructor, initializing it directly within the class.
- Updated spanGroupKeyExtractor to handle null segmentSpan gracefully.
- Adjusted createSpan methods in tests to reflect the removal of spanId initialization, ensuring consistency across test cases.

* Update segmentSpan assignment in RecordingSentrySpanV2 constructor

- Modified the assignment of _segmentSpan to use parentSpan directly if segmentSpan is null, ensuring more robust handling of parent span relationships.

* Update segmentSpan getter in RecordingSentrySpanV2 for improved null handling

- Changed the segmentSpan getter to return itself when _segmentSpan is null, enhancing the logic for span relationships.
- Updated the corresponding test to reflect this change in behavior, ensuring clarity in expected outcomes.

* Refactor spanGroupKeyExtractor in DefaultTelemetryProcessorIntegration for improved span identification

- Updated the spanGroupKeyExtractor to directly use segmentSpan.spanId, removing the null check for segmentSpan. This change enhances the accuracy of span grouping in telemetry processing.
- Removed outdated comment in RecordingSentrySpanV2 regarding segmentSpan behavior, clarifying the getter's functionality.

* Add DefaultTelemetryProcessorIntegration to Sentry options

- Integrated DefaultTelemetryProcessorIntegration into the Sentry options, enhancing telemetry processing capabilities.
- Updated tests to verify the addition of DefaultTelemetryProcessorIntegration, ensuring it is included in the integration list during initialization.

* Enhance documentation and internal logging

- Introduced detailed logging for buffer operations in _BaseInMemoryTelemetryBuffer, including item encoding and flushing events.
- Updated the DefaultTelemetryProcessor to log when the telemetry processor is already set, preventing redundant assignments.
- Added new callback types for better handling of telemetry item encoding and flushing.
- Refactored the segmentSpan getter in RecordingSentrySpanV2 for clarity and improved documentation on span relationships.

* feat(span-first): Add `traceLifecycle` option, dsc to span and sampling to `startSpan` (#3429)

* feat(span): Enhance span sampling and telemetry context handling

- Introduced sampling decision logic in the Hub class to determine whether spans should be recorded based on a random sampling rate.
- Updated the captureSpan method to return a Future, allowing for asynchronous handling of span captures.
- Enhanced SentryTraceContextHeader to create headers from RecordingSentrySpanV2, improving telemetry context management.
- Added a factory method for creating SentryTraceContextHeader from spans, facilitating better integration with the telemetry system.
- Updated tests to reflect changes in span handling and sampling logic, ensuring robust coverage for new implementations.

* refactor: rename dscFactory to dscCreator and update related implementations

- Renamed the `dscFactory` parameter to `dscCreator` in the Hub and RecordingSentrySpanV2 classes for clarity.
- Updated all references and implementations across the codebase to reflect this change.
- Added a new `captureSpan` method in NoOpSentryClient to support the updated span handling.
- Adjusted tests to accommodate the new parameter name.

* feat: introduce span sampling context and lifecycle management

- Added `SentryTraceLifecycle` enum to control trace data collection methods (streaming vs static).
- Enhanced `SentrySamplingContext` to include span sampling context and lifecycle options.
- Updated `RecordingSentrySpanV2` to support sampling decisions for root and child spans.
- Modified `Hub` class to evaluate sampling decisions at the root span level, ensuring child spans inherit the sampling decision.
- Added tests to verify sampling inheritance and behavior across nested spans.
- Updated example application to utilize the new streaming trace lifecycle option.

* refactor: update span handling and sampling context management

- Refactored `captureSpan` method in `Hub`, `NoOpSentryClient`, and `SentryClient` to return void instead of FutureOr<void> for consistency.
- Enhanced `SentrySamplingContext` with new constructors for transaction and span contexts, improving clarity in sampling decision evaluations.
- Updated `SentryTracesSampler` to utilize the new sampling context structure, ensuring proper handling of static and streaming trace lifecycles.
- Added comments to clarify the limitations of distributed trace support in the current implementation.
- Adjusted tests to validate the new span handling and sampling context behavior, ensuring robust coverage for the updated functionality.

* refactor: enhance SentrySamplingContext with dual-mode support

- Updated `SentrySamplingContext` to clarify its dual-mode functionality for transaction and span contexts, ensuring backwards compatibility.
- Added runtime checks and comments to guide usage in static and streaming modes.
- Included TODOs for future simplification once the legacy transaction API is removed.

* fix: update error types in SentrySamplingContext tests

- Changed expected error types in `SentrySamplingContext` tests from `AssertionError` to `StateError` for accessing `transactionContext` and `spanContext`.
- Improved formatting in test cases for better readability.
- Removed unnecessary blank lines in mock telemetry processor.

* fix: correct sampling decision references in SentryTraceContextHeader

- Updated the `SentryTraceContextHeader` class to use the correct sampling decision properties from the `span` object instead of the `hub.scope.propagationContext`.
- Ensured that `sampleRand` and `sampled` are now accurately derived from the `span.samplingDecision`, improving the integrity of trace context handling.

* fix: update return statements in captureSpan method for consistency

- Modified the `captureSpan` method in the `Hub` class to return void instead of null for better clarity and consistency in handling no-op scenarios.
- Ensured that the return type aligns with the recent refactor of span handling, improving overall code readability.

* fix: update captureSpan method to return void for consistency

- Changed the return type of the `captureSpan` method in `MockSentryClient` from `FutureOr<void>` to `void` to align with recent refactoring efforts.
- This update enhances clarity and consistency in the method's behavior, following similar changes made in the `Hub` class.

* fix: update sampling decision reference in trace context tests

- Modified the test for `SentryTraceContextHeader` to use the sampling decision from the span instead of the propagation context.
- Updated the test case to reflect the new sampling decision structure, ensuring accurate testing of trace context handling.

* refactor: clean up unused imports and methods in trace context and telemetry processor

- Removed unnecessary imports from `SentryTraceContextHeader` to streamline the codebase.
- Eliminated the unused `close` method in `MockTelemetryProcessor`, enhancing code clarity and maintainability.

* Rename DscCreator to DscCreatorCallback

* Document attributes field in SentrySpanSamplingContextV2

Added documentation for the attributes field.

* refactor: simplify span creation in telemetry tests

- Replaced specific span creation methods with a unified `createSpan` method in telemetry tests, enhancing code clarity and reducing redundancy.
- Updated the `Fixture` class to support optional `dscCreator` and `samplingDecision` parameters, streamlining span initialization.

* fix: improve error handling in SentrySamplingContext

- Replaced StateError throws with internalLogger error calls in the transactionContext and spanContext getters to enhance error reporting and maintain backwards compatibility.
- This change provides clearer logging for developers when accessing context in incorrect modes.

* refactor: update SentryTraceContextHeader to accept options and replayId

- Modified the `fromRecordingSpan` factory method in `SentryTraceContextHeader` to accept `SentryOptions` and `replayId` as parameters instead of `Hub`.
- Updated the `dscCreator` in the `Hub` class to reflect these changes, ensuring proper context propagation.
- Adjusted related tests to use the new method signature, enhancing clarity and consistency in span creation.

* refactor: remove redundant StateError tests in SentrySamplingContext

- Eliminated tests that checked for StateError throws when accessing transactionContext and spanContext, as these checks are no longer necessary following recent error handling improvements.
- This cleanup enhances the clarity of the test suite by focusing on relevant functionality and expected behaviors.

* Formaatting

* feat(span-first): Replace `LogBatcher` usage with `TelemetryProcessor` and add `traceLifecycle` guards to start APIs (#3435)

* feat(span): Enhance span sampling and telemetry context handling

- Introduced sampling decision logic in the Hub class to determine whether spans should be recorded based on a random sampling rate.
- Updated the captureSpan method to return a Future, allowing for asynchronous handling of span captures.
- Enhanced SentryTraceContextHeader to create headers from RecordingSentrySpanV2, improving telemetry context management.
- Added a factory method for creating SentryTraceContextHeader from spans, facilitating better integration with the telemetry system.
- Updated tests to reflect changes in span handling and sampling logic, ensuring robust coverage for new implementations.

* refactor: rename dscFactory to dscCreator and update related implementations

- Renamed the `dscFactory` parameter to `dscCreator` in the Hub and RecordingSentrySpanV2 classes for clarity.
- Updated all references and implementations across the codebase to reflect this change.
- Added a new `captureSpan` method in NoOpSentryClient to support the updated span handling.
- Adjusted tests to accommodate the new parameter name.

* feat: introduce span sampling context and lifecycle management

- Added `SentryTraceLifecycle` enum to control trace data collection methods (streaming vs static).
- Enhanced `SentrySamplingContext` to include span sampling context and lifecycle options.
- Updated `RecordingSentrySpanV2` to support sampling decisions for root and child spans.
- Modified `Hub` class to evaluate sampling decisions at the root span level, ensuring child spans inherit the sampling decision.
- Added tests to verify sampling inheritance and behavior across nested spans.
- Updated example application to utilize the new streaming trace lifecycle option.

* refactor: update span handling and sampling context management

- Refactored `captureSpan` method in `Hub`, `NoOpSentryClient`, and `SentryClient` to return void instead of FutureOr<void> for consistency.
- Enhanced `SentrySamplingContext` with new constructors for transaction and span contexts, improving clarity in sampling decision evaluations.
- Updated `SentryTracesSampler` to utilize the new sampling context structure, ensuring proper handling of static and streaming trace lifecycles.
- Added comments to clarify the limitations of distributed trace support in the current implementation.
- Adjusted tests to validate the new span handling and sampling context behavior, ensuring robust coverage for the updated functionality.

* refactor: enhance SentrySamplingContext with dual-mode support

- Updated `SentrySamplingContext` to clarify its dual-mode functionality for transaction and span contexts, ensuring backwards compatibility.
- Added runtime checks and comments to guide usage in static and streaming modes.
- Included TODOs for future simplification once the legacy transaction API is removed.

* fix: update error types in SentrySamplingContext tests

- Changed expected error types in `SentrySamplingContext` tests from `AssertionError` to `StateError` for accessing `transactionContext` and `spanContext`.
- Improved formatting in test cases for better readability.
- Removed unnecessary blank lines in mock telemetry processor.

* fix: correct sampling decision references in SentryTraceContextHeader

- Updated the `SentryTraceContextHeader` class to use the correct sampling decision properties from the `span` object instead of the `hub.scope.propagationContext`.
- Ensured that `sampleRand` and `sampled` are now accurately derived from the `span.samplingDecision`, improving the integrity of trace context handling.

* fix: update return statements in captureSpan method for consistency

- Modified the `captureSpan` method in the `Hub` class to return void instead of null for better clarity and consistency in handling no-op scenarios.
- Ensured that the return type aligns with the recent refactor of span handling, improving overall code readability.

* fix: update captureSpan method to return void for consistency

- Changed the return type of the `captureSpan` method in `MockSentryClient` from `FutureOr<void>` to `void` to align with recent refactoring efforts.
- This update enhances clarity and consistency in the method's behavior, following similar changes made in the `Hub` class.

* fix: update sampling decision reference in trace context tests

- Modified the test for `SentryTraceContextHeader` to use the sampling decision from the span instead of the propagation context.
- Updated the test case to reflect the new sampling decision structure, ensuring accurate testing of trace context handling.

* refactor: clean up unused imports and methods in trace context and telemetry processor

- Removed unnecessary imports from `SentryTraceContextHeader` to streamline the codebase.
- Eliminated the unused `close` method in `MockTelemetryProcessor`, enhancing code clarity and maintainability.

* refactor: replace log batcher with telemetry processor and update related tests and imports

* add trace lifecycle guards and tests for static and streaming modes

* Rename DscCreator to DscCreatorCallback

* Document attributes field in SentrySpanSamplingContextV2

Added documentation for the attributes field.

* refactor: simplify span creation in telemetry tests

- Replaced specific span creation methods with a unified `createSpan` method in telemetry tests, enhancing code clarity and reducing redundancy.
- Updated the `Fixture` class to support optional `dscCreator` and `samplingDecision` parameters, streamlining span initialization.

* fix: improve error handling in SentrySamplingContext

- Replaced StateError throws with internalLogger error calls in the transactionContext and spanContext getters to enhance error reporting and maintain backwards compatibility.
- This change provides clearer logging for developers when accessing context in incorrect modes.

* refactor: update SentryTraceContextHeader to accept options and replayId

- Modified the `fromRecordingSpan` factory method in `SentryTraceContextHeader` to accept `SentryOptions` and `replayId` as parameters instead of `Hub`.
- Updated the `dscCreator` in the `Hub` class to reflect these changes, ensuring proper context propagation.
- Adjusted related tests to use the new method signature, enhancing clarity and consistency in span creation.

* refactor: remove redundant StateError tests in SentrySamplingContext

- Eliminated tests that checked for StateError throws when accessing transactionContext and spanContext, as these checks are no longer necessary following recent error handling improvements.
- This cleanup enhances the clarity of the test suite by focusing on relevant functionality and expected behaviors.

* Formaatting

* add mock telemetry processor implementation for testing telemetry integration

* Formaatting

* Formatting

* fix: update span lifecycle tests to remove warning logs in streaming mode

* fix: update trace lifecycle warnings and start span handling for static mode

* feature: wire up dsc for spans in telemetry processor; part of ([#3429]https://github.com/getsentry/sentry-dart/pull/3429)

* fix: correct indentation in buffer_test.dart to ensure accurate test expectations

* Fix missing processor integration

* feat(span-first): telemetry enrichment (#3457)

* feat: introduce span capture pipeline and semantic attributes for telemetry

- Added `SpanCapturePipeline` to manage span capturing and attribute enrichment.
- Introduced `SemanticAttributesConstants` for standardized telemetry attributes.
- Updated `SentryClient` to utilize the new span capture pipeline.
- Enhanced lifecycle hooks to support processing spans with additional attributes.
- Added utility extensions for managing span attributes and default attributes.
- Implemented tests for the new span capture functionality and attribute handling.

* refactor: remove unused SpanAttributeUtils extension

- Deleted the SpanAttributeUtils extension as it is no longer needed following recent changes to the span capture pipeline and attribute management.

* feat: add SpanAttributeUtils extension for SentrySpanV2

- Introduced a new extension `SpanAttributeUtils` to enhance `SentrySpanV2` by adding a method to conditionally add attributes if they are absent.
- Removed the unused import of `span_attribute_utils.dart` from `span_capture_pipeline.dart`.
- Created a new mock class `FakeSpanCapturePipeline` for testing purposes, which captures spans and scopes during tests.

* feat: enhance load contexts integration tests with trace lifecycle scenarios

- Added tests to verify the addition of native attributes to spans when using the streaming trace lifecycle.
- Implemented a test to ensure no callbacks are registered with the static trace lifecycle.
- Updated the device context in the test fixture to include brand, model, and family attributes, along with OS version.

* Fix tests

* Fix tests

* Fix tests

* Refine captureSpan warning and update TODO comments

Updated warning message for static trace lifecycle and removed ignored span from TODO.

* Review

* Fix nullable

* Fix compilation

* Fix compilation

* Fix compilation

* Add span streaming example to demo

* refactor: update span end callback to be async and adjust span ending logic for better concurrency handling

* Fix compilation errors

* Fix compilation errors

* refactor: remove unused imports of sentry_span_v2.dart across multiple files

This commit cleans up the codebase by removing unnecessary imports of the `sentry_span_v2.dart` file from various Dart files, enhancing maintainability and reducing clutter.

* feat(span-first): Add streaming instrumentation span implementation and tests (#3496)

* feat(tracing): Add streaming instrumentation span implementation with SpanV2 integration tests

Implement streaming span infrastructure to support SpanV2 telemetry:

- Create _sentry_testing package with FakeTelemetryProcessor for test assertions
- Add InstrumentationSpanFactorySetupIntegration to configure span factory based on traceLifecycle
- Implement StreamingInstrumentationSpan and StreamingInstrumentationSpanFactory for SpanV2 compatibility
- Add semantic attribute constants for HTTP, database, and span operations
- Create SpanV2 integration tests for dio, drift, file, hive, isar, sqflite, and supabase packages
- Update Flutter example app to test dual span mode support

The streaming implementation enables packages to emit SpanV2 telemetry
while maintaining backward compatibility with legacy transaction-based tracing.

Co-Authored-By: Claude <[email protected]>

* feat(link): Add SpanV2 integration test for GraphQL tracing

Add comprehensive SpanV2 integration test for the sentry_link package to verify GraphQL operation tracing works correctly with streaming spans:

- Add spanv2_integration_test.dart with tests for query, mutation, and error scenarios
- Add SentryTraceOrigins.autoGraphQlSentryLink constant for origin tracking
- Update SentryTracingLink to set origin on created spans

The test validates that GraphQL operations create properly structured SpanV2 instances with correct attributes, parent-child relationships, and error handling.

Co-Authored-By: Claude <[email protected]>

* ref(link): Support streaming spans in shouldStartTransaction mode

Update SentryTracingLink to properly handle shouldStartTransaction=true
in streaming mode by creating root SpanV2 instances instead of falling
back to legacy transaction API:

- When shouldStartTransaction=true and no active span exists, create
  a root span using Hub.startSpan() in streaming mode
- Set sentry.op attribute on root spans created in streaming mode
- Add test case for shouldStartTransaction root span creation
- Maintain backward compatibility with legacy mode

This ensures GraphQL tracing works correctly with SpanV2 architecture
when apps don't have an active span but want tracing enabled.

Co-Authored-By: Claude <[email protected]>

* Clean up and tests

* Fix analyze

* Fix analyze

* Update comment

* Fix analyze

* Fix analyze

* Fix analyze

* Update README

* Update

* Simplify

* Deslop

* Remove startTimestamp

* Restore main.dart replay settings

* Update

* Set logging to info

* Return on noop

* Update test name

* Update test names

* Revert removing spanv2 demo function with nested spans and attribute setting

* make parentSpan non-null

* Use constants

* Update

* Update

---------

Co-authored-by: Claude <[email protected]>

* feat(span): add beforeSendSpan callback for span data scrubbing (#3483)

* feat(span): add beforeSendSpan callback for span data scrubbing

Add beforeSendSpan callback to SentryOptions that allows users to modify
span data before it's sent. Unlike other beforeSend callbacks, this cannot
drop spans - it's intended for scrubbing sensitive data or PII from span
attributes and names.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* feat(span): Add IgnoreSpanFilter for span filtering in pipeline

Add IgnoreSpanFilter that drops spans based on configurable criteria:
- Filter by span name patterns (exact, prefix, suffix, contains, regex)
- Filter by attribute key-value patterns
- Apply match-all or match-any logic

Also fix beforeSendSpan example to avoid concurrent modification
when removing attributes during iteration.

Co-Authored-By: Claude <[email protected]>

* ref(span): Remove IgnoreSpanFilter

Remove IgnoreSpanFilter and associated tests.

Co-Authored-By: Claude <[email protected]>

* Update impl

* Update impl

* Update impl

* Update impl

* Review

* Update

* Update

* Update

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

* feat(span-first): add span v2 support for frames tracking (#3447)

* Add support

* Add test

* Update test

* Update doc

* Update to OnProcessSpan

* Update

* Update

* Set noop datetime to 0

* Use switch for traceLifecycle

* Deprecate collectors

* Review

* Review

* Review

* Review

* Review

* Review

* Review

* Analyze

* Update to unified collector

* Analyze

* Update

* Update

* Update

* Fix frames tracking

* Update finished bool

* Update

* Update

* Fix race condition for finish

* Update

* Update finish condition

* Fix analyze

* Update

* Review

* Fix tracer bug

* Review

* Simplify

* Fix test

* feat(span-first): `startSpan` callback api (#3505)

* feat(span-first): Add startSpan callback API with zone-based scope forking

Introduce `startSpan` as a callback-based API that automatically manages
span lifecycle (end on completion) and forks scope via Dart zones for
proper parent-child resolution. Rename the previous `startSpan` to
`startSpanManual` for explicit lifecycle control.

Update all integration tests and example app to use the new APIs.

Co-Authored-By: Claude <[email protected]>

* Update span api

* Enhance span API documentation and streamline span creation

- Added detailed documentation for the `startSpan` method in the Sentry class, explaining its usage and error handling.
- Simplified the span creation method in the Hub class for better readability.
- Removed redundant span initialization code from the SentryNavigatorObserver class to clean up the implementation.

* remove .worktrees/ from gitignore

* remove obsolete documentation plan files for span v2 and instrumentation

* Revert replay settings in example

* Fix tests

* Fix isar tests

* Updated

* Fix analyze

* Fix sentry_options docs

* Fix analyze

* Update

* Update

* Add clarifying active span comment

* Fix log messages

* Review

---------

Co-authored-by: Claude <[email protected]>

* feat(span-first): Add idle span support and support user interaction tracing (#3521)

* Convert user interaction

* Add

* Update

* Update

* Update

* Update

* Update

* Update idle span getter

* Update

* Update

* Update nav

* Update

* Remove childSpanTimeout for now

* Update

* Fix analyze

* Update status conversion

* End idle span on close

* Fix status json conversion

* Review

* Review

* Dont drop empty idle spans

* Update

* Update sampleRootSpan function

* Formatting

* feat(span-first): `ignoreSpans` (#3517)

* Add ignoreSpan rule

* Fix tests

* Fix formatting:

* Add ignoreSpan example

* Reparent ignored spans

* Update comments

* Update name

* Update test

* Remove unused NoOpSentrySpanV2.ignored factory

Co-Authored-By: Claude Opus 4.6 <[email protected]>

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

* feat(span-first): Add TTID/TTFD instrumentation (#3532)

* feat(flutter): Add TimeToDisplayTrackerV2 for streaming TTID/TTFD

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* refactor(flutter): Wire TimeToDisplayTrackerV2 through the system

Replace inline TTID/TTFD streaming code in SentryNavigatorObserver
with TimeToDisplayTrackerV2.trackRoute(). Remove static ttfdSpan field
and route SentryDisplay/SentryFlutter.currentDisplay() through the
tracker on SentryFlutterOptions.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* refactor(flutter): Improve TimeToDisplayTrackerV2 wiring and add streaming integration tests

Make timeToDisplayTrackerV2 a non-nullable late field on SentryFlutterOptions
instead of being created and set by SentryNavigatorObserver. Add didPop
handling for streaming mode and integration tests covering the full span v2
TTID/TTFD lifecycle through the navigator observer.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* Update logger and example

* Review

* Review

* Review

* Fix test

* Review

* Update

* Update

* review

* review

* Update

* test(tracing): Add TTFD conditional tests and refactor observer streaming tests

Guard TTFD span creation behind enableTimeToFullDisplayTracing option.
Refactor observer streaming tests to use a fake tracker, verifying
method calls instead of re-testing tracker internals.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* refactor(tracing): Use Dart 3 object pattern for TTFD option check

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* feat(tracing): Add debug logging for TTFD option check

Implement a debug log to indicate when Time To Full Display (TTFD) tracing is disabled, returning null for currentDisplay accordingly. This enhances traceability and debugging for TTFD-related functionality.

* fix(test): Enable enableTimeToFullDisplayTracing in SentryDisplayWidget test

currentDisplay() now guards on this option, so the test fixture
needs it set to true for reportFullyDisplayed to be called.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* Analyze

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>

* Update CHANGELOG

* feat(span-first): Port native app start integration to V2 span API (#3534)

* feat(flutter): Add TimeToDisplayTrackerV2 for streaming TTID/TTFD

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* refactor(flutter): Wire TimeToDisplayTrackerV2 through the system

Replace inline TTID/TTFD streaming code in SentryNavigatorObserver
with TimeToDisplayTrackerV2.trackRoute(). Remove static ttfdSpan field
and route SentryDisplay/SentryFlutter.currentDisplay() through the
tracker on SentryFlutterOptions.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* refactor(flutter): Improve TimeToDisplayTrackerV2 wiring and add streaming integration tests

Make timeToDisplayTrackerV2 a non-nullable late field on SentryFlutterOptions
instead of being created and set by SentryNavigatorObserver. Add didPop
handling for streaming mode and integration tests covering the full span v2
TTID/TTFD lifecycle through the navigator observer.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* Update logger and example

* Review

* Review

* Review

* Fix test

* Review

* Update

* Update

* review

* review

* feat(tracing): Port native app start integration to V2 span API

Add V2 streaming span support to the native and generic app start
integrations, gated by SentryTraceLifecycle.streaming.

Key changes:
- Add startTimestamp param to V2 span creation chain (Hub, Recording/
  IdleRecordingSentrySpanV2) for backdated app start spans
- Extract shared AppStartInfo/TimeSpan/parseNativeAppStart into
  native_app_start_data.dart for reuse across V1 and V2 handlers
- Extend TimeToDisplayTrackerV2.trackRoute() to return SentrySpanV2
  and accept optional startTimestamp/ttidEndTimestamp params
- Create NativeAppStartHandlerV2 that uses trackRoute() with backdated
  timestamps and creates app start + phase + native child spans
- Branch NativeAppStartIntegration and GenericAppStartIntegration on
  traceLifecycle to delegate to V1 or V2 handlers

Co-Authored-By: Claude <[email protected]>

* Update

* feat(tracing): Early idle span creation for native app start parenting

Create root idle span synchronously during integration init via
prepareRouteSpan() so user spans in initState can parent to it.
When native app start data arrives, trackRoute() reuses the prepared
span and backdates timestamps instead of creating a new one.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* Update

* test(flutter): Update TimeToDisplayTrackerV2 tests for new API

Replace outdated `trackRoute()` calls with the current API methods:
`trackRootNavigation`, `trackNonRootNavigation`, and
`prepareRootNavigation`. Add new test groups for `prepareRootNavigation`
and the prepare-then-track interaction flow.

Co-Authored-By: Claude <[email protected]>

* Update

* feat(flutter): Refine native app start integration and clean up tests

Remove debug print statement from NativeAppStartIntegration, delete
obsolete FakeTimeToDisplayTrackerV2, update example app to use
structured app start spans, and apply formatting fixes.

Co-Authored-By: Claude <[email protected]>

* Update

* ref(flutter): Clean up NativeAppStartHandlerV2

Remove outdated doc comments and step comments, switch error logging
to use internalLogger, and update TODO for next PR.

Co-Authored-By: Claude <[email protected]>

* test(flutter): Remove redundant TimeToDisplayTrackerV2 tests

Remove 3 tests that duplicated assertions already covered elsewhere:
- 'stores TTFD span id' (covered by 'creates TTFD span when enabled')
- 'creates idle span named root /' (merged into 'returns idle span')
- 'ends TTID on frame callback' in root group (covered by non-root)

Co-Authored-By: Claude <[email protected]>

* ref(flutter): Use fake tracker in navigator observer streaming tests

Replace integration-style tests with delegation tests that verify the
observer calls the correct tracker methods. Tracker behavior is already
covered by TimeToDisplayTrackerV2 unit tests.

Co-Authored-By: Claude <[email protected]>

* Update

* ref(flutter): Enhance error logging in native app start data and refine pattern matching

Updated error handling in `parseNativeAppStart` to utilize `internalLogger` for logging warnings. Improved pattern matching syntax in `TimeToDisplayTrackerV2` for better clarity and consistency.

* Formatting

* fix: Address review feedback for native app start v2

- Remove unused `options` parameter from `parseNativeAppStart`
- Fix index mismatch bug in native span ending by ending spans inline
- Update test name and comment to reference `trackRootNavigation`

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: Apply dart format to handler files

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: Cancel prepared root navigation on early return and use exhaustive switch

- Cancel orphaned idle span when handler returns early (null native start or >60s)
- Use switch on SentryTraceLifecycle for exhaustive matching instead of if/else

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix: Normalize startTimestamp to UTC in span constructor

Aligns constructor behavior with the setter which already calls .toUtc().

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* test(dart): assert UTC-normalized start timestamps

Update hub span timestamp assertions to expect UTC normalization for explicit startTimestamp values on inactive and idle spans.

Co-authored-by: Cursor <[email protected]>

* Test

* chore: Remove unused devtools_options.yaml files from drift and link packages

* test(flutter): expect UTC-normalized app start span timestamps

Align native app start V2 test assertions with UTC normalization so span start times are compared consistently across environments.

Co-authored-by: Cursor <[email protected]>

* test(flutter): clean up comments in integration tests

Removed outdated comments regarding V1 and V2 behavior in the generic app start integration test and the native app start handler V2 test for clarity and to reflect current implementation.

* refactor(flutter): consolidate attributes for span tracking in NativeAppStartHandlerV2

Streamlined the attribute assignment for span tracking by creating a single attributes map, reducing redundancy in the code. This change enhances maintainability and clarity in the NativeAppStartHandlerV2 implementation.

* fix(flutter): handle null context in native app start integration

Added a check for null context in the NativeAppStartIntegration class to prevent potential errors. If the context is null, a warning is logged, and the integration process is skipped, enhancing robustness.

* Cleanup tracker in handler

* refactor(flutter): rename tracking methods for clarity and consistency

Updated method names in the time-to-display tracking system to improve clarity. Changed `trackRootNavigation` to `trackAppStart` and `trackNonRootNavigation` to `trackRoute`, aligning with their functionality. Adjusted related comments and test cases to reflect these changes, enhancing code readability and maintainability.

---------

Co-authored-by: Claude Opus 4.6 <[email protected]>
Co-authored-by: Cursor <[email protected]>

* feat(span): Make `startInactiveSpan` public API (#3568)

* feat(span): Add public startInactiveSpan API to Sentry

Expose startInactiveSpan on the Sentry class as a public static method,
mirroring the existing startSpan API. Unlike startSpan, this creates a
span that is not set as the active span and must be ended manually,
useful for spans that survive across execution boundaries like widget
lifecycles or stream subscriptions.

Remove @internal annotation from Hub.startInactiveSpan.

Co-Authored-By: Claude <[email protected]>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

* refactor(span): Standardize parentSpan parameter placement in startInactiveSpan methods

Updated the startInactiveSpan method across Hub, NoOpHub, and Sentry classes to ensure the parentSpan parameter is consistently placed at the end of the parameter list. This change improves code readability and maintains uniformity in method signatures.

---------

Co-authored-by: Claude <[email protected]>
Co-authored-by: Copilot Autofix powered by AI <[email protected]>

* feat(span-first): Add `startSpan` and `startSpanSync` (#3574)

* refactor(span): Update startSpan method signatures to return type T and include startTimestamp parameter

Modified the startSpan method across Hub, NoOpHub, and Sentry classes to return type T instead of FutureOr<T>, enhancing type safety. Added an optional startTimestamp parameter to support backdated spans. Updated example usage in the Flutter demo to demonstrate synchronous span creation.

* feat(span): Introduce startSpanSync method for synchronous span creation

Added a new startSpanSync method to the Hub, NoOpHub, and Sentry classes, allowing for synchronous span creation with a callback. Updated the startSpan method to return Future<T> for asynchronous operations. Enhanced documentation to clarify usage and added tests to ensure correct behavior of the new synchronous method.

* test(span): Add missing critical tests for startSpan and startSpanSync

Add tests covering the NoOpSentrySpanV2 code path in both startSpan
and startSpanSync for two scenarios: hub is closed and traceLifecycle
is static. These paths skip zone forking and call the callback directly,
which was previously untested.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* build(flutter): Regenerate mocks for updated startSpan signature

The Hub.startSpan return type changed from FutureOr<T> to Future<T>,
causing MockHub.startSpan to be out of sync.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

* fix(span): Update spanV2Demo to use startSpanSync for synchronous span creation

Replaced the call to Sentry.startSpan with Sentry.startSpanSync in the Flutter example to demonstrate the synchronous span creation functionality. This aligns with recent changes to the span API and enhances the example's clarity.

* fix analyze error

* refactor(span): Simplify span error handling in Hub class

Removed the _endActiveSpan method and integrated its functionality directly into the error handling of startSpan. Now, spans are ended and their status is set to error in the catch block, improving code clarity and reducing redundancy.

* refactor(span): Streamline runZoned usage in Hub class

Removed unnecessary variable assignments in the runZoned calls within the Hub class, enhancing code readability and reducing redundancy. The changes simplify the asynchronous handling of spans while maintaining functionality.

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <[email protected]>

* update

* Refactor getActiveSpan documentation comments

Removed outdated comments regarding active spans in zone-forked scopes.

* docs(hub): Enhance documentation for scope and active span retrieval

Updated comments in the Hub class to clarify the behavior of the _zoneScope and getActiveSpan methods. The changes improve the understanding of how zone-forked scopes and…