feat: Make tracing object fluent

[stayallive]

This could make writing tracing code easier and more readable depending on your preference.

The upside is that this unlocks a fluent way of writing. I don't think there are any actual downsides (apart from BC).

I believe this is a backward incompatible change, especially Span is not a final class so I don't think we can make this change in 3.x but maybe this is a good start for 4.x and allows us to make the tracing code simpeler/shorter to use. Possibly we could already convert the final classes but not a 100% sure if that is also a BC.

If we think this is acceptable and a good change I would propose that going forward (possibly starting with 4.x) to make all future APIs fluent where it makes sense.

---

A small example partly taken from the laravel codebase:

Before:

$context = TransactionContext::fromHeaders($sentryTraceHeader, $baggageHeader);
$context->setOp('http.server');
$context->setData([
    'url' => '/' . ltrim($request->path(), '/'),
    'method' => strtoupper($request->method()),
]);
$context->setStartTimestamp($requestStartTime);

$bootstrapSpan = $this->addAppBootstrapSpan($request);

$appContextStart = new SpanContext();
$appContextStart->setOp('laravel.handle');
$appContextStart->setStartTimestamp($bootstrapSpan ? $bootstrapSpan->getEndTimestamp() : microtime(true));

$this->transaction->startChild($appContextStart);

After:

$context = TransactionContext::fromHeaders($sentryTraceHeader, $baggageHeader)
    ->setStartTimestamp($requestStartTime)
    ->setOp('http.server')
    ->setData([
        'url' => '/' . ltrim($request->path(), '/'),
        'method' => strtoupper($request->method()),
    ]);

$bootstrapSpan = $this->addAppBootstrapSpan($request);

$appContextStart = (new SpanContext)
    ->setStartTimestamp($bootstrapSpan ? $bootstrapSpan->getEndTimestamp() : microtime(true))
    ->setOp('laravel.handle');

[cleptric]

I really like how this would improve our API.

On the other hand, we will force people to update all their instrumentation code when they upgrade to 4.0.
And I have the feeling that this work is not really worth the gain for them 🙁

[stayallive]

Why would they? The old code still works with this change. In my description, both code blocks work perfectly fine after this change 😄

The only thing is that people extending our classes (read: Span) need to add return $this;. But I'm not sure why people would extend our Span class in the first place so unsure this is a real problem.

[cleptric]

Ok, then let's mark Span as final. No, we can't...

I would like to have a discussion about this in a different issue, where we could discuss annotating stuff as @internal vs making everything final and impossible for people to extend (there might be uses-cases for that).

[cleptric]

Closing for now but keeping the branch for later 🙂

[stayallive]

Closing this in favor of #1601.