Port opentelemetry-java-examples

.gitattributes

@@ -0,0 +1,7 @@
+* text=auto eol=lf
+
+*.bat text eol=crlf
+*.cmd text eol=crlf
+
+*.jar -text
+*.png -text

.github/workflows/pr-build.yml

@@ -0,0 +1,28 @@
+name: "PR Examples Build"
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'examples/**'
+jobs:
+  build:
+    name: Build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - macos-latest
+          - ubuntu-20.04
+    steps:
+      - uses: actions/[email protected]
+      - name: Setup Java 17
+        uses: actions/setup-java@v2
+        with:
+          distribution: temurin
+          java-version: 17
+      - uses: gradle/gradle-build-action@v2
+        with:
+          arguments: clean check shadowJar
+      - run: java -cp sdk-usage/build/libs/opentelemetry-examples-sdk-usage-0.1.0-SNAPSHOT-all.jar io.opentelemetry.sdk.example.ConfigureSpanProcessorExample

.gitignore

@@ -0,0 +1,35 @@
+# Gradle
+build
+.gradle
+local.properties
+out/
+
+# Maven (proto)
+target
+
+# IntelliJ IDEA
+.idea
+*.iml
+
+# Eclipse
+.classpath
+.project
+.settings
+bin
+
+# NetBeans
+/.nb-gradle
+/.nb-gradle-properties
+
+# VS Code
+.vscode
+
+# OS X
+.DS_Store
+
+# Emacs
+*~
+\#*\#
+
+# Vim
+.swp

README.md

@@ -1,3 +1,40 @@
-# OpenTelemetry Java
+# Java OpenTelemetry Examples
 
-Under Construction: We will be moving in docs and examples for app authors from the opentelemetry-java and opentelemetry-java-instrumentation.
+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.
+
+## Example modules:
+
+- [Using the SDK AutoConfiguration module](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.
+- [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 using them.
+  - Note: this example requires having docker installed to run the example.
+- [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 using the OpenTelemetry API.
+  - Note: this example requires having docker installed to run the example.
+- [Setting up the Zipkin exporter](zipkin)
+  - This module contains a fully-functional example of configuring the OpenTelemetry SDK to use a
+    Jaeger exporter, and send some spans to a zipkin backend using the OpenTelemetry API.
+  - Note: this example requires having docker installed to run the example.
+- [Configuring the Logging Exporters](logging)
+  - This module contains a fully-functional example of configuring the OpenTelemetry SDK to use a 
+  logging exporter.
+- [Manually Configuring the SDK](sdk-usage)
+  - This module shows some concrete examples of manually configuring the Java OpenTelemetry SDK for Tracing.
+- [Using the OpenTelemetry metrics API](metrics)
+  - This module contains examples of using the (still experimental) OpenTelemetry metrics APIs.
+- [Setting up the Prometheus exporter](prometheus)
+  - The module shows how to configure the OpenTelemetry SDK to expose an endpoint that can be scraped
+    by Prometheus.
+  - Note: this example uses experimental metrics APIs and SDK.
+- [Manual instrumentation of GRPC](grpc)
+  - This module provides an example of writing manual instrumentation for GRPC, both client and
+    server.
+  - Note that if you want to use more production-ready instrumentation for GRPC, this is provided
+    as a part of the [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) project.

autoconfigure/README.md

@@ -0,0 +1,47 @@
+# 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
+
+## How to run
+
+First build this example application:
+
+```shell
+../gradlew shadowJar
+```
+
+Then start the example application with the logging exporter configured:
+
+```shell
+java -Dotel.traces.exporter=logging \
+  -cp build/libs/opentelemetry-examples-autoconfigure-0.1.0-SNAPSHOT-all.jar \
+  io.opentelemetry.example.autoconfigure.AutoConfigExample
+```
+
+Alternatively, instead of system properties you can use environment variables:
+
+```shell
+export OTEL_TRACES_EXPORTER=logging
+
+java -cp build/libs/opentelemetry-examples-autoconfigure-0.1.0-SNAPSHOT-all.jar \
+  io.opentelemetry.example.autoconfigure.AutoConfigExample
+```
+
+Full documentation of all supported properties can be found in
+the [OpenTelemetry SDK Autoconfigure README](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure).
+
+After running the app you should see the trace printed out in the console:
+
+```
+...
+INFO: 'important work' : ca3938a5793f6f9aba5c757f536a50cb b5e826c981112198 INTERNAL [tracer: io.opentelemetry.example.autoconfigure.AutoConfigExample:] AttributesMap{data={foo=42, bar=a string!}, capacity=128, totalAddedValues=2}
+...
+```
+
+Congratulations! You are now collecting traces using OpenTelemetry.

autoconfigure/build.gradle

@@ -0,0 +1,12 @@
+plugins {
+    id 'java'
+}
+
+description = "OpenTelemetry Examples for SDK autoconfiguration"
+ext.moduleName = "io.opentelemetry.examples.autoconfigure"
+
+dependencies {
+    implementation("io.opentelemetry:opentelemetry-api")
+    implementation("io.opentelemetry:opentelemetry-exporter-logging")
+    implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
+}

autoconfigure/src/main/java/io/opentelemetry/example/autoconfigure/AutoConfigExample.java

@@ -0,0 +1,43 @@
+package io.opentelemetry.example.autoconfigure;
+
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.Tracer;
+import io.opentelemetry.sdk.autoconfigure.OpenTelemetrySdkAutoConfiguration;
+
+/**
+ * An example of using {@link io.opentelemetry.sdk.autoconfigure.OpenTelemetrySdkAutoConfiguration}
+ * and logging exporter: {@link io.opentelemetry.exporter.logging.LoggingSpanExporter}.
+ */
+public final class AutoConfigExample {
+  private static final String INSTRUMENTATION_NAME = AutoConfigExample.class.getName();
+
+  public static void main(String[] args) throws InterruptedException {
+    // Let the SDK configure itself using environment variables and system properties
+    OpenTelemetry openTelemetry = OpenTelemetrySdkAutoConfiguration.initialize();
+
+    AutoConfigExample example = new AutoConfigExample(openTelemetry);
+    // Do some real work that'll emit telemetry
+    example.doWork();
+  }
+
+  private final Tracer tracer;
+
+  public AutoConfigExample(OpenTelemetry openTelemetry) {
+    this.tracer = openTelemetry.getTracer(INSTRUMENTATION_NAME);
+  }
+
+  public void doWork() throws InterruptedException {
+    Span span =
+        tracer
+            .spanBuilder("important work")
+            .setAttribute("foo", 42)
+            .setAttribute("bar", "a string!")
+            .startSpan();
+    try {
+      Thread.sleep(1000);
+    } finally {
+      span.end();
+    }
+  }
+}

build.gradle

@@ -0,0 +1,48 @@
+plugins {
+    id "com.diffplug.spotless"
+    id "com.github.johnrengelman.shadow" apply false
+}
+
+ext {
+  openTelemetryVersion = "1.9.1"
+  openTelemetryAlphaVersion = "1.9.1-alpha"
+
+  grpcVersion = '1.34.1'
+  protobufVersion = '3.11.4'
+  protocVersion = protobufVersion
+}
+
+println("Building against OpenTelemetry version: $openTelemetryVersion")
+
+subprojects {
+    apply plugin: 'eclipse'
+    apply plugin: 'java'
+    apply plugin: 'java-library'
+    apply plugin: 'idea'
+    apply plugin: 'com.diffplug.spotless'
+    apply plugin: 'com.github.johnrengelman.shadow'
+
+    group = "io.opentelemetry"
+    version = "0.1.0-SNAPSHOT"
+
+    repositories {
+        mavenCentral()
+        maven {
+            // Add snapshot repository
+            url "https://oss.sonatype.org/content/repositories/snapshots"
+        }
+    }
+
+    dependencies {
+        implementation platform("io.opentelemetry:opentelemetry-bom:${openTelemetryVersion}")
+        implementation platform("io.opentelemetry:opentelemetry-bom-alpha:${openTelemetryAlphaVersion}")
+        implementation platform("io.grpc:grpc-bom:${grpcVersion}")
+    }
+
+    spotless {
+        java {
+            targetExclude '**/generated/**'
+            googleJavaFormat()
+        }
+    }
+}

gradle.properties

@@ -0,0 +1,13 @@
+org.gradle.parallel=true
+org.gradle.caching=true
+
+org.gradle.priority=low
+
+# Gradle default is 256m which causes issues with our build - https://docs.gradle.org/current/userguide/build_environment.html#sec:configuring_jvm_memory
+# Also workaround https://github.com/diffplug/spotless/issues/834
+org.gradle.jvmargs=-XX:MaxMetaspaceSize=512m \
+  --add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \
+  --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \
+  --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED \
+  --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \
+  --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED \

gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,6 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionSha256Sum=b586e04868a22fd817c8971330fec37e298f3242eb85c374181b12d637f80302
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.3-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists