Update READMEs (#830)

Author: trask

README.md

@@ -1,21 +1,36 @@
 # Java OpenTelemetry Examples
 
-This module contains a set of fully-functional, working examples of using the
-OpenTelemetry Java APIs and SDK that should all be able to be run locally. Some
-of them assume you have docker running on your local machine.
+This repository contains a set of fully functional, working examples of using the
+OpenTelemetry Java APIs and SDK. All examples can be run locally. Some
+examples require Docker to be running on your local machine.
 
-## Example modules:
+## Requirements
+
+Java 17 or higher is required to build the examples in this repository.
+To check your Java version, run:
+
+```bash
+java -version
+```
+
+To build the all of examples, run:
+
+```bash
+./gradlew assemble
+```
+
+## Example Modules
 
 - [Using the SDK AutoConfiguration module](autoconfigure)
-    - This module contains a fully-functional example of using the autoconfigure
+    - This module contains a fully functional example of using the autoconfigure
       SDK extension module to configure the SDK using only environment
       variables (or system properties).
     - Note: the `opentelemetry-sdk-extension-autoconfigure` module is still
       experimental at this time.
 - [Manual instrumentation of HTTP](http)
     - This module provides an example of writing manual instrumentation for
       HTTP, both client and server.
-    - Note more production-ready instrumentation for HTTP is provided as a part
+    - Note: More production-ready instrumentation for HTTP is provided as part
       of the [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation)
       project.
 - [Manual span creation and baggage propagation](manual-tracing)
@@ -24,53 +39,53 @@ of them assume you have docker running on your local machine.
     - Additionally, it demonstrates how to use the OpenTelemetry API to
       propagate baggage items.
 - [Configuring the Jaeger Exporter](jaeger)
-    - This module contains a fully-functional example of configuring the
-      OpenTelemetry SDK to use a Jaeger exporter, and send some spans to it
+    - This module contains a fully functional example of configuring the
+      OpenTelemetry SDK to use a Jaeger exporter and send spans to it
       using the OpenTelemetry API.
-    - Note: this example requires having docker installed to run the example.
+    - Note: This example requires Docker to be installed.
 - [Using the OpenTelemetry Java Agent](javaagent)
     - This module demonstrates using the OpenTelemetry Java Agent with a simple
-      spring boot application. Traces, metrics, and logs are exported to a
+      Spring Boot application. Traces, metrics, and logs are exported to a
       collector via OTLP.
 - [Spring native image telemetry with OpenTelemetry Spring Starter](spring-native)
     - This module demonstrates using the OpenTelemetry Spring Boot starter with a
-      Graal VM native image. Traces and metrics are exported to a collector via OTLP.
+      GraalVM native image. Traces and metrics are exported to a collector via OTLP.
 - [Configuring Log Appenders](log-appender)
     - This module demonstrates how to configure the Log4j and Logback appenders to
       bridge logs into the OpenTelemetry Log SDK.
 - [Configuring the Logging Exporters](logging)
-    - This module contains a fully-functional example of configuring the
+    - This module contains a fully functional example of configuring the
       OpenTelemetry SDK to use a logging exporter.
-- [Exporting Application logs using JSON logging in Kubernetes](logging-k8s-stdout-otlp-json)
+- [Exporting application logs using JSON logging in Kubernetes](logging-k8s-stdout-otlp-json)
     - This module demonstrates how to export application logs using JSON logging
       in Kubernetes.
 - [Using the OpenTelemetry metrics API](metrics)
     - This module contains examples of using the OpenTelemetry metrics APIs.
 - [Using OpenTelemetry Micrometer shim](micrometer-shim)
-    - This module contains an example of a typical micrometer setup (spring boot
-      with spring boot actuator) configured to bridge metrics to OpenTelemetry
-      with the micrometer shim.
-    - Note: the micrometer shim is still experimental at this time.
+    - This module contains an example of a typical Micrometer setup (Spring Boot
+      with Spring Boot Actuator) configured to bridge metrics to OpenTelemetry
+      with the Micrometer shim.
+    - Note: The Micrometer shim is still experimental at this time.
 - [Setting up OTLP exporters](otlp)
-    - OTLP is the OpenTelemetry Protocol. This module will demonstrate how to
-      configure the OTLP exporters, and send data to the OpenTelemetry collector
+    - OTLP is the OpenTelemetry Protocol. This module demonstrates how to
+      configure the OTLP exporters and send data to the OpenTelemetry Collector
       using them.
-    - Note: this example requires having docker installed to run the example.
+    - Note: This example requires Docker to be installed.
 - [Setting up the Prometheus exporter](prometheus)
-    - The module shows how to configure the OpenTelemetry SDK to expose an
+    - This module shows how to configure the OpenTelemetry SDK to expose an
       endpoint that can be scraped by Prometheus.
-    - Note: the prometheus metric reader is still experimental at this time.
+    - Note: The Prometheus metric reader is still experimental at this time.
 - [Manually Configuring the SDK](sdk-usage)
-    - This module shows some concrete examples of manually configuring the Java
-      OpenTelemetry SDK for Tracing.
+    - This module shows some concrete examples of manually configuring the
+      OpenTelemetry SDK for tracing.
 - [Telemetry Testing](telemetry-testing)
-    - This module demonstrates how to test OpenTelemetry instrumentation with a
+    - This module demonstrates how to test OpenTelemetry instrumentation with
       MockServer.
 - [Setting up the Zipkin exporter](zipkin)
-    - This module contains a fully-functional example of configuring the
-      OpenTelemetry SDK to use a Zipkin exporter, and send some spans to a
-      zipkin backend using the OpenTelemetry API.
-    - Note: this example requires having docker installed to run the example.
+    - This module contains a fully functional example of configuring the
+      OpenTelemetry SDK to use a Zipkin exporter and send spans to a
+      Zipkin backend using the OpenTelemetry API.
+    - Note: This example requires Docker to be installed.
 
 ## Contributing
 

autoconfigure/README.md

@@ -1,16 +1,17 @@
-# SDK autoconfiguration example
+# SDK Autoconfiguration Example
 
 This is a simple example that demonstrates the usage of
 the [OpenTelemetry SDK Autoconfigure](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure)
 module.
 
 ## Prerequisites
 
-* Java 1.8
+* Java 17 or higher is required to run Gradle and build this example
+* Java 8 or higher may be used to run the example once it has been built
 
-## How to run
+## How to Run
 
-First build this example application:
+First, build this example application:
 
 ```shell
 ../gradlew shadowJar

declarative-configuration/README.md

@@ -4,11 +4,12 @@ This example demonstrates how to use [declarative configuration](https://opentel
 
 The configuration file is located at [otel-sdk-config.yaml](./otel-sdk-config.yaml).
 
-# How to run
+# How to Run
 
 ## Prerequisites
 
-* Java 1.8
+* Java 17 or higher is required to run Gradle and build this example
+* Java 8 or higher may be used to run the example once it has been built
 
 ## Run
 
@@ -19,4 +20,4 @@ export OTEL_EXPERIMENTAL_CONFIG_FILE=$(pwd)/otel-sdk-config.yaml
 
 Observe how data is printed to the console as configured in [otel-sdk-config.yaml](./otel-sdk-config.yaml).
 
-For use with the OpenTelemetry Java, see [Java Agent declarative configuration](../javaagent/README.md#declarative-configuration).
+For use with the OpenTelemetry Java Agent, see [Java Agent declarative configuration](../javaagent/README.md#declarative-configuration).

grpc/README.md

@@ -1,17 +1,22 @@
-# GRPC Example
+# gRPC Example
 
 **Note:** This is an advanced scenario useful for people who want to *manually* instrument their own code.
-(If you're using the [java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation), you get this instrumentation "out-of-the-box" and this isn't necessary.)
+(If you're using the [Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation), you get this instrumentation "out-of-the-box" and this isn't necessary.)
 
 This is a simple example that demonstrates how to use the OpenTelemetry SDK
-to *manually* instrument a simple GRPC based Client/Server application.
+to *manually* instrument a simple gRPC-based client/server application.
 This example utilizes the [opentelemetry-grpc-1.6](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/grpc-1.6/library/README.md#library-instrumentation-for-grpc-160)
-to instrument both the GRPC client and server. 
+library to instrument both the gRPC client and server.
 
-# How to run
+# How to Run
 
 ## Prerequisites
-* Be on the grpc project root folder 
+
+* Java 17 or higher is required to run Gradle and build this example
+* Java 8 or higher may be used to run the example once it has been built
+
+Be in the gRPC project root folder:
+
 ```shell script
 cd grpc/
 ```

http/README.md

@@ -1,18 +1,19 @@
 # HTTP Example
 
-**Note:** This is an advanced scenario useful for people that want to *manually* instrument their own code. 
+**Note:** This is an advanced scenario useful for people who want to *manually* instrument their own code.
 
-This is a simple example that demonstrates how to use the OpenTelemetry SDK 
-to *manually* instrument a simple HTTP based Client/Server application. 
-The example creates the **Root Span** on the client and sends the context
+This is a simple example that demonstrates how to use the OpenTelemetry SDK
+to *manually* instrument a simple HTTP-based client/server application.
+The example creates the **root span** on the client and sends the context
 over the HTTP request. On the server side, the example shows how to extract the context
-and create a **Child Span** with attached a **Span Event**. 
+and create a **child span** with an attached **span event**.
 
-# How to run
+# How to Run
 
 ## Prerequisites
-* Java 1.8.231
-* Be on the project root folder
+
+* Java 17 or higher is required to run Gradle and build this example
+* Java 8 or higher may be used to run the example once it has been built
 
 ## 1 - Compile 
 ```shell script

jaeger/README.md

@@ -1,15 +1,16 @@
 # Jaeger Example
 
-This is a simple example that demonstrates how to use the OpenTelemetry SDK 
+This is a simple example that demonstrates how to use the OpenTelemetry SDK
 to instrument a simple application and export to a Jaeger backend.
 
-# How to run
+# How to Run
 
 ## Prerequisites
-* Java 1.8+
-* Docker 19.03
-* Jaeger 1.16 - [Link][jaeger]
 
+* Java 17 or higher is required to run Gradle and build this example
+* Java 8 or higher may be used to run the example once it has been built
+* Docker
+* Jaeger 1.16 or higher
 
 ## 1 - Compile 
 ```shell script

javaagent/README.md

@@ -3,58 +3,58 @@
 This example demonstrates simple usage of the OpenTelemetry Java Agent published
 by [opentelemetry-java-instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation).
 
-It consists of a spring boot application with:
+It consists of a Spring Boot application with:
 
-- A gradle task for downloading the OpenTelemetry Java Agent.
+- A Gradle task for downloading the OpenTelemetry Java Agent
 - A simple web API available at `GET http://localhost:8080/ping`. When called,
-  auto instrumentation from the OpenTelemetry Java Agent records spans and
+  auto-instrumentation from the OpenTelemetry Java Agent records spans and
   metrics. Additionally, there is manual trace and metric instrumentation, as
-  well as application logging performed in the context of traces using the log4j
-  API.
-- A docker compose setup configured to run the application and export to
-  the [collector](https://opentelemetry.io/docs/collector/) via OTLP.
-- The collector is configured with
+  well as application logging performed in the context of traces using the Log4j
+  API
+- A Docker Compose setup configured to run the application and export to
+  the [Collector](https://opentelemetry.io/docs/collector/) via OTLP
+- The Collector is configured with
   the [OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver)
-  and export it to standard out with
+  and exports to standard out with
   the [logging exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/debugexporter)
 
 ## Prerequisites
 
-* Java 1.8
-* Docker compose
+* Java 17 or higher is required to build and run this example
+* Docker Compose
 
-# How to run
+# How to Run
 
-Build the application jar
+Build the application jar:
 
 ```shell
 ../gradlew bootJar
 ```
 
-Run the application and the collector with docker compose
+Run the application and the Collector with Docker Compose:
 
 ```shell
-docker-compose up --build
+docker compose up --build
 ```
 
-In a separate shell, exercise the application by calling its endpoint
+In a separate shell, exercise the application by calling its endpoint:
 
 ```shell
 curl http://localhost:8080/ping
 ```
 
-Watch for spans, metrics, and logs in the collector log output
+Watch for spans, metrics, and logs in the Collector log output.
 
 ## Declarative Configuration
 
-By default, this example uses the [environment variable configuration schema](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) to configure the SDK. However, it also includes [sdk-config.yaml](./sdk-config.yaml) which demonstrates how the [declarative configuration](https://opentelemetry.io/docs/specs/otel/configuration/#declarative-configuration) scheme can be used to configure the SDK based on a YAML configuration file instead. 
+By default, this example uses the [environment variable configuration schema](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) to configure the SDK. However, it also includes [sdk-config.yaml](./sdk-config.yaml) which demonstrates how the [declarative configuration](https://opentelemetry.io/docs/specs/otel/configuration/#declarative-configuration) scheme can be used to configure the SDK based on a YAML configuration file instead.
 
 `sdk-config.yaml` extends the [opentelemetry-configuration sdk-config.yaml](https://github.com/open-telemetry/opentelemetry-configuration/blob/v0.3.0/examples/sdk-config.yaml) template, demonstrating:
 
-- Configuration of instrumentation (see `.instrumentation.java`) 
-- Configuration of [rule based routing sampler](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/samplers) (see `.tracer_provider.sampler.parent_based.root`)
+- Configuration of instrumentation (see `.instrumentation.java`)
+- Configuration of [rule-based routing sampler](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/samplers) (see `.tracer_provider.sampler.parent_based.root`)
 
-To use declarative configuration instead of the environment variable scheme, add the following before starting the application and collector:
+To use declarative configuration instead of the environment variable scheme, add the following before starting the application and Collector:
 
 ```shell
 export OTEL_EXPERIMENTAL_CONFIG_FILE=/sdk-config.yaml

kotlin-extension/README.md

@@ -1,23 +1,24 @@
-# Kotlin Extension examples
+# Kotlin Extension Examples
 
-This is a simple example that demonstrates how to use the Kotlin extension for attaching a Span context to a Kotlin
+This is a simple example that demonstrates how to use the Kotlin extension for attaching a span context to a Kotlin
 coroutine.
 
 ## Prerequisites
 
-* Java 1.8 or higher
+* Java 17 or higher is required to run Gradle and build this example
+* Java 8 or higher may be used to run the example once it has been built
 
 ## Compile
 
-Compile with
+Compile with:
 
 ```shell script
 ../gradlew shadowJar
 ```
 
 ## Run
 
-The following commands are used to run the examples.
+Use the following command to run the example:
 
 ```shell script
 java -cp build/libs/kotlin-extension-0.1.0-SNAPSHOT-all.jar io.opentelemetry.example.kotlinextension.Application