refactor readme.md

Author: Cirilla-zmh

messaging-wrappers/README.md

@@ -5,6 +5,23 @@ type of messaging system client. To further ease the burden of instrumentation,
 predefined implementations for certain messaging systems, helping you seamlessly address the issue
 of broken traces.
 
+<details>
+<summary>Table of Contents</summary>
+
+- [Overview](#overview)
+- [Predefined Implementations](#predefined-implementations)
+- [Quickstart For Given Implementations](#quickstart-for-given-implementations)
+  - [\[Given\] Step 1 Add dependencies](#given-step-1-add-dependencies)
+  - [\[Given\] Step 2 Initializing MessagingWrappers](#given-step-2-initializing-messagingwrappers)
+  - [\[Given\] Step 3 Wrapping the Process](#given-step-3-wrapping-the-process)
+- [Manual Implementation](#manual-implementation)
+  - [\[Manual\] Step 1 Add dependencies](#manual-step-1-add-dependencies)
+  - [\[Manual\] Step 2 Initializing MessagingWrappers](#manual-step-2-initializing-messagingwrappers)
+  - [\[Manual\] Step 3 Wrapping the Process](#manual-step-3-wrapping-the-process)
+- [Component Owners](#component-owners)
+
+</details>
+
 ## Overview
 
 The primary goal of this API is to simplify the process of adding instrumentation to your messaging
@@ -20,15 +37,96 @@ this tool aims to streamline the tracing and monitoring process.
 | kafka-clients     | `[0.11.0.0,)` | process      |
 | aliyun mns-client | `[1.3.0,)`    | process      |
 
-## Quickstart
+## Quickstart For Given Implementations
+
+This example will demonstrate how to add automatic instrumentation to your Kafka consumer with process wrapper. For
+detailed example, please check out [KafkaClientTest](./kafka-clients/src/test/java/io/opentelemetry/contrib/messaging/wrappers/kafka/KafkaClientTest.java).
 
-### Step 1 Add dependencies
+### [Given] Step 1 Add dependencies
 
 To use OpenTelemetry in your project, you need to add the necessary dependencies. Below are the configurations for both
 Gradle and Maven.
 
 #### Gradle
 
+```kotlin
+dependencies {
+    implementation("io.opentelemetry.contrib:opentelemetry-messaging-wrappers-kafka-clients:${latest_version}")
+}
+```
+
+#### Maven
+
+```xml
+<dependency>
+    <groupId>io.opentelemetry.contrib</groupId>
+    <artifactId>opentelemetry-messaging-wrappers-kafka-clients</artifactId>
+    <version>${latest_version}</version>
+</dependency>
+```
+
+### [Given] Step 2 Initializing MessagingWrappers
+
+For `kafka-clients`, we provide pre-implemented wrappers that allow for out-of-the-box integration. We provide
+an implementation based on the OpenTelemetry semantic convention by default.
+
+```java
+public class KafkaDemo {
+ 
+  public static MessagingProcessWrapper<KafkaProcessRequest> createWrapper() {
+    return KafkaHelper.processWrapperBuilder().build();
+  }
+}
+```
+
+### [Given] Step 3 Wrapping the Process
+
+Once the MessagingWrapper are initialized, you can wrap your message processing logic to ensure that tracing spans are
+properly created and propagated.
+
+**P.S.** Some instrumentations may also [generate process spans](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md).
+If both are enabled, it might result in duplicate nested process spans. It is recommended to disable one of them.
+
+```java
+public class Demo {
+
+  private static final MessagingProcessWrapper<KafkaProcessRequest> WRAPPER = createWrapper();
+
+  // please initialize consumer
+  private Consumer<Integer, String> consumer;
+  
+  public String consume() {
+    ConsumerRecords<?, ?> records = consumer.poll(Duration.ofSeconds(5));
+    ConsumerRecord<?, ?> record = records.iterator().next();
+
+    return WRAPPER.doProcess(
+        KafkaProcessRequest.of(record, groupId, clientId), () -> {
+          // your processing logic
+          return "success";
+        });
+  }
+
+  public void consumeWithoutResult() {
+    ConsumerRecords<?, ?> records = consumer.poll(Duration.ofSeconds(5));
+    ConsumerRecord<?, ?> record = records.iterator().next();
+
+    WRAPPER.doProcess(
+        KafkaProcessRequest.of(record, groupId, clientId), () -> {
+          // your processing logic
+        });
+  }
+}
+```
+
+## Manual Implementation
+
+You can also build implementations based on the `messaging-wrappers-api` for any messaging system to accommodate your
+custom message protocol. For detailed example, please check out [UserDefinedMessageSystemTest](./api/src/test/java/io/opentelemetry/contrib/messaging/wrappers/UserDefinedMessageSystemTest.java).
+
+### [Manual] Step 1 Add dependencies
+
+#### Gradle
+
 ```kotlin
 dependencies {
     implementation("io.opentelemetry.contrib:opentelemetry-messaging-wrappers-api:${latest_version}")
@@ -45,7 +143,7 @@ dependencies {
 </dependency>
 ```
 
-### Step 2 Initializing MessagingWrappers
+### [Manual] Step 2 Initializing MessagingWrappers
 
 Below is an example of how to initialize a messaging wrapper.
 
@@ -75,21 +173,9 @@ public class MyTextMapGetter implements TextMapGetter<MyMessagingProcessRequest>
 ```
 
 For arbitrary messaging systems, you need to manually define `MessagingProcessRequest` and the corresponding `TextMapGetter`.
-You can also customize your messaging spans by adding an AttributesExtractor.
-
-For popular messaging systems, we provide pre-implemented wrappers that allow for out-of-the-box integration. We provide
-an implementation based on the OpenTelemetry semantic convention by default.
-
-```java
-public class KafkaDemo {
- 
-  public static MessagingProcessWrapper<KafkaProcessRequest> createWrapper() {
-    return KafkaHelper.processWrapperBuilder().build();
-  }
-}
-```
+You can also customize your messaging spans by adding an `AttributesExtractor`.
 
-### Step 3 Wrapping your process
+### [Manual] Step 3 Wrapping the Process
 
 Once the MessagingWrapper are initialized, you can wrap your message processing logic to ensure that tracing spans are
 properly created and propagated.
@@ -103,14 +189,21 @@ public class Demo {
   private static final MessagingProcessWrapper<MyMessagingProcessRequest> WRAPPER = createWrapper();
 
   public String consume(Message message) {
+    return WRAPPER.doProcess(new MyMessagingProcessRequest(message), () -> {
+      // your processing logic
+      return "success";
+    });
+  }
+
+  public void consumeWithoutReturn(Message message) {
     WRAPPER.doProcess(new MyMessagingProcessRequest(message), () -> {
       // your processing logic
     });
   }
 }
 ```
 
-## Component owners
+## Component Owners
 
 - [Minghui Zhang](https://github.com/Cirilla-zmh), Alibaba
 - [Steve Rao](https://github.com/steverao), Alibaba

messaging-wrappers/aliyun-mns-sdk/build.gradle.kts

@@ -12,10 +12,12 @@ dependencies {
 
   compileOnly("com.aliyun.mns:aliyun-sdk-mns:1.3.0")
 
+  testImplementation(project(":messaging-wrappers:testing"))
   testImplementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
   testImplementation("io.opentelemetry:opentelemetry-sdk-trace")
   testImplementation("io.opentelemetry:opentelemetry-sdk-testing")
-
   testImplementation("io.opentelemetry:opentelemetry-sdk-extension-incubator")
-  testImplementation("uk.org.webcompere:system-stubs-jupiter:2.0.3")
+
+  testImplementation("com.aliyun.mns:aliyun-sdk-mns:1.3.0")
+  testImplementation("org.springframework.boot:spring-boot-starter-web:3.0.0")
 }