From 77b7a7c856fa43e741e884baa0d55368cbf60887 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 29 Sep 2025 20:06:08 -0700 Subject: [PATCH 1/7] Fix Java version requirements --- README.md | 17 +++++++++++++++++ autoconfigure/README.md | 3 ++- declarative-configuration/README.md | 3 ++- grpc/README.md | 7 ++++++- http/README.md | 5 +++-- jaeger/README.md | 5 +++-- javaagent/README.md | 2 +- kotlin-extension/README.md | 3 ++- log-appender/README.md | 5 ++++- micrometer-shim/README.md | 6 ++++++ otlp/README.md | 8 ++++++++ prometheus/README.md | 3 ++- sdk-usage/README.md | 7 +++++-- spring-native/README.md | 3 ++- zipkin/README.md | 4 +++- 15 files changed, 66 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 565905071d..8a1c554f3a 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,23 @@ 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. +## 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 examples, run: + +```bash +./gradlew assemble +``` + +Note: Individual examples may run on lower Java versions (see each module's README for runtime requirements). + ## Example modules: - [Using the SDK AutoConfiguration module](autoconfigure) diff --git a/autoconfigure/README.md b/autoconfigure/README.md index c1753dd5ab..22386e3e21 100644 --- a/autoconfigure/README.md +++ b/autoconfigure/README.md @@ -6,7 +6,8 @@ module. ## Prerequisites -* Java 1.8 +* Java 17 or higher is required to build this example (to run Gradle) +* Java 8 or higher is required to run the compiled example ## How to run diff --git a/declarative-configuration/README.md b/declarative-configuration/README.md index 059c9802bc..509a7b5c53 100644 --- a/declarative-configuration/README.md +++ b/declarative-configuration/README.md @@ -8,7 +8,8 @@ The configuration file is located at [otel-sdk-config.yaml](./otel-sdk-config.ya ## Prerequisites -* Java 1.8 +* Java 17 or higher is required to build this example (to run Gradle) +* Java 8 or higher is required to run the compiled example ## Run diff --git a/grpc/README.md b/grpc/README.md index e9279a4cb7..f68cc8ca97 100644 --- a/grpc/README.md +++ b/grpc/README.md @@ -11,7 +11,12 @@ to instrument both the GRPC client and server. # How to run ## Prerequisites -* Be on the grpc project root folder + +* Java 17 or higher is required to build this example (to run Gradle) +* Java 8 or higher is required to run the compiled example + +Be on the grpc project root folder: + ```shell script cd grpc/ ``` diff --git a/http/README.md b/http/README.md index 0853b313c7..ce5603aea9 100644 --- a/http/README.md +++ b/http/README.md @@ -11,8 +11,9 @@ and create a **Child Span** with attached a **Span Event**. # How to run ## Prerequisites -* Java 1.8.231 -* Be on the project root folder + +* Java 17 or higher is required to build this example (to run Gradle) +* Java 8 or higher is required to run the compiled example ## 1 - Compile ```shell script diff --git a/jaeger/README.md b/jaeger/README.md index 05418ca5ed..ad71e1c828 100644 --- a/jaeger/README.md +++ b/jaeger/README.md @@ -6,11 +6,12 @@ to instrument a simple application and export to a Jaeger backend. # How to run ## Prerequisites -* Java 1.8+ + +* Java 17 or higher is required to build this example (to run Gradle) +* Java 8 or higher is required to run the compiled example * Docker 19.03 * Jaeger 1.16 - [Link][jaeger] - ## 1 - Compile ```shell script ../gradlew shadowJar diff --git a/javaagent/README.md b/javaagent/README.md index 1a93d96c82..6bd9392d75 100644 --- a/javaagent/README.md +++ b/javaagent/README.md @@ -20,7 +20,7 @@ It consists of a spring boot application with: ## Prerequisites -* Java 1.8 +* Java 17 or higher is required to build and run this example * Docker compose # How to run diff --git a/kotlin-extension/README.md b/kotlin-extension/README.md index 1a855ee3ee..d2d9ea3388 100644 --- a/kotlin-extension/README.md +++ b/kotlin-extension/README.md @@ -5,7 +5,8 @@ coroutine. ## Prerequisites -* Java 1.8 or higher +* Java 17 or higher is required to build this example (to run Gradle) +* Java 8 or higher is required to run the compiled example ## Compile diff --git a/log-appender/README.md b/log-appender/README.md index eac9529ef2..eed02e6740 100644 --- a/log-appender/README.md +++ b/log-appender/README.md @@ -23,11 +23,14 @@ Details about the example: ## Prerequisites -* Java 1.8 +* Java 17 or higher is required to build this example (to run Gradle) +* Java 11 or higher is required to run the compiled example * Docker compose # How to run +``` + Run the collector via docker ```shell diff --git a/micrometer-shim/README.md b/micrometer-shim/README.md index 4cb6f852cc..7fa25bc941 100644 --- a/micrometer-shim/README.md +++ b/micrometer-shim/README.md @@ -12,6 +12,12 @@ It consists of a spring boot application with: # How to run +## Prerequisites + +* Java 17 or higher is required to build and run this example + +## Run + Run the application ```shell diff --git a/otlp/README.md b/otlp/README.md index b675ac470a..26f1b58072 100644 --- a/otlp/README.md +++ b/otlp/README.md @@ -1,5 +1,13 @@ ### Running the OTLP example +## Prerequisites + +* Java 17 or higher is required to build this example (to run Gradle) +* Java 8 or higher is required to run the compiled example +* Docker compose + +## Run + Assuming you're on a unix-alike (mac, linux, etc): In a shell: diff --git a/prometheus/README.md b/prometheus/README.md index 447d6222b9..6932d74112 100644 --- a/prometheus/README.md +++ b/prometheus/README.md @@ -11,7 +11,8 @@ metrics via HTTP. ## Prerequisites -* Java 1.7 +* Java 17 or higher is required to build this example (to run Gradle) +* Java 8 or higher is required to run the compiled example * Docker 19.03 * Docker compose diff --git a/sdk-usage/README.md b/sdk-usage/README.md index 9f161f57bb..34234b38ef 100644 --- a/sdk-usage/README.md +++ b/sdk-usage/README.md @@ -3,11 +3,14 @@ This is a simple example that demonstrates how to use and configure the OpenTelemetry SDK. ## Prerequisites -* Java 1.8 or higher +* Java 17 or higher is required to build this example (to run Gradle) +* Java 8 or higher is required to run the compiled example ## Compile -Compile with + +Compile with: + ```shell script ../gradlew shadowJar ``` diff --git a/spring-native/README.md b/spring-native/README.md index 177701b370..7b296f0559 100644 --- a/spring-native/README.md +++ b/spring-native/README.md @@ -25,7 +25,8 @@ We have included the [OpenTelemetry Spring starter](https://opentelemetry.io/doc ## Prerequisites -* GraalVM for Java 17 +* Java 17 or higher is required to build and run this example +* GraalVM for Java 17 (required for native image compilation) * Docker compose # How to run diff --git a/zipkin/README.md b/zipkin/README.md index 2a8d262bae..f03ba2085e 100644 --- a/zipkin/README.md +++ b/zipkin/README.md @@ -6,7 +6,9 @@ to instrument a simple application using Zipkin as trace exporter. # How to run ## Prerequisites -* Java 1.8.231 + +* Java 17 or higher is required to build this example (to run Gradle) +* Java 8 or higher is required to run the compiled example * Docker 19.03 ## 1 - Compile From 2d7189fa21e0abaa591cc2e336a2bb00c11cdbd8 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 29 Sep 2025 20:13:01 -0700 Subject: [PATCH 2/7] Docker compose --- javaagent/README.md | 8 ++++---- log-appender/README.md | 6 ++---- otlp/README.md | 4 ++-- otlp/docker/README.md | 6 +++--- prometheus/README.md | 6 +++--- spring-native/README.md | 8 ++++---- 6 files changed, 18 insertions(+), 20 deletions(-) diff --git a/javaagent/README.md b/javaagent/README.md index 6bd9392d75..1cf6b58eb6 100644 --- a/javaagent/README.md +++ b/javaagent/README.md @@ -11,7 +11,7 @@ It consists of a spring boot application with: 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 +- 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) @@ -21,7 +21,7 @@ It consists of a spring boot application with: ## Prerequisites * Java 17 or higher is required to build and run this example -* Docker compose +* Docker Compose # How to run @@ -31,10 +31,10 @@ Build the application jar ../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 diff --git a/log-appender/README.md b/log-appender/README.md index eed02e6740..872e021f8c 100644 --- a/log-appender/README.md +++ b/log-appender/README.md @@ -25,16 +25,14 @@ Details about the example: * Java 17 or higher is required to build this example (to run Gradle) * Java 11 or higher is required to run the compiled example -* Docker compose +* Docker Compose # How to run -``` - Run the collector via docker ```shell -docker-compose up +docker compose up ``` In a separate shell, run the application diff --git a/otlp/README.md b/otlp/README.md index 26f1b58072..ce2937fa3f 100644 --- a/otlp/README.md +++ b/otlp/README.md @@ -4,7 +4,7 @@ * Java 17 or higher is required to build this example (to run Gradle) * Java 8 or higher is required to run the compiled example -* Docker compose +* Docker Compose ## Run @@ -13,7 +13,7 @@ Assuming you're on a unix-alike (mac, linux, etc): In a shell: ```shell cd docker -docker-compose up +docker compose up ``` In a separate shell: diff --git a/otlp/docker/README.md b/otlp/docker/README.md index 4db17ee28d..7640f3dfee 100644 --- a/otlp/docker/README.md +++ b/otlp/docker/README.md @@ -2,12 +2,12 @@ *IMPORTANT:* This uses a pre-released version of the OpenTelemetry Collector. -This demo uses `docker-compose` and by default runs against the +This demo uses `docker compose` and by default runs against the `otel/opentelemetry-collector-dev:latest` image. To run the demo, switch to this directory and run: ```shell -docker-compose up -d +docker compose up -d ``` The demo exposes the following backends: @@ -21,5 +21,5 @@ Notes: - It may take some time for the application metrics to appear on the Prometheus dashboard; -To clean up any docker container from the demo run `docker-compose down` from +To clean up any docker container from the demo run `docker compose down` from this directory. diff --git a/prometheus/README.md b/prometheus/README.md index 6932d74112..67c0db0622 100644 --- a/prometheus/README.md +++ b/prometheus/README.md @@ -14,7 +14,7 @@ metrics via HTTP. * Java 17 or higher is required to build this example (to run Gradle) * Java 8 or higher is required to run the compiled example * Docker 19.03 -* Docker compose +* Docker Compose ## 1 - Compile @@ -24,10 +24,10 @@ metrics via HTTP. ## 2 - Run -Start the application and prometheus via docker compose +Start the application and prometheus via Docker Compose ```shell -docker-compose up +docker compose up ``` ## 3 - View metrics diff --git a/spring-native/README.md b/spring-native/README.md index 7b296f0559..2a8c71b9ba 100644 --- a/spring-native/README.md +++ b/spring-native/README.md @@ -5,7 +5,7 @@ This example demonstrates usage of the [OpenTelemetry Spring starter](https://op The example uses the following elements: - A web API available at `GET http://localhost:8080/ping`. -- A docker compose setup configured to run the application and export to +- A Docker Compose setup configured to run the application and export to the [collector](https://opentelemetry.io/docs/collector/) via OTLP. - A collector configured with the [OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver) @@ -27,7 +27,7 @@ We have included the [OpenTelemetry Spring starter](https://opentelemetry.io/doc * Java 17 or higher is required to build and run this example * GraalVM for Java 17 (required for native image compilation) -* Docker compose +* Docker Compose # How to run @@ -37,9 +37,9 @@ cd spring-native ../gradlew bootBuildImage --imageName=otel-native-graalvm ``` -Run the application and the collector with docker compose +Run the application and the collector with Docker Compose ```shell -docker-compose up +docker compose up ``` In a separate shell, exercise the application by calling its endpoint From f7eaf37ac86738e905b455c806c260433c00d682 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 29 Sep 2025 20:20:49 -0700 Subject: [PATCH 3/7] copyedit --- README.md | 58 ++++++++++++++--------------- autoconfigure/README.md | 6 +-- declarative-configuration/README.md | 4 +- grpc/README.md | 12 +++--- http/README.md | 12 +++--- jaeger/README.md | 6 +-- javaagent/README.md | 34 ++++++++--------- kotlin-extension/README.md | 8 ++-- log-appender/README.md | 26 ++++++------- micrometer-shim/README.md | 16 ++++---- otlp/README.md | 23 +----------- prometheus/README.md | 10 ++--- sdk-usage/README.md | 4 +- spring-native/README.md | 29 ++++++++------- zipkin/README.md | 6 +-- 15 files changed, 118 insertions(+), 136 deletions(-) diff --git a/README.md b/README.md index 8a1c554f3a..7fc32776fe 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # 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. ## Requirements @@ -21,10 +21,10 @@ To build the examples, run: Note: Individual examples may run on lower Java versions (see each module's README for runtime requirements). -## Example modules: +## 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 @@ -32,7 +32,7 @@ Note: Individual examples may run on lower Java versions (see each module's READ - [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) @@ -41,53 +41,53 @@ Note: Individual examples may run on lower Java versions (see each module's READ - 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 diff --git a/autoconfigure/README.md b/autoconfigure/README.md index 22386e3e21..44f7e800a4 100644 --- a/autoconfigure/README.md +++ b/autoconfigure/README.md @@ -1,4 +1,4 @@ -# 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) @@ -9,9 +9,9 @@ module. * Java 17 or higher is required to build this example (to run Gradle) * Java 8 or higher is required to run the compiled example -## How to run +## How to Run -First build this example application: +First, build this example application: ```shell ../gradlew shadowJar diff --git a/declarative-configuration/README.md b/declarative-configuration/README.md index 509a7b5c53..c86d1049d2 100644 --- a/declarative-configuration/README.md +++ b/declarative-configuration/README.md @@ -4,7 +4,7 @@ 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 @@ -20,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). diff --git a/grpc/README.md b/grpc/README.md index f68cc8ca97..c9be288250 100644 --- a/grpc/README.md +++ b/grpc/README.md @@ -1,21 +1,21 @@ -# 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 * Java 17 or higher is required to build this example (to run Gradle) * Java 8 or higher is required to run the compiled example -Be on the grpc project root folder: +Be in the gRPC project root folder: ```shell script cd grpc/ diff --git a/http/README.md b/http/README.md index ce5603aea9..57ba6d0a2e 100644 --- a/http/README.md +++ b/http/README.md @@ -1,14 +1,14 @@ # 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 diff --git a/jaeger/README.md b/jaeger/README.md index ad71e1c828..6d71e0442f 100644 --- a/jaeger/README.md +++ b/jaeger/README.md @@ -1,16 +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 17 or higher is required to build this example (to run Gradle) * Java 8 or higher is required to run the compiled example * Docker 19.03 -* Jaeger 1.16 - [Link][jaeger] +* Jaeger 1.16 or higher ## 1 - Compile ```shell script diff --git a/javaagent/README.md b/javaagent/README.md index 1cf6b58eb6..34df7e7e67 100644 --- a/javaagent/README.md +++ b/javaagent/README.md @@ -3,19 +3,19 @@ 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. + 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 [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 @@ -23,38 +23,38 @@ It consists of a spring boot application with: * 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 ``` -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 diff --git a/kotlin-extension/README.md b/kotlin-extension/README.md index d2d9ea3388..c87033cbf0 100644 --- a/kotlin-extension/README.md +++ b/kotlin-extension/README.md @@ -1,6 +1,6 @@ -# 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 @@ -10,7 +10,7 @@ coroutine. ## Compile -Compile with +Compile with: ```shell script ../gradlew shadowJar @@ -18,7 +18,7 @@ Compile with ## 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 diff --git a/log-appender/README.md b/log-appender/README.md index 872e021f8c..ff1d0be4c8 100644 --- a/log-appender/README.md +++ b/log-appender/README.md @@ -1,25 +1,25 @@ # OpenTelemetry Log Appender Example -This example demonstrates an application configured to use the OpenTelemetry Log -Appenders to bridge logs into the OpenTelemetry Log SDK, and export +This example demonstrates an application configured to use the OpenTelemetry log +appenders to bridge logs into the OpenTelemetry Log SDK and export via [OTLP](https://opentelemetry.io/docs/reference/specification/protocol/otlp/). Details about the example: * The OpenTelemetry Log SDK is configured to export data to - the [collector](https://opentelemetry.io/docs/collector/), which prints the - logs to the console. + the [Collector](https://opentelemetry.io/docs/collector/), which prints the + logs to the console * The application is configured with a variety of log solutions: * Log4j API [configured](./src/main/resources/log4j2.xml) to print logs to the console and - the [OpenTelemetry Log4J Appender](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/log4j/log4j-appender-2.17/library/README.md). + the [OpenTelemetry Log4j Appender](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/log4j/log4j-appender-2.17/library/README.md) * SLF4J API [configured with Logback](./src/main/resources/logback.xml) to print logs to the console and - the [OpenTelemetry Logback Appender](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/logback/logback-appender-1.0/library/README.md). - * [JUL to SLF4J](./build.gradle.kts), which bridges JUL logs to the SLF4J API, and - ultimately to Logback. + the [OpenTelemetry Logback Appender](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/logback/logback-appender-1.0/library/README.md) + * [JUL to SLF4J](./build.gradle.kts), which bridges JUL logs to the SLF4J API and + ultimately to Logback * Demonstrates how trace context is propagated to logs when recorded within a - span. + span ## Prerequisites @@ -27,18 +27,18 @@ Details about the example: * Java 11 or higher is required to run the compiled example * Docker Compose -# How to run +# How to Run -Run the collector via docker +Run the Collector via Docker: ```shell docker compose up ``` -In a separate shell, run the application +In a separate shell, run the application: ```shell ../gradlew run ``` -Watch the collector logs to see exported log records +Watch the Collector logs to see exported log records. diff --git a/micrometer-shim/README.md b/micrometer-shim/README.md index 7fa25bc941..35e1c2d2a0 100644 --- a/micrometer-shim/README.md +++ b/micrometer-shim/README.md @@ -1,16 +1,16 @@ # Micrometer Shim Example This example demonstrates a typical use case -of [micrometer shim](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/micrometer/micrometer-1.5/library). +of [Micrometer shim](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/micrometer/micrometer-1.5/library). -It consists of a spring boot application with: +It consists of a Spring Boot application with: - A simple web API available at `GET http://localhost:8080/ping` -- Instrumented with the spring boot actuator and micrometer -- Micrometer metrics bridged to OpenTelemetry using the micrometer shim -- OpenTelemetry metrics exported with prometheus +- Instrumented with the Spring Boot Actuator and Micrometer +- Micrometer metrics bridged to OpenTelemetry using the Micrometer shim +- OpenTelemetry metrics exported with Prometheus -# How to run +# How to Run ## Prerequisites @@ -18,13 +18,13 @@ It consists of a spring boot application with: ## Run -Run the application +Run the application: ```shell ../gradlew bootRun ``` -Exercise the application by calling its endpoint +Exercise the application by calling its endpoint: ```shell curl http://localhost:8080/ping diff --git a/otlp/README.md b/otlp/README.md index ce2937fa3f..681bd8559f 100644 --- a/otlp/README.md +++ b/otlp/README.md @@ -1,22 +1 @@ -### Running the OTLP example - -## Prerequisites - -* Java 17 or higher is required to build this example (to run Gradle) -* Java 8 or higher is required to run the compiled example -* Docker Compose - -## Run - -Assuming you're on a unix-alike (mac, linux, etc): - -In a shell: -```shell -cd docker -docker compose up -``` - -In a separate shell: -```shell -../gradlew run -``` \ No newline at end of file +# OTLP Example\n\n## Prerequisites\n\n* Java 17 or higher is required to build this example (to run Gradle)\n* Java 8 or higher is required to run the compiled example\n* Docker Compose\n\n## Run\n\nAssuming you're on a Unix-like system (macOS, Linux, etc.):\n\nIn a shell:\n\n```shell\ncd docker\ndocker compose up\n```\n\nIn a separate shell:\n\n```shell\n../gradlew run\n``` \ No newline at end of file diff --git a/prometheus/README.md b/prometheus/README.md index 67c0db0622..b132c98247 100644 --- a/prometheus/README.md +++ b/prometheus/README.md @@ -4,10 +4,10 @@ This example demonstrates how to use the OpenTelemetry SDK to instrument a simple application using Prometheus as the metric exporter and expose the metrics via HTTP. -These are collected by a Prometheus instance which is configured to pull these +These metrics are collected by a Prometheus instance which is configured to scrape metrics via HTTP. -# How to run +# How to Run ## Prerequisites @@ -24,15 +24,15 @@ metrics via HTTP. ## 2 - Run -Start the application and prometheus via Docker Compose +Start the application and Prometheus via Docker Compose: ```shell docker compose up ``` -## 3 - View metrics +## 3 - View Metrics -To view metrics in prometheus, navigate to: +To view metrics in Prometheus, navigate to: http://localhost:9090/graph?g0.range_input=15m&g0.expr=incoming_messages&g0.tab=0 diff --git a/sdk-usage/README.md b/sdk-usage/README.md index 34234b38ef..44fe85b464 100644 --- a/sdk-usage/README.md +++ b/sdk-usage/README.md @@ -1,6 +1,6 @@ # SDK Usage Examples -This is a simple example that demonstrates how to use and configure the OpenTelemetry SDK. +This is a simple example that demonstrates how to use and configure the OpenTelemetry SDK. ## Prerequisites @@ -17,7 +17,7 @@ Compile with: ## Run -The following commands are used to run the examples. +Use the following commands to run the examples: ```shell script java -cp build/libs/opentelemetry-examples-sdk-usage-0.1.0-SNAPSHOT-all.jar io.opentelemetry.sdk.example.ConfigureTraceExample ``` diff --git a/spring-native/README.md b/spring-native/README.md index 2a8c71b9ba..484d76aa7c 100644 --- a/spring-native/README.md +++ b/spring-native/README.md @@ -4,18 +4,18 @@ This example demonstrates usage of the [OpenTelemetry Spring starter](https://op The example uses the following elements: -- A web API available at `GET http://localhost:8080/ping`. +- A web API available at `GET http://localhost:8080/ping` - A Docker Compose setup configured to run the application and export to - the [collector](https://opentelemetry.io/docs/collector/) via OTLP. -- A collector configured with + the [Collector](https://opentelemetry.io/docs/collector/) via OTLP +- A Collector configured with the [OTLP receiver](https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver) - and exporting to the standard output with - the [logging exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/debugexporter). -- A spring configuration to suppress spans for the `/actuator` endpoint -- A spring configuration to set OTLP headers dynamically + and exporting to standard output with + the [logging exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/debugexporter) +- A Spring configuration to suppress spans for the `/actuator` endpoint +- A Spring configuration to set OTLP headers dynamically (not needed for the example - it shows how to configure exporters programmatically) -# Description of the instrumentation set-up +# Description of the Instrumentation Setup We have included the [OpenTelemetry Spring starter](https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/) to instrument the HTTP calls, the logs, the SQL queries, and send the OpenTelemetry data via OTLP: @@ -29,25 +29,28 @@ We have included the [OpenTelemetry Spring starter](https://opentelemetry.io/doc * GraalVM for Java 17 (required for native image compilation) * Docker Compose -# How to run +# How to Run + +Build the GraalVM native image: -Build the GraalVM native image ```shell cd spring-native ../gradlew bootBuildImage --imageName=otel-native-graalvm ``` -Run the application and the collector with Docker Compose +Run the application and the Collector with Docker Compose: + ```shell docker compose up ``` -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. Example of the beginning of the collector log after the ping: ``` diff --git a/zipkin/README.md b/zipkin/README.md index f03ba2085e..8c90e61c0c 100644 --- a/zipkin/README.md +++ b/zipkin/README.md @@ -1,9 +1,9 @@ # Zipkin Example -This is a simple example that demonstrates how to use the OpenTelemetry SDK -to instrument a simple application using Zipkin as trace exporter. +This is a simple example that demonstrates how to use the OpenTelemetry SDK +to instrument a simple application using Zipkin as the trace exporter. -# How to run +# How to Run ## Prerequisites From 534828c1189dbec35cca7cec205407cf9c45ab34 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 29 Sep 2025 20:25:14 -0700 Subject: [PATCH 4/7] updates --- README.md | 4 +--- autoconfigure/README.md | 4 ++-- declarative-configuration/README.md | 4 ++-- grpc/README.md | 4 ++-- http/README.md | 4 ++-- jaeger/README.md | 4 ++-- kotlin-extension/README.md | 4 ++-- log-appender/README.md | 2 +- otlp/README.md | 2 +- prometheus/README.md | 4 ++-- sdk-usage/README.md | 4 ++-- zipkin/README.md | 4 ++-- 12 files changed, 21 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 7fc32776fe..7a35020f0b 100644 --- a/README.md +++ b/README.md @@ -13,14 +13,12 @@ To check your Java version, run: java -version ``` -To build the examples, run: +To build the all of examples, run: ```bash ./gradlew assemble ``` -Note: Individual examples may run on lower Java versions (see each module's README for runtime requirements). - ## Example Modules - [Using the SDK AutoConfiguration module](autoconfigure) diff --git a/autoconfigure/README.md b/autoconfigure/README.md index 44f7e800a4..5363a4e16a 100644 --- a/autoconfigure/README.md +++ b/autoconfigure/README.md @@ -6,8 +6,8 @@ module. ## Prerequisites -* Java 17 or higher is required to build this example (to run Gradle) -* Java 8 or higher is required to run the compiled example +* 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 diff --git a/declarative-configuration/README.md b/declarative-configuration/README.md index c86d1049d2..50d0afaf30 100644 --- a/declarative-configuration/README.md +++ b/declarative-configuration/README.md @@ -8,8 +8,8 @@ The configuration file is located at [otel-sdk-config.yaml](./otel-sdk-config.ya ## Prerequisites -* Java 17 or higher is required to build this example (to run Gradle) -* Java 8 or higher is required to run the compiled example +* 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 diff --git a/grpc/README.md b/grpc/README.md index c9be288250..a5f75ab531 100644 --- a/grpc/README.md +++ b/grpc/README.md @@ -12,8 +12,8 @@ library to instrument both the gRPC client and server. ## Prerequisites -* Java 17 or higher is required to build this example (to run Gradle) -* Java 8 or higher is required to run the compiled example +* 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: diff --git a/http/README.md b/http/README.md index 57ba6d0a2e..17d002ef67 100644 --- a/http/README.md +++ b/http/README.md @@ -12,8 +12,8 @@ and create a **child span** with an attached **span event**. ## Prerequisites -* Java 17 or higher is required to build this example (to run Gradle) -* Java 8 or higher is required to run the compiled example +* 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 diff --git a/jaeger/README.md b/jaeger/README.md index 6d71e0442f..0ac4f29253 100644 --- a/jaeger/README.md +++ b/jaeger/README.md @@ -7,8 +7,8 @@ to instrument a simple application and export to a Jaeger backend. ## Prerequisites -* Java 17 or higher is required to build this example (to run Gradle) -* Java 8 or higher is required to run the compiled example +* 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 19.03 * Jaeger 1.16 or higher diff --git a/kotlin-extension/README.md b/kotlin-extension/README.md index c87033cbf0..19f1c39089 100644 --- a/kotlin-extension/README.md +++ b/kotlin-extension/README.md @@ -5,8 +5,8 @@ coroutine. ## Prerequisites -* Java 17 or higher is required to build this example (to run Gradle) -* Java 8 or higher is required to run the compiled example +* 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 diff --git a/log-appender/README.md b/log-appender/README.md index ff1d0be4c8..d715c7aba9 100644 --- a/log-appender/README.md +++ b/log-appender/README.md @@ -23,7 +23,7 @@ Details about the example: ## Prerequisites -* Java 17 or higher is required to build this example (to run Gradle) +* Java 17 or higher is required to run Gradle and build this example * Java 11 or higher is required to run the compiled example * Docker Compose diff --git a/otlp/README.md b/otlp/README.md index 681bd8559f..72284107a1 100644 --- a/otlp/README.md +++ b/otlp/README.md @@ -1 +1 @@ -# OTLP Example\n\n## Prerequisites\n\n* Java 17 or higher is required to build this example (to run Gradle)\n* Java 8 or higher is required to run the compiled example\n* Docker Compose\n\n## Run\n\nAssuming you're on a Unix-like system (macOS, Linux, etc.):\n\nIn a shell:\n\n```shell\ncd docker\ndocker compose up\n```\n\nIn a separate shell:\n\n```shell\n../gradlew run\n``` \ No newline at end of file +# OTLP Example\n\n## Prerequisites\n\n* Java 17 or higher is required to run Gradle and build this example\n* Java 8 or higher may be used to run the example once it has been built\n* Docker Compose\n\n## Run\n\nAssuming you're on a Unix-like system (macOS, Linux, etc.):\n\nIn a shell:\n\n```shell\ncd docker\ndocker compose up\n```\n\nIn a separate shell:\n\n```shell\n../gradlew run\n``` \ No newline at end of file diff --git a/prometheus/README.md b/prometheus/README.md index b132c98247..59b39dc377 100644 --- a/prometheus/README.md +++ b/prometheus/README.md @@ -11,8 +11,8 @@ metrics via HTTP. ## Prerequisites -* Java 17 or higher is required to build this example (to run Gradle) -* Java 8 or higher is required to run the compiled example +* 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 19.03 * Docker Compose diff --git a/sdk-usage/README.md b/sdk-usage/README.md index 44fe85b464..553602e2f2 100644 --- a/sdk-usage/README.md +++ b/sdk-usage/README.md @@ -4,8 +4,8 @@ This is a simple example that demonstrates how to use and configure the OpenTele ## Prerequisites -* Java 17 or higher is required to build this example (to run Gradle) -* Java 8 or higher is required to run the compiled example +* 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 diff --git a/zipkin/README.md b/zipkin/README.md index 8c90e61c0c..7206a3c68d 100644 --- a/zipkin/README.md +++ b/zipkin/README.md @@ -7,8 +7,8 @@ to instrument a simple application using Zipkin as the trace exporter. ## Prerequisites -* Java 17 or higher is required to build this example (to run Gradle) -* Java 8 or higher is required to run the compiled example +* 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 19.03 ## 1 - Compile From 9958740fcda8340993174bd2ae28e1a407ecaaa8 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 29 Sep 2025 20:32:15 -0700 Subject: [PATCH 5/7] fix --- otlp/README.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/otlp/README.md b/otlp/README.md index 72284107a1..bd26793bc3 100644 --- a/otlp/README.md +++ b/otlp/README.md @@ -1 +1,24 @@ -# OTLP Example\n\n## Prerequisites\n\n* Java 17 or higher is required to run Gradle and build this example\n* Java 8 or higher may be used to run the example once it has been built\n* Docker Compose\n\n## Run\n\nAssuming you're on a Unix-like system (macOS, Linux, etc.):\n\nIn a shell:\n\n```shell\ncd docker\ndocker compose up\n```\n\nIn a separate shell:\n\n```shell\n../gradlew run\n``` \ No newline at end of file +# OTLP Example + +## Prerequisites + +* 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 Compose + +## How to Run + +Assuming you're on a Unix-like system (macOS, Linux, etc.): + +In a shell: + +```shell +cd docker +docker compose up +``` + +In a separate shell: + +```shell +../gradlew run +``` \ No newline at end of file From 4775a5d60fae332a2e1adb8fb80dfcc19e7f1856 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 29 Sep 2025 20:33:54 -0700 Subject: [PATCH 6/7] Update jaeger/README.md --- jaeger/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jaeger/README.md b/jaeger/README.md index 0ac4f29253..dfb0a744a5 100644 --- a/jaeger/README.md +++ b/jaeger/README.md @@ -9,7 +9,7 @@ to instrument a simple application and export to a Jaeger backend. * 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 19.03 +* Docker * Jaeger 1.16 or higher ## 1 - Compile From 706391ace6d191f055834b33ad31127155eb139d Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 29 Sep 2025 20:34:57 -0700 Subject: [PATCH 7/7] up --- javaagent/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/javaagent/README.md b/javaagent/README.md index 34df7e7e67..ab3a0f7caf 100644 --- a/javaagent/README.md +++ b/javaagent/README.md @@ -25,7 +25,7 @@ It consists of a Spring Boot application with: # How to Run -Build the application JAR: +Build the application jar: ```shell ../gradlew bootJar