Update SDK tracing docs for span-first (JS, Python, Flutter)

[inventarSarah]

SDK

Other

Description

Update the tracing documentation to introduce the new span-first tracing mode and help users (mainly users using manual instrumentation) opt in and update their code where needed. Ensure existing tracing docs and new span-first docs are consistent and work together.

Basis: #17621

Background and context

Sentry is moving from a transaction-based tracing model to a span-first model (aligning with how OTel handles it). In the new model, transactions are phased out and everything is a span.

There will be a new (opt-in) tracing mode, currently called "stream spans": spans get sent to Sentry in batches as they finish, rather than being held in memory until the transaction ends. This removes the 1,000-span limit and makes trace data visible sooner.

Impact by sdk:

• JS: already on the new Span API; stream spans is a new opt-in. One or more functions work differently for stream spans so users may need to update code when switching (even if they already use Span API)
• Python & Flutter: A new Span API is coming and stream spans will also be available as an opt-in.

The changes mainly affect users who do manual instrumentation and want to opt in to streaming mode, or those hitting the limitations of the current transaction model.

Definitions

Naming recommendations:

• New spans
  • Can describe how they differ from transactions. These are stream mode spans…
• Stream mode - the way spans are formatted:
  • is a tracing mode, where spans are sent to Sentry in batches as they finish, rather than being held in memory until the transaction ends. This removes the 1k-span limit, reduces memory usage, and makes trace data visible in Sentry sooner.
  • This allows for describing stream mode vs transaction mode
• Root span - the topmost span connected to a trace ID
• Child spans - any span nested under a parent, connected to the same trace ID
• Service span - a parent-level span at top of a service, nested under the same trace ID as the root span

What is a Service Span?

Developer Docs Span API

The topmost span within a service boundary is called the service span.

For example, a distributed trace from frontend to backend, would have a service span for the backend, and a service span for the frontend. The frontend service span is also the root span of the entire span tree.
Visualization:

Trace (trace_id)
│
└── Root span  [frontend]       ← also a service span
     ├── Child span
     │    └── Child span
     ├── Child span
     │    └── ...
     └── Service span  [backend]   ← remote parent in frontend
          ├── Child span
          └── Child span
               └── Child span

Hierarchy

Transaction-based:

Trace
 └── Root Span
	  └── Child span
      └── Transaction
           └── Child Span
                └── Child Span

Span-based:

Trace
 └── Root Span
      └── Child span
      └── Service Span
           └── Child Span
                └── Child Span

cc @sfanahata @cleptric

Suggested Solution

No response

[linear-code]

DOCS-2661