feat: Tracing API polishing + Distributed tracing Docs

[abelonogov-ld]

Summary

• Distributed tracing Docs
• Activity Microsoft API exposed
• Fix StartRootActivity to always restore Activity.Current after creating the root activity, preventing permanent loss of the ambient activity context.

Problem

StartRootActivity saves Activity.Current into previous and sets it to null to create a parentless activity. However, it only restored previous when StartActivity returned null. On success, Activity.Current was left pointing to the new root activity — and when that activity was later disposed, Activity.Current reverted to its parent (null), permanently losing the original ambient context.

This made StartRootActivity behave differently from StartRootSpan, which uses DeactivateNewSpan to leave Activity.Current untouched. The README documents these as "equivalent," but they had different side effects on ambient context.

Fix

Unconditionally restore Activity.Current = previous after creating the activity, matching the behavior of StartRootSpan.

Test plan

• Verify that Activity.Current is preserved after calling StartRootActivity
• Verify the returned root activity has no parent
• Verify StartRootActivity and StartRootSpan behave equivalently with respect to ambient context

---

Note

Medium Risk
Adds new public tracing surface area (Activity/ActivitySource and parent-context span overloads) and changes ambient Activity.Current handling in StartRootActivity, which could affect trace correlation if incorrect.

Overview
Tracing API polish + distributed tracing docs. LDObserve now supports starting spans with an explicit parent SpanContext (and optional SpanKind) to enable manual context propagation across threads, and it exposes a .NET-native Activity API (GetActivitySource, StartActivity, StartRootActivity).

StartRootActivity is fixed to always restore the previous Activity.Current after creating a root activity, avoiding accidental loss of ambient context. Documentation is expanded with a new docs/distributed-tracing.md cookbook and README updates (log/span context examples, span.AddEvent, root spans/activities), and the sample app adds a polling demo that creates child spans from captured context.

^{Reviewed by Cursor Bugbot for commit 7caf8e9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5f9a9ff. Configure here.}