Maven OpenTelemetry Extension initial commit (#79)

Author: cyrille-leclerc

maven-extension/README.md

@@ -0,0 +1,89 @@
+# Maven OpenTelemetry extension
+
+Maven extension to observe Maven builds as distributed traces.
+
+## Getting Started
+
+The Maven OpenTelemetry Extension is configured using environment variables or JVM system properties and can be added to a build using one of the following ways:
+* adding the extension jar to `${maven.home}/lib/ext`
+* adding the path to the extension jar to`-Dmaven.ext.class.path`,
+* adding the extension as a build extension in the `pom.xml`,
+* (since Maven 3.3.1) configuring the extension in `.mvn/extensions.xml`.
+
+
+### Adding the extension to the classpath
+
+Add the Maven OpenTelemetry Extension to `${maven.home}/lib/ext` or to the classpath using `-Dmaven.ext.class.path=`.
+
+```
+cp /path/to/opentelemetry-java-contrib/maven-extension/build/libs/opentelemetry-maven-extension-1.6.0-SNAPSHOT.jar target/dependency/opentelemetry-maven-extension.jar
+export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
+
+mvn -Dmaven.ext.class.path=target/dependency/opentelemetry-maven-extension.jar verify
+```
+
+### Declaring the extension in the `pom.xml` file
+
+WARNING documentation is invalid until the first release of the io.opentelemetry.contrib:opentelemetry-maven-extension is published on a public Maven repository
+
+Add the Maven OpenTelemetry Extension in the `pom.xml` file:
+
+```xml
+<project>
+  ...
+  <build>
+    <extensions>
+      <extension>
+          <groupId>io.opentelemetry.contrib</groupId>
+          <artifactId>opentelemetry-maven-extension</artifactId>
+          <version>1.6.0-SNAPSHOT</version>
+      </extension>
+    </extensions>
+  </build>
+</project>
+```
+
+```
+export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
+
+mvn verify
+```
+
+## Configuration
+
+The Maven OpenTelemetry Extension supports a subset of the [OpenTelemetry auto configuration environment variables and JVM system properties](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure).
+
+| System property              | Environment variable        | Description                                                               |
+|------------------------------|-----------------------------|---------------------------------------------------------------------------|
+| otel.exporter.otlp.endpoint  | OTEL_EXPORTER_OTLP_ENDPOINT | The OTLP traces and metrics endpoint to connect to. Must be a URL with a scheme of either `http` or `https` based on the use of TLS. Example `http://localhost:4317`.            |
+| otel.exporter.otlp.headers   | OTEL_EXPORTER_OTLP_HEADERS  | Key-value pairs separated by commas to pass as request headers on OTLP trace and metrics requests.        |
+| otel.exporter.otlp.timeout   | OTEL_EXPORTER_OTLP_TIMEOUT  | The maximum waiting time, in milliseconds, allowed to send each OTLP trace and metric batch. Default is `10000`.  |
+| otel.resource.attributes | OTEL_RESOURCE_ATTRIBUTES | Specify resource attributes in the following format: key1=val1,key2=val2,key3=val3 |
+
+
+ℹ️ The `service.name` is set by default to `maven`, it can be overwritten specifying resource atributes.
+
+
+## Examples
+
+Example of a trace of a Maven build.
+
+![](https://raw.githubusercontent.com/cyrille-leclerc/opentelemetry-java-contrib/add-maven-extension-v2/maven-extension/docs/images/maven-execution-trace-jaeger.png)
+
+## Example of a distributed trace of a Jenkins pipeline executing a Maven build
+
+Distributed trace of a Jenkins pipeline invoking a Maven build instrumented with the  [Jenkins OpenTelemetry plugin](https://plugins.jenkins.io/opentelemetry/) and the OpenTelemetry Maven Extension and visualized with [Jaeger Tracing](https://www.jaegertracing.io/)
+
+![](https://raw.githubusercontent.com/cyrille-leclerc/opentelemetry-java-contrib/add-maven-extension-v2/maven-extension/docs/images/jenkins-maven-execution-trace-jaeger.png)
+
+# Other CI/CD Tools supporting OpenTelemetry traces
+
+List of other CI/CD tools that support OpenTelemetry traces and integrate with the Maven OpenTelemetry Extension creating a distributed traces providing end to end visibility.
+
+## Jenkins OpenTelemetry Plugin
+
+The [Jenkins OpenTelemetry Plugin](https://plugins.jenkins.io/opentelemetry/) exposes Jenkins pipelines & jobs as OpenTelemetry traces and exposes Jenkins health indicators as OpenTelemetry metrics.
+
+## Otel CLI
+
+The [`otel-cli`](https://github.com/equinix-labs/otel-cli) is a command line wrapper to observe the execution of a shell command as an OpenTelemetry trace.

maven-extension/build.gradle.kts

@@ -0,0 +1,47 @@
+plugins {
+  id("java")
+  id("com.github.johnrengelman.shadow")
+  id("otel.java-conventions")
+  id("otel.publish-conventions")
+}
+
+// NOTE
+// `META-INF/plexus/components.xml` is manually handled under src/main/resources because there is no Gradle
+// equivalent to the Maven plugin `plexus-component-metadata:generate-metadata`
+
+description = "Maven extension to observe Maven builds with distributed traces using OpenTelemetry SDK"
+
+dependencies {
+  implementation("org.codehaus.plexus:plexus-component-annotations:2.1.0")
+
+  implementation("io.opentelemetry:opentelemetry-api")
+  implementation("io.opentelemetry:opentelemetry-sdk")
+  implementation("io.opentelemetry:opentelemetry-sdk-trace")
+  implementation("io.opentelemetry:opentelemetry-semconv")
+  implementation("io.opentelemetry:opentelemetry-exporter-otlp")
+  implementation("io.opentelemetry:opentelemetry-exporter-otlp-trace")
+
+  implementation("io.grpc:grpc-netty-shaded")
+
+  annotationProcessor("com.google.auto.value:auto-value")
+  compileOnly("com.google.auto.value:auto-value-annotations")
+  
+  compileOnly("org.apache.maven:maven-core:3.5.0")
+  compileOnly("org.slf4j:slf4j-api")
+  compileOnly("org.sonatype.aether:aether-api:1.13.1")
+
+
+  testImplementation("org.apache.maven:maven-core:3.5.0")
+  testImplementation("org.slf4j:slf4j-simple")
+}
+
+tasks {
+  shadowJar {
+    archiveClassifier.set("")
+  }
+
+  assemble {
+    dependsOn(shadowJar)
+  }
+}
+

maven-extension/docs/images/jenkins-maven-execution-trace-jaeger.png

@@ -0,0 +1,146 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package io.opentelemetry.maven;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.stream.Collectors;
+import org.apache.maven.execution.ExecutionEvent;
+import org.apache.maven.execution.ExecutionListener;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Util class to chain multiple {@link ExecutionListener} as Maven APIs don't offer this capability.
+ */
+final class ChainedExecutionListener implements ExecutionListener {
+  private final Logger logger = LoggerFactory.getLogger(getClass());
+
+  private final List<ExecutionListener> listeners;
+
+  /** @param listeners {@code null} values are filtered */
+  ChainedExecutionListener(ExecutionListener... listeners) {
+    this.listeners = Arrays.stream(listeners).filter(e -> e != null).collect(Collectors.toList());
+  }
+
+  @Override
+  public void projectDiscoveryStarted(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.projectDiscoveryStarted(event);
+    }
+  }
+
+  @Override
+  public void sessionStarted(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.sessionStarted(event);
+    }
+  }
+
+  @Override
+  public void sessionEnded(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.sessionEnded(event);
+    }
+  }
+
+  @Override
+  public void projectSkipped(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.projectSkipped(event);
+    }
+  }
+
+  @Override
+  public void projectStarted(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.projectStarted(event);
+    }
+  }
+
+  @Override
+  public void projectSucceeded(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.projectSucceeded(event);
+    }
+  }
+
+  @Override
+  public void projectFailed(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.projectFailed(event);
+    }
+  }
+
+  @Override
+  public void mojoSkipped(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.mojoSkipped(event);
+    }
+  }
+
+  @Override
+  public void mojoStarted(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.mojoStarted(event);
+    }
+  }
+
+  @Override
+  public void mojoSucceeded(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.mojoSucceeded(event);
+    }
+  }
+
+  @Override
+  public void mojoFailed(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.mojoFailed(event);
+    }
+  }
+
+  @Override
+  public void forkStarted(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.forkStarted(event);
+    }
+  }
+
+  @Override
+  public void forkSucceeded(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.forkSucceeded(event);
+    }
+  }
+
+  @Override
+  public void forkFailed(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.forkFailed(event);
+    }
+  }
+
+  @Override
+  public void forkedProjectStarted(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.forkedProjectStarted(event);
+    }
+  }
+
+  @Override
+  public void forkedProjectSucceeded(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.forkedProjectSucceeded(event);
+    }
+  }
+
+  @Override
+  public void forkedProjectFailed(ExecutionEvent event) {
+    for (ExecutionListener listener : this.listeners) {
+      listener.forkedProjectFailed(event);
+    }
+  }
+}