Document setting Scope.Span

[jamescrosswell]

Originally posted by @jamescrosswell in #4264 (comment)

The issue with not wanting the spans for outgoing HttpRequests to be mixed up with other spans (perhaps being performed in async Tasks) is a bit more nuanced.

Currently, the way the MessageHandler creates spans is this:

sentry-dotnet/src/Sentry/SentryHttpMessageHandler.cs

Lines 68 to 73 in dc3c0dd

	// Start a span that tracks this request
	// (may be null if transaction is not set on the scope)
	var span = _hub.GetSpan()?.StartChild(
	"http.client",
	$"{method} {url}" // e.g. "GET https://example.com"
	);

In the most common case then, if there's no Scope.Transaction then no span gets created. If there is a Scope.Transaction then a span gets created as a child of the transaction... and implicitly it becomes the "last active span" for the transaction.

The way Bruno managed to work around that in the symbol collector is by setting Scope.Span (not Scope.Transaction):
https://github.com/getsentry/symbol-collector/blob/8a0fdb2594c3028f63f180b9b56b1efea1cbce34/src/SymbolCollector.Core/Client.cs#L75

This appears to be completely undocumented.

1. We should add documentation for this... it's a useful API that allows SDK users to force spans that get automatically instrumented by our integrations to be created on specific transactions without having to set those transactions on the Scope.
2. It would be fantastic if we had a more intuitive solution to this. That would need some head scratching though (if it is even possible)