[EXAMPLE] Rename async example to manual propagation

After the changes, the new reframing should be:

This PR adds an example that demonstrates how to manually propagate tracing
context across
asynchronous calls between generic clients and servers. It simulates context
injections and extractions showing how to **explicitly/manually** 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 helpful for use cases which involve asynchronous
operations.

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.

Author: jgomezselles

examples/CMakeLists.txt

@@ -28,7 +28,7 @@ add_subdirectory(metrics_simple)
 add_subdirectory(multithreaded)
 add_subdirectory(multi_processor)
 add_subdirectory(environment_carrier)
-add_subdirectory(async)
+add_subdirectory(manual_propagation)
 
 if(WITH_EXAMPLES_HTTP)
   add_subdirectory(http)

examples/async/CMakeLists.txt

@@ -4,7 +4,7 @@
 load("@rules_cc//cc:cc_binary.bzl", "cc_binary")
 
 cc_binary(
-    name = "example_async",
+    name = "example_manual_propagation",
     srcs = [
         "main.cc",
     ],

examples/async/BUILD examples/manual_propagation/BUILDexamples/async/BUILD renamed to examples/manual_propagation/BUILD

@@ -0,0 +1,11 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+add_executable(example_manual_propagation main.cc)
+target_link_libraries(
+  example_manual_propagation PRIVATE opentelemetry-cpp::trace
+                        opentelemetry-cpp::ostream_span_exporter)
+
+if(BUILD_TESTING)
+  add_test(NAME examples.manual_propagation COMMAND "$<TARGET_FILE:example_manual_propagation>")
+endif()

examples/manual_propagation/CMakeLists.txt

@@ -1,12 +1,13 @@
-# OpenTelemetry C++ ASYNC Example
+# OpenTelemetry C++ Manual Asynchronous Context Propagation Example
 
-This is a simple 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.
+This example demonstrates how to manually propagate tracing context across
+asynchronous calls between generic clients and servers. It simulates context
+injections and extractions showing how to **explicitly/manually** 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.
+The proposed pattern may be helpful for use cases which involve asynchronous
+operations.
 
 ## Running the example
 
@@ -19,15 +20,14 @@ requests have distributed tracing context `injected` into a map, simulating
 headers.
 
 * These requests then arrive to a server, which `extracts` the span information
-and creates child spans sharing the same trace id's with the client request,
-and marking it as parent. After that, other spans are `nested`, simulating
-server work.
+and creates child spans sharing the same trace id's with the client request.
+After that, other spans are `nested`, simulating server work.
 
-* Answers contain again the context `injected`, and the client extracts them
-without more context than the headers arriving from the
+* Answers contain again the context `injected`, and the client propagates it
+without more context than the headers arriving in the answer.
 
-* The Parent spans that originated the only 2 `trace-id`'s of this example are
-kept alive during the whole example, and ended at the end.
+* The parent spans that originated the only 2 `trace-id`'s simulated here are
+kept alive until the end of the example.
 
 ```text
 [Client]                    [Server]
@@ -45,7 +45,7 @@ process_answer
 ## Span Hierarchy
 
 Only 2 traces are generated in this example. Each one contains 4 spans in
-total, created across both a server and a client. The Span hierarchy is
+total, and are propagated across a server and a client. The Span hierarchy is
 shown below:
 
 ```text
@@ -67,7 +67,9 @@ create child spans from a previous one, independently on the active span.
 
 It's worth noting that `shared_ptr`'s are used because it helps for keeping
 spans alive and passing them across different lambda functions or execution
-scopes for more complex use cases. These functions are:
+scopes for more complex use cases.
+
+The auxiliary functions used in this example are explained below:
 
 ### Creating Child Spans
 

examples/async/README.md examples/manual_propagation/README.mdexamples/async/README.md renamed to examples/manual_propagation/README.md

@@ -42,7 +42,7 @@ void InitTracer()
   std::shared_ptr<opentelemetry::trace::TracerProvider> provider =
       trace_sdk::TracerProviderFactory::Create(std::move(processor),
                                                opentelemetry::sdk::resource::Resource::Create({}));
-  // Set the global trace provider
+  // Set the global tracer provider
   trace_sdk::Provider::SetTracerProvider(provider);
 
   ctx::propagation::GlobalTextMapPropagator::SetGlobalPropagator(