[EXAMPLE] Add async example

[jgomezselles]

Fixes #1464

Changes

This PR adds an example that demonstrates tracing async requests between generic clients and servers. It simulates context injections and extractions and shows how to explicitly set parent span_id's in different situations, when the scope is not available, or different threads are run in parallel.

The proposed pattern may be used for any kind of asynchronous client/server communication.

It defines auxiliary functions that can be easily adapted to other code bases together with a README documenting the flow and expected outcome.

Apart from markdown lining and clang formatting, BUILD and relevant CMakeLists have been adapted.

For significant contributions please make sure you have completed the following items:

• CHANGELOG.md updated for non-trivial changes
• Unit tests have been added
• Changes in public API reviewed

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: jgomezselles / name: Jose Gómez-Sellés (f1062e2)

[jgomezselles]

Hi!

First I wanted to say that I'm a big fan of this project. I've been involved with OpenTelemetry and C++ in different ways in the past,
(i.e. Product Manager of OpenTelemetry at Red Hat a couple of years ago or giving some talks about how to instrument C++ code, for example at FOSDEM last year).

When I started trying to include this lib some years ago, I have to confess struggled a bit. Since then, I really wanted to contribute with an example like this, so folks can just easily create spans in regular C++ code bases that deal with async calls. Finally I had some quality time.

Of course, I'm very open for feedback. I tried my best to clearly explain this with a simple example that doesn't need to rely on other libs or clients and servers. I hope this makes sense.

For context: I'm using this kind of implementation in an async http2 client I created for load testing and demos (repo here ).

If this is eventually approved, I'd like to also contribute to the documentation.

Thanks again, and congrats on the great work maintaining this library!

[lalitb]

Thanks for the PR.

Non-blocking: this example is correct, but it reads more like a carrier-based context propagation example than an async programming example. Since we already have an HTTP propagation example, this would be more distinctive if it either (a) were renamed/reframed around manual async context propagation, or (b) showed a more practical in-process async pattern such as passing SpanContext from the submitting thread to worker-thread child spans.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.13%. Comparing base (4307862) to head (f1062e2).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3935      +/-   ##
==========================================
+ Coverage   90.06%   90.13%   +0.07%     
==========================================
  Files         226      226              
  Lines        7227     7227              
==========================================
+ Hits         6508     6513       +5     
+ Misses        719      714       -5     

see 4 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jgomezselles]

Thanks for the feedback. I'll think about it and will come back with changes.