Minimal extension example (#886)

Author: jaydeluca

.github/scripts/run-oats-tests.sh

@@ -10,6 +10,8 @@ pushd javaagent-declarative-configuration
 ../gradlew bootJar
 popd
 
+./gradlew :doc-snippets:extensions-testapp:jar :doc-snippets:extensions-minimal:shadowJar
+
 # renovate: datasource=github-releases depName=k3d-io/k3d
 K3D_VERSION=v5.8.3
 wget -q -O - https://raw.githubusercontent.com/k3d-io/k3d/${K3D_VERSION}/install.sh | TAG=${K3D_VERSION} bash
@@ -19,3 +21,4 @@ OATS_VERSION=v0.4.1
 go install github.com/grafana/oats@${OATS_VERSION}
 oats -timeout 5m logging-k8s-stdout-otlp-json/
 oats -timeout 5m javaagent-declarative-configuration/oats/
+oats -timeout 5m doc-snippets/extensions-minimal/oats/

.github/workflows/oats-tests.yml

@@ -7,7 +7,8 @@ on:
     paths:
       - .github/workflows/oats-tests.yml
       - 'logging-k8s-stdout-otlp-json/**'
-      - 'javaagent-declarative-configuration/oats/**'
+      - 'javaagent-declarative-configuration/**'
+      - 'doc-snippets/extensions-minimal/**'
   workflow_dispatch:
 
 permissions:

doc-snippets/extensions-minimal/README.md

@@ -0,0 +1,45 @@
+# Extensions - Minimal example
+
+This code is used on the documentation site to demonstrate a "quick start" minimal example that someone can use
+as a starting point when writing a new extension. The functionality is that it configures a SpanProcessor to add
+a custom attribute "custom.processor:active" to the spans.
+
+**NOTE:** This code is used for populating code examples on opentelemetry.io, so please ensure that any changes
+maintain the clarity and simplicity of the example and are synced correctly with the documentation site.
+
+## Building
+
+To build the extension JAR:
+
+```bash
+cd /path/to/opentelemetry-java-examples
+./gradlew :doc-snippets:extensions-minimal:shadowJar
+```
+
+The output JAR will be at: `build/libs/extensions-minimal-0.1.0-SNAPSHOT-all.jar`
+
+## Testing
+
+This module includes OATS (OpenTelemetry Acceptance Tests) to verify the extension works correctly.
+
+### Prerequisites
+
+Install OATS:
+```bash
+go install github.com/grafana/oats@latest
+```
+
+Build both the extension and the test application:
+```bash
+cd /path/to/opentelemetry-java-examples
+./gradlew :doc-snippets:extensions-testapp:jar :doc-snippets:extensions-minimal:shadowJar
+```
+
+### Run the tests
+
+```bash
+cd doc-snippets/extensions-minimal
+oats oats/oats.yaml
+```
+
+The test will verify that the custom `custom.processor: "active"` attribute is added to all spans.

doc-snippets/extensions-minimal/build.gradle.kts

@@ -0,0 +1,26 @@
+plugins {
+    id("java")
+    id("com.gradleup.shadow")
+}
+
+dependencies {
+    // Use BOM to manage OpenTelemetry dependency versions
+    compileOnly(platform("io.opentelemetry:opentelemetry-bom:1.56.0"))
+
+    // OpenTelemetry SDK autoconfiguration SPI (provided by agent)
+    compileOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure-spi")
+
+    // OpenTelemetry SDK (needed for SpanProcessor and trace classes)
+    compileOnly("io.opentelemetry:opentelemetry-sdk")
+
+    // Annotation processor for automatic SPI registration
+    compileOnly("com.google.auto.service:auto-service:1.1.1")
+    annotationProcessor("com.google.auto.service:auto-service:1.1.1")
+
+    // Add any external dependencies with 'implementation' scope
+    // implementation("org.apache.commons:commons-lang3:3.19.0")
+}
+
+tasks.assemble {
+    dependsOn(tasks.shadowJar)
+}

doc-snippets/extensions-minimal/oats/Dockerfile

@@ -0,0 +1,22 @@
+FROM eclipse-temurin:21.0.9_10-jre@sha256:bbcd43c7120c41cc5c9fc844b4403e6865a6f911fec1624ff5dda6f9118cc115
+
+WORKDIR /usr/src/app/
+
+# renovate: datasource=github-releases depName=opentelemetry-java-instrumentation packageName=open-telemetry/opentelemetry-java-instrumentation
+ENV OPENTELEMETRY_JAVA_INSTRUMENTATION_VERSION=v2.21.0
+
+# Add the test application JAR
+ADD ./extensions-testapp/build/libs/extensions-testapp-1.0-SNAPSHOT.jar ./app.jar
+
+# Add the custom extension JAR
+ADD ./extensions-minimal/build/libs/extensions-minimal-0.1.0-SNAPSHOT-all.jar ./extensions/
+
+# Download the OpenTelemetry Java agent
+ADD --chmod=644 https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/$OPENTELEMETRY_JAVA_INSTRUMENTATION_VERSION/opentelemetry-javaagent.jar ./opentelemetry-javaagent.jar
+
+# Configure the Java agent with the custom extension
+ENV JAVA_TOOL_OPTIONS=-javaagent:./opentelemetry-javaagent.jar
+ENV OTEL_JAVAAGENT_EXTENSIONS=./extensions/extensions-minimal-0.1.0-SNAPSHOT-all.jar
+
+EXPOSE 8080
+ENTRYPOINT [ "java", "-jar", "./app.jar" ]

doc-snippets/extensions-minimal/oats/docker-compose.yml

@@ -0,0 +1,13 @@
+version: '3'
+services:
+  app:
+    build:
+      context: ../../
+      dockerfile: extensions-minimal/oats/Dockerfile
+    environment:
+      OTEL_SERVICE_NAME: "extensions-minimal-test-app"
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://lgtm:4318
+      OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: http://lgtm:4318/v1/traces
+      OTEL_EXPORTER_OTLP_PROTOCOL: http/protobuf
+    ports:
+      - "8080:8080"

doc-snippets/extensions-minimal/oats/oats.yaml

@@ -0,0 +1,23 @@
+# OATS is an acceptance testing framework for OpenTelemetry - https://github.com/grafana/oats
+
+docker-compose:
+  files:
+    - ./docker-compose.yml
+  app-service: app
+  app-docker-tag: extensions-minimal:latest
+  app-docker-port: 8080
+
+input:
+  - path: /hello
+    interval: 5000ms
+
+expected:
+  traces:
+    - traceql: '{ span.http.route = "/hello" }'
+      spans:
+        - name: "GET /hello"
+          attributes:
+            http.request.method: "GET"
+            http.route: "/hello"
+            # This custom attribute is added by MySpanProcessor
+            custom.processor: "active"

doc-snippets/extensions-minimal/src/main/java/otel/MyExtensionProvider.java

@@ -0,0 +1,24 @@
+package otel;
+
+import com.google.auto.service.AutoService;
+import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizer;
+import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider;
+import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
+import io.opentelemetry.sdk.trace.SdkTracerProviderBuilder;
+import io.opentelemetry.sdk.trace.SpanLimits;
+
+@AutoService(AutoConfigurationCustomizerProvider.class)
+public class MyExtensionProvider implements AutoConfigurationCustomizerProvider {
+
+  @Override
+  public void customize(AutoConfigurationCustomizer config) {
+    config.addTracerProviderCustomizer(this::configureTracer);
+  }
+
+  private SdkTracerProviderBuilder configureTracer(
+      SdkTracerProviderBuilder tracerProvider, ConfigProperties config) {
+    return tracerProvider
+        .setSpanLimits(SpanLimits.builder().setMaxNumberOfAttributes(1024).build())
+        .addSpanProcessor(new MySpanProcessor());
+  }
+}

doc-snippets/extensions-minimal/src/main/java/otel/MySpanProcessor.java

@@ -0,0 +1,36 @@
+package otel;
+
+import io.opentelemetry.context.Context;
+import io.opentelemetry.sdk.common.CompletableResultCode;
+import io.opentelemetry.sdk.trace.ReadWriteSpan;
+import io.opentelemetry.sdk.trace.ReadableSpan;
+import io.opentelemetry.sdk.trace.SpanProcessor;
+
+public class MySpanProcessor implements SpanProcessor {
+
+  @Override
+  public void onStart(Context parentContext, ReadWriteSpan span) {
+    // Add custom attributes when span starts
+    span.setAttribute("custom.processor", "active");
+  }
+
+  @Override
+  public boolean isStartRequired() {
+    return true;
+  }
+
+  @Override
+  public void onEnd(ReadableSpan span) {
+    // Process span when it ends (optional)
+  }
+
+  @Override
+  public boolean isEndRequired() {
+    return false;
+  }
+
+  @Override
+  public CompletableResultCode shutdown() {
+    return CompletableResultCode.ofSuccess();
+  }
+}

doc-snippets/extensions-testapp/README.md

@@ -0,0 +1,37 @@
+# Extensions - Test Application
+
+This is a simple HTTP server application used for testing OpenTelemetry Java agent extensions. It provides one endpoint:
+
+- `GET /hello` - Returns a simple greeting
+
+## Building
+
+To build the application JAR:
+
+```bash
+cd /path/to/opentelemetry-java-examples
+./gradlew :doc-snippets:extensions-testapp:jar
+```
+
+The output JAR will be at: `build/libs/extensions-testapp-1.0-SNAPSHOT.jar`
+
+## Running
+
+To run the application with the OpenTelemetry Java agent:
+
+```bash
+java -javaagent:path/to/opentelemetry-javaagent.jar \
+     -Dotel.service.name=test-app \
+     -jar build/libs/extensions-testapp-1.0-SNAPSHOT.jar
+```
+
+The server will start on port 8080. You can test it with:
+
+```bash
+curl http://localhost:8080/hello
+```
+
+## Usage with Extensions
+
+This application is designed to be used with the extensions-minimal module to test custom OpenTelemetry extensions.
+See the extensions-minimal readme for details on running OATS tests.