Help the user to manage the OpenTelemetry version in Spring Monitor (Azure#36610)

Author: jeanbisutti

eng/code-quality-reports/src/main/resources/checkstyle/checkstyle-suppressions.xml

@@ -429,6 +429,9 @@ the main ServiceBusClientBuilder. -->
   <!-- GoodLoggingCheck: Spring as a framework, will not directly use ClientLogger-->
   <suppress checks="com.azure.tools.checkstyle.checks.(GoodLoggingCheck|ThrowFromClientLoggerCheck|UseCaughtExceptionCauseCheck)" files=".*[/\\]com[/\\]azure[/\\]spring[/\\].*"/>
 
+  <!-- Can be removed after https://github.com/Azure/azure-sdk-for-java/issues/36609 -->
+  <suppress checks="com.azure.tools.checkstyle.checks.(GoodLoggingCheck|ThrowFromClientLoggerCheck|UseCaughtExceptionCauseCheck)" files="com.azure.monitor.applicationinsights.spring.OpenTelemetryVersionCheckRunner.java"/>
+
   <!-- ExternalDependencyExposedCheck: Spring will directly use classes from spring dependencies in methods-->
   <suppress checks="com.azure.tools.checkstyle.checks.ExternalDependencyExposedCheck" files=".*[/\\]com[/\\]azure[/\\]spring[/\\].*"/>
 

sdk/spring/spring-cloud-azure-starter-monitor-test/src/test/java/com/azure/SpringMonitorTest.java

@@ -4,16 +4,16 @@
 
 import static java.util.concurrent.TimeUnit.SECONDS;
 import static org.assertj.core.api.Assertions.*;
-import static org.assertj.core.api.Assertions.assertThat;
 
 import com.azure.core.http.*;
 import com.azure.core.http.policy.HttpPipelinePolicy;
+import com.azure.monitor.applicationinsights.spring.OpenTelemetryVersionCheckRunner;
 import com.azure.monitor.opentelemetry.exporter.implementation.models.*;
 import io.opentelemetry.sdk.logs.export.LogRecordExporter;
 import io.opentelemetry.sdk.metrics.export.MetricExporter;
+import io.opentelemetry.sdk.resources.Resource;
 import io.opentelemetry.sdk.trace.export.SpanExporter;
-
-import java.io.InputStream;
+import io.opentelemetry.semconv.resource.attributes.ResourceAttributes;
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.util.List;
@@ -43,13 +43,15 @@ public class SpringMonitorTest {
   @Autowired private TestRestTemplate restTemplate;
 
   // See io.opentelemetry.instrumentation.spring.autoconfigure.OpenTelemetryAutoConfiguration
-  @Autowired ObjectProvider<List<SpanExporter>> otelSpanExportersProvider;
+  @Autowired private ObjectProvider<List<SpanExporter>> otelSpanExportersProvider;
 
   // See io.opentelemetry.instrumentation.spring.autoconfigure.OpenTelemetryAutoConfiguration
-  @Autowired ObjectProvider<List<LogRecordExporter>> otelLoggerExportersProvider;
+  @Autowired private ObjectProvider<List<LogRecordExporter>> otelLoggerExportersProvider;
 
   // See io.opentelemetry.instrumentation.spring.autoconfigure.OpenTelemetryAutoConfiguration
-  @Autowired ObjectProvider<List<MetricExporter>> otelMetricExportersProvider;
+  @Autowired private ObjectProvider<List<MetricExporter>> otelMetricExportersProvider;
+
+  @Autowired private Resource otelResource;
 
   @Configuration(proxyBeanMethods = false)
   static class TestConfiguration {
@@ -166,4 +168,15 @@ public void shouldMonitor() throws InterruptedException, MalformedURLException {
     assertThat(requestData.getResponseCode()).isEqualTo("200");
     assertThat(requestData.getName()).isEqualTo("GET /controller-url");
   }
+
+  @Test
+  public void verifyOpenTelemetryVersion() {
+    String currentOTelVersion = otelResource.getAttribute(ResourceAttributes.TELEMETRY_SDK_VERSION);
+    assertThat(OpenTelemetryVersionCheckRunner.STARTER_OTEL_VERSION)
+        .as(
+            "Dear developer, You may have updated the OpenTelemetry dependencies of spring-cloud-azure-starter-monitor without updating the OTel starter version declared in "
+                + OpenTelemetryVersionCheckRunner.class
+                + ".")
+        .isEqualTo(currentOTelVersion);
+  }
 }

sdk/spring/spring-cloud-azure-starter-monitor/README.md

@@ -27,7 +27,47 @@ For more information, please read [introduction to Application Insights][applica
 ```
 [//]: # ({x-version-update-end})
 
-This dependency is a Spring Boot starter that provides telemetry data for HTTP requests.
+You may have to align the OpenTelemetry versions of Spring Boot 3 and `spring-cloud-azure-starter-monitor`. If this is the case, you will notice a WARN message during the application start-up:
+```
+WARN  c.a.m.a.s.OpenTelemetryVersionCheckRunner - The OpenTelemetry version is not compatible with the spring-cloud-azure-starter-monitor dependency. The OpenTelemetry version should be
+```
+To fix this with Maven, you can set the `opentelemetry.version` property:
+
+```xml
+<properties>
+   <opentelemetry.version>{otel-version-given-in-the-warn-log}</opentelemetry.version>
+</properties>
+```
+
+Another way is to declare the `opentelemetry-bom` BOM:
+
+```xml
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-bom</artifactId>
+            <version>{otel-version-given-in-the-warn-log}</version>
+            <type>pom</type>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+```
+
+With Gradle, you can fix the issue in this way:
+
+```
+plugins {
+    id 'org.springframework.boot'
+    id 'io.spring.dependency-management'
+}
+
+dependencyManagement {
+    imports {
+        mavenBom 'io.opentelemetry:opentelemetry-bom:{otel-version-given-in-the-warn-log}'
+    }
+}
+```
 
 ### Authentication
 

sdk/spring/spring-cloud-azure-starter-monitor/pom.xml

@@ -57,20 +57,47 @@
       <artifactId>opentelemetry-runtime-telemetry-java8</artifactId>
       <version>1.28.0-alpha</version> <!-- {x-version-update;io.opentelemetry.instrumentation:opentelemetry-runtime-telemetry-java8;external_dependency} -->
     </dependency>
+    <dependency>
+      <groupId>io.opentelemetry</groupId>
+      <artifactId>opentelemetry-api-logs</artifactId>
+      <version>1.26.0-alpha</version> <!-- {x-version-update;io.opentelemetry:opentelemetry-api-logs;external_dependency} -->
+      <scope>compile</scope>
+    </dependency>
     <!-- End of OTel dependencies -->
 
     <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-monitor-opentelemetry-exporter</artifactId>
       <version>1.0.0-beta.11</version> <!-- {x-version-update;com.azure:azure-monitor-opentelemetry-exporter;dependency} -->
     </dependency>
+
+    <!-- Test dependencies -->
     <dependency>
-      <groupId>io.opentelemetry</groupId>
-      <artifactId>opentelemetry-api-logs</artifactId>
-      <version>1.26.0-alpha</version> <!-- {x-version-update;io.opentelemetry:opentelemetry-api-logs;external_dependency} -->
-      <scope>compile</scope>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-api</artifactId>
+      <version>5.9.3</version> <!-- {x-version-update;org.junit.jupiter:junit-jupiter-api;external_dependency} -->
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <version>5.9.3</version> <!-- {x-version-update;org.junit.jupiter:junit-jupiter-engine;external_dependency} -->
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.assertj</groupId>
+      <artifactId>assertj-core</artifactId>
+      <version>3.22.0</version>  <!-- {x-version-update;org.assertj:assertj-core;external_dependency} -->
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-test</artifactId>
+      <version>2.7.14</version> <!-- {x-version-update;org.springframework.boot:spring-boot-starter-test;external_dependency} -->
+      <scope>test</scope>
     </dependency>
 
+    <!-- End of test dependencies -->
 
   </dependencies>
 

sdk/spring/spring-cloud-azure-starter-monitor/src/main/java/com/azure/monitor/applicationinsights/spring/OTelVersion.java

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.azure.monitor.applicationinsights.spring;
+
+class OTelVersion {
+
+    private final String otelVersionAsString;
+    private final int majorVersion;
+    private final int minorVersion;
+    private final int patchVersion;
+
+    OTelVersion(String otelVersionAsString) {
+        this.otelVersionAsString = otelVersionAsString;
+        String[] versionComponents = otelVersionAsString.split("\\.");
+        this.majorVersion = Integer.parseInt(versionComponents[0]);
+        this.minorVersion = Integer.parseInt(versionComponents[1]);
+        this.patchVersion = Integer.parseInt(versionComponents[2]);
+    }
+
+    boolean isLessThan(OTelVersion oTelVersion) {
+        if (this.otelVersionAsString.equals(oTelVersion.otelVersionAsString)) {
+            return false;
+        }
+        return !isGreaterThan(oTelVersion);
+    }
+
+    boolean isGreaterThan(OTelVersion oTelVersion) {
+        if (this.otelVersionAsString.equals(oTelVersion.otelVersionAsString)) {
+            return false;
+        }
+        if (this.majorVersion > oTelVersion.majorVersion) {
+            return true;
+        }
+        if (this.minorVersion > oTelVersion.minorVersion) {
+            return true;
+        }
+        if (this.patchVersion > oTelVersion.patchVersion) {
+            return true;
+        }
+        return false;
+    }
+
+    boolean hasSameMajorVersionAs(OTelVersion oTelVersion) {
+        return this.majorVersion == oTelVersion.majorVersion;
+    }
+
+}

sdk/spring/spring-cloud-azure-starter-monitor/src/main/java/com/azure/monitor/applicationinsights/spring/OpenTelemetryVersionCheckRunner.java

@@ -0,0 +1,69 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.azure.monitor.applicationinsights.spring;
+
+import io.opentelemetry.sdk.resources.Resource;
+import io.opentelemetry.semconv.resource.attributes.ResourceAttributes;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.stereotype.Component;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * This component alerts the user to the fact that the OpenTelemetry version used is not compatible
+ * with the starter. One use case is Spring Boot 3 using OpenTelemetry.
+ */
+@Component
+public class OpenTelemetryVersionCheckRunner implements CommandLineRunner {
+    private static final Logger LOG = LoggerFactory.getLogger(OpenTelemetryVersionCheckRunner.class);
+
+    // If this version is not up-to-date, a test will fail.
+    /**
+     * OpenTelemetry version of the starter
+     */
+    public static final String STARTER_OTEL_VERSION = "1.28.0";
+
+    private final Resource otelResource;
+
+    /**
+     * Component to check the OpenTelemetry version.
+     *
+     * @param otelResource OpenTelemetry resource
+     */
+    public OpenTelemetryVersionCheckRunner(Resource otelResource) {
+        this.otelResource = otelResource;
+    }
+
+    /**
+     * To verify the OpenTelemetry version at the application start-up.
+     *
+     * @param args args
+     */
+    @Override
+    public void run(String... args) {
+        try {
+            String currentOTelVersionAsString = otelResource.getAttribute(ResourceAttributes.TELEMETRY_SDK_VERSION);
+            OTelVersion currentOtelVersion = new OTelVersion(currentOTelVersionAsString);
+            OTelVersion starterOTelVersion = new OTelVersion(STARTER_OTEL_VERSION);
+            checkOpenTelemetryVersion(currentOtelVersion, starterOTelVersion);
+        } catch (Exception e) {
+            LOG.warn(
+                "An unexpected issue has happened during the verification of the OpenTelemetry version.",
+                e);
+        }
+    }
+
+    private static void checkOpenTelemetryVersion(
+        OTelVersion currentOTelVersion, OTelVersion starterOTelVersion) {
+        if (!currentOTelVersion.hasSameMajorVersionAs(starterOTelVersion) && currentOTelVersion.isLessThan(starterOTelVersion)) {
+            LOG.warn(
+                "The OpenTelemetry version is not compatible with the spring-cloud-azure-starter-monitor dependency. The OpenTelemetry version should be "
+                    + STARTER_OTEL_VERSION
+                    + ". "
+                    + "Please look at the spring-cloud-azure-starter-monitor documentation to fix this.");
+        } else if (currentOTelVersion.isGreaterThan(starterOTelVersion)) {
+            LOG.info(
+                "A new version of spring-cloud-azure-starter-monitor dependency may be available.");
+        }
+    }
+}

sdk/spring/spring-cloud-azure-starter-monitor/src/main/resources/META-INF/native-image/reflect-config.json

@@ -1,28 +1,4 @@
 [
-  {
-    "name": "io.opentelemetry.internal.shaded.jctools.queues.MpscArrayQueueConsumerIndexField",
-    "fields": [
-      {
-        "name": "consumerIndex"
-      }
-    ]
-  },
-  {
-    "name": "io.opentelemetry.internal.shaded.jctools.queues.MpscArrayQueueProducerIndexField",
-    "fields": [
-      {
-        "name": "producerIndex"
-      }
-    ]
-  },
-  {
-    "name": "io.opentelemetry.internal.shaded.jctools.queues.MpscArrayQueueProducerLimitField",
-    "fields": [
-      {
-        "name": "producerLimit"
-      }
-    ]
-  },
   {
     "name": "io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender",
     "allDeclaredMethods": true,

sdk/spring/spring-cloud-azure-starter-monitor/src/test/java/com/azure/monitor/applicationinsights/spring/OTelVersionTest.java

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.azure.monitor.applicationinsights.spring;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class OTelVersionTest {
+
+    @Test
+    void lessThanWithSameVersions() {
+        assertThat(new OTelVersion("1.28.0").isLessThan(new OTelVersion("1.28.0"))).isFalse();
+    }
+
+    @Test
+    void lessThanWithSameMajorVersions() {
+        assertThat(new OTelVersion("1.27.0").isLessThan(new OTelVersion("1.28.0"))).isTrue();
+    }
+
+    @Test
+    void lessThanWithSameMajorAndMinorVersions() {
+        assertThat(new OTelVersion("1.28.0").isLessThan(new OTelVersion("1.28.1"))).isTrue();
+    }
+
+    @Test
+    void lessThanWithDifferentMajorVersions() {
+        assertThat(new OTelVersion("1.27.0").isLessThan(new OTelVersion("2.28.0"))).isTrue();
+    }
+
+    @Test
+    void greaterThanWithSameVersions() {
+        assertThat(new OTelVersion("1.28.0").isGreaterThan(new OTelVersion("1.28.0"))).isFalse();
+    }
+
+    @Test
+    void greaterThanWithSameMajorVersions() {
+        assertThat(new OTelVersion("1.28.0").isGreaterThan(new OTelVersion("1.27.0"))).isTrue();
+    }
+
+    @Test
+    void greaterThanWithSameMajorAndMinorVersions() {
+        assertThat(new OTelVersion("1.28.1").isGreaterThan(new OTelVersion("1.28.0"))).isTrue();
+    }
+
+    @Test
+    void greaterThanWithDifferentMajorVersions() {
+        assertThat(new OTelVersion("2.28.0").isGreaterThan(new OTelVersion("1.28.0"))).isTrue();
+    }
+
+
+}

sdk/spring/spring-cloud-azure-starter-monitor/src/test/java/com/azure/monitor/applicationinsights/spring/SpringContextTest.java

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+package com.azure.monitor.applicationinsights.spring;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.AutoConfigurations;
+import org.springframework.boot.test.context.runner.ApplicationContextRunner;
+
+public class SpringContextTest {
+
+    private final ApplicationContextRunner contextRunner = new ApplicationContextRunner();
+
+    // The tests of the Spring Monitor features are done in the spring-cloud-azure-starter-monitor-test Maven module
+    @Test
+    void loadContext() {
+        this.contextRunner.withConfiguration(AutoConfigurations.of(AzureSpringMonitorAutoConfig.class)).run(context -> {
+        });
+    }
+
+}