Library doc cleanup (#6948)

Related to #6947, but just cleans up the library module doc that already
existed (mostly for uniformity). Does not introduce any new doc.

docs/standalone-library-instrumentation.md

@@ -4,6 +4,7 @@ This repository also publishes standalone instrumentation for several libraries
 that can be used if you prefer that over using the Java agent:
 
 * [Apache Dubbo](../instrumentation/apache-dubbo-2.7/library-autoconfigure)
+* [Apache Kafka](../instrumentation/kafka/kafka-clients/kafka-clients-2.6/library)
 * [Armeria](../instrumentation/armeria-1.3/library)
 * [AWS Lambda](../instrumentation/aws-lambda/aws-lambda-core-1.0/library)
 * [AWS SDK 1.11](../instrumentation/aws-sdk/aws-sdk-1.11/library)

instrumentation/apache-dbcp-2.0/library/README.md

@@ -1,18 +1,17 @@
-# Manual Instrumentation for Apache DBCP
+# Library Instrumentation for Apache DBCP version 2.0 and higher
 
 Provides OpenTelemetry instrumentation for [Apache DBCP](https://commons.apache.org/proper/commons-dbcp/).
 
 ## Quickstart
 
 ### Add these dependencies to your project:
 
-Replace `OPENTELEMETRY_VERSION` with the latest stable
-[release](https://mvnrepository.com/artifact/io.opentelemetry). `Minimum version: 1.15.0`
+Replace `OPENTELEMETRY_VERSION` with the [latest
+release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-apache-dbcp-2.0).
 
 For Maven, add to your `pom.xml` dependencies:
 
 ```xml
-
 <dependencies>
   <dependency>
     <groupId>io.opentelemetry.instrumentation</groupId>

instrumentation/aws-lambda/aws-lambda-core-1.0/library/README.md

@@ -48,13 +48,15 @@ link to tracing information provided by Lambda itself. To do so, add a dependenc
 you use.
 
 Gradle:
+
 ```kotlin
 dependencies {
   implementation("io.opentelemetry:opentelemetry-extension-trace-propagators:0.8.0")
 }
 ```
 
 Maven:
+
 ```xml
 <dependencies>
   <dependency>

instrumentation/aws-lambda/aws-lambda-events-2.2/library/README.md

@@ -58,6 +58,7 @@ dependencies {
 ```
 
 Maven:
+
 ```xml
 <dependencies>
   <dependency>

instrumentation/c3p0-0.9/library/README.md

@@ -1,18 +1,17 @@
-# Manual Instrumentation for C3P0
+# Library Instrumentation for C3P0 version 0.9 and higher
 
 Provides OpenTelemetry instrumentation for [C3P0](https://www.mchange.com/projects/c3p0/).
 
 ## Quickstart
 
 ### Add these dependencies to your project:
 
-Replace `OPENTELEMETRY_VERSION` with the latest stable
-[release](https://mvnrepository.com/artifact/io.opentelemetry). `Minimum version: 1.15.0`
+Replace `OPENTELEMETRY_VERSION` with the [latest
+release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-c3p0-0.9).
 
 For Maven, add to your `pom.xml` dependencies:
 
 ```xml
-
 <dependencies>
   <dependency>
     <groupId>io.opentelemetry.instrumentation</groupId>

instrumentation/graphql-java-12.0/library/README.md

@@ -1,18 +1,17 @@
-# Manual Instrumentation for GraphQL Java
+# Library Instrumentation for GraphQL Java version 12.0 and higher
 
 Provides OpenTelemetry instrumentation for [GraphQL Java](https://www.graphql-java.com/).
 
 ## Quickstart
 
 ### Add these dependencies to your project:
 
-Replace `OPENTELEMETRY_VERSION` with the latest stable
-[release](https://mvnrepository.com/artifact/io.opentelemetry). `Minimum version: 1.13.0`
+Replace `OPENTELEMETRY_VERSION` with the [latest
+release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-graphql-java-12.0).
 
 For Maven, add to your `pom.xml` dependencies:
 
 ```xml
-
 <dependencies>
   <dependency>
     <groupId>io.opentelemetry.instrumentation</groupId>

instrumentation/hikaricp-3.0/library/README.md

@@ -1,18 +1,17 @@
-# Manual Instrumentation for HikariCP
+# Library Instrumentation for HikariCP version 3.0 and higher
 
 Provides OpenTelemetry instrumentation for [HikariCP](https://github.com/brettwooldridge/HikariCP).
 
 ## Quickstart
 
 ### Add these dependencies to your project:
 
-Replace `OPENTELEMETRY_VERSION` with the latest stable
-[release](https://mvnrepository.com/artifact/io.opentelemetry). `Minimum version: 1.14.0`
+Replace `OPENTELEMETRY_VERSION` with the [latest
+release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-hikaricp-3.0).
 
 For Maven, add to your `pom.xml` dependencies:
 
 ```xml
-
 <dependencies>
   <dependency>
     <groupId>io.opentelemetry.instrumentation</groupId>

instrumentation/jdbc/library/README.md

@@ -1,16 +1,16 @@
-# Manual Instrumentation for JDBC
+# Library Instrumentation for JDBC
 
 Provides OpenTelemetry instrumentation for
 [Java JDBC API](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/).
 
 ## Quickstart
 
-### Add these dependencies to your project.
+### Add these dependencies to your project:
 
-Replace `OPENTELEMETRY_VERSION` with the latest stable
-[release](https://mvnrepository.com/artifact/io.opentelemetry). `Minimum version: 1.4.0`
+Replace `OPENTELEMETRY_VERSION` with the [latest
+release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-jdbc).
 
-For Maven add to your `pom.xml`:
+For Maven, add to your `pom.xml` dependencies:
 
 ```xml
 <dependencies>
@@ -22,19 +22,19 @@ For Maven add to your `pom.xml`:
 </dependencies>
 ```
 
-For Gradle add to your dependencies:
+For Gradle, add to your dependencies:
 
 ```groovy
 implementation("io.opentelemetry.instrumentation:opentelemetry-jdbc:OPENTELEMETRY_VERSION")
 ```
 
-##### Usage
+### Usage
 
-There are three possible ways to activate the OpenTelemetry JDBC instrumentation. The first way is more preferable for
+There are two possible ways to activate the OpenTelemetry JDBC instrumentation. The first way is more preferable for
 DI frameworks which uses connection pools, as it wraps a `DataSource` with a special OpenTelemetry wrapper. The second
 one requires to change the connection URL and switch to use a special OpenTelemetry driver.
 
-### Datasource way
+#### Datasource way
 
 If your application uses a DataSource, simply wrap your current DataSource object with `OpenTelemetryDataSource`.
 `OpenTelemetryDataSource` has a constructor method that accepts the `DataSource` to wrap. This is by far the simplest
@@ -63,7 +63,7 @@ public class DataSourceConfig {
 }
 ```
 
-### Driver way
+#### Driver way
 
 1. Activate tracing for JDBC connections by setting `jdbc:otel:` prefix to the JDBC URL:
 

instrumentation/kafka/kafka-clients/kafka-clients-2.6/library/README.md

@@ -1,4 +1,75 @@
-# Kafka Metrics
+# Library instrumentation for Kafka Clients version 2.6 and higher
+
+## Quickstart
+
+### Add these dependencies to your project:
+
+Replace `OPENTELEMETRY_VERSION` with the [latest
+release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-kafka-clients-2.6).
+
+For Maven, add to your `pom.xml` dependencies:
+
+```xml
+<dependencies>
+  <dependency>
+    <groupId>io.opentelemetry.instrumentation</groupId>
+    <artifactId>opentelemetry-kafka-clients-2.6</artifactId>
+    <version>OPENTELEMETRY_VERSION</version>
+  </dependency>
+</dependencies>
+```
+
+For Gradle, add to your dependencies:
+
+```groovy
+implementation("io.opentelemetry.instrumentation:opentelemetry-kafka-clients-2.6:OPENTELEMETRY_VERSION")
+```
+
+### Usage (Tracing)
+
+There are two options for capturing traces, either using interceptors or wrapping clients, both described below.
+
+#### Using interceptors
+
+The Kafka clients API provides a way to "intercept" messages before they are sent to the brokers as well as messages received from the broker before being passed to the application.
+The OpenTelemetry instrumented Kafka library provides two interceptors to be configured to add tracing information automatically.
+The interceptor class has to be set in the properties bag used to create the Kafka client.
+
+Use the `TracingProducerInterceptor` for the producer in order to create a "send" span automatically, each time a message is sent.
+
+```java
+props.setProperty(ProducerConfig.INTERCEPTOR_CLASSES_CONFIG, TracingProducerInterceptor.class.getName());
+```
+
+Use the `TracingConsumerInterceptor` for the consumer in order to create a "receive" span automatically, each time a message is received.
+
+```java
+props.setProperty(ConsumerConfig.INTERCEPTOR_CLASSES_CONFIG, TracingConsumerInterceptor.class.getName());
+```
+
+#### Wrapping clients
+
+The other way is by wrapping the Kafka client with a tracing enabled Kafka client.
+
+Assuming you have a `Producer<K, V> producer` instance, you can wrap it in the following way.
+
+```java
+KafkaTelemetry telemetry = KafkaTelemetry.create(GlobalOpenTelemetry.get());
+Producer<String, String> tracingProducer = telemetry.wrap(producer);
+```
+
+Then use the `tracingProducer` as usual for sending messages to the Kafka cluster.
+
+Assuming you have a `Consumer<K, V> consumer` instance, you can wrap it in the following way.
+
+```java
+KafkaTelemetry telemetry = KafkaTelemetry.create(GlobalOpenTelemetry.get());
+Consumer<String, String> tracingConsumer = telemetry.wrap(this.consumer);
+```
+
+Then use the `tracingConsumer` as usual for receiving messages from the Kafka cluster.
+
+### Usage (Metrics)
 
 The Kafka client exposes metrics via `org.apache.kafka.common.metrics.MetricsReporter` interface.
 OpenTelemetry provides an implementation that bridges the metrics into OpenTelemetry.

instrumentation/ktor/ktor-1.0/library/README.md

@@ -1,8 +1,33 @@
-# Ktor Instrumentation
+# Library Instrumentation for Ktor versions 1.x
 
 This package contains libraries to help instrument Ktor. Currently, only server instrumentation is supported.
 
-## Initializing server instrumentation
+## Quickstart
+
+### Add these dependencies to your project:
+
+Replace `OPENTELEMETRY_VERSION` with the [latest
+release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-ktor-1.0).
+
+For Maven, add to your `pom.xml` dependencies:
+
+```xml
+<dependencies>
+  <dependency>
+    <groupId>io.opentelemetry.instrumentation</groupId>
+    <artifactId>opentelemetry-ktor-1.0</artifactId>
+    <version>OPENTELEMETRY_VERSION</version>
+  </dependency>
+</dependencies>
+```
+
+For Gradle, add to your dependencies:
+
+```groovy
+implementation("io.opentelemetry.instrumentation:opentelemetry-ktor-1.0:OPENTELEMETRY_VERSION")
+```
+
+## Usage
 
 Initialize instrumentation by installing the `KtorServerTracing` feature. You must set the `OpenTelemetry` to use with
 the feature.

instrumentation/ktor/ktor-2.0/library/README.md

@@ -1,7 +1,34 @@
-# Ktor Instrumentation
+# Library Instrumentation for Ktor version 2.0 and higher
 
 This package contains libraries to help instrument Ktor. Currently, only server instrumentation is supported.
 
+## Quickstart
+
+### Add these dependencies to your project:
+
+Replace `OPENTELEMETRY_VERSION` with the [latest
+release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-ktor-2.0).
+
+For Maven, add to your `pom.xml` dependencies:
+
+```xml
+<dependencies>
+  <dependency>
+    <groupId>io.opentelemetry.instrumentation</groupId>
+    <artifactId>opentelemetry-ktor-2.0</artifactId>
+    <version>OPENTELEMETRY_VERSION</version>
+  </dependency>
+</dependencies>
+```
+
+For Gradle, add to your dependencies:
+
+```groovy
+implementation("io.opentelemetry.instrumentation:opentelemetry-ktor-2.0:OPENTELEMETRY_VERSION")
+```
+
+## Usage
+
 ## Initializing server instrumentation
 
 Initialize instrumentation by installing the `KtorServerTracing` feature. You must set the `OpenTelemetry` to use with