Allow developer to choose whether Helidon injects OTel types which notify span listeners

docs/src/main/asciidoc/mp/telemetry.adoc

@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2023, 2024 Oracle and/or its affiliates.
+    Copyright (c) 2023, 2025 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -204,6 +204,15 @@ include::{sourcedir}/mp/TelemetrySnippets.java[tag=snippet_6, indent=0]
 
 include::{rootdir}/includes/tracing/common-callbacks.adoc[tags=defs;detailed,leveloffset=+1]
 
+==== Using Span Listeners with Injection
+By default, Helidon _does not_ notify registered span listeners of life cycle events that involve an injected OpenTelemetry `Tracer` or `Span`.
+
+To enable this notification for injected telemetry objects configure `telemetry.injection-type` to `neutral` (overriding the default of `native`). See the <<Configuration,Configuration>> section for more information. Helidon then injects wrappers around the OpenTelemetry native objects instead of the OpenTelemetry native objects themselves. The wrappers notify registered listeners of life cycle changes.
+
+Note that although the injected neutral objects implement the corresponding OpenTelemetry interfaces, they _are not_ type-compatible with the underlying OpenTelemetry implementation types, so code that uses `instanceof` or other type-sensitive logic that refers to OpenTelemetry implementation types will not work. The injected neutral objects implement the
+link:{tracing-javadoc-base-url}/io/helidon/tracing/Wrapper.html[`io.helidon.tracing.Wrapper` interface]
+which declares the `unwrap` method. You can check and cast an injected neutral object to `Wrapper` and invokes its `unwrap` method to get access to the underlying OpenTelemetry object.
+
 === Controlling Automatic Span Creation
 By default, Helidon MP Telemetry creates a new child span for each incoming REST request and for each outgoing REST client request. You can selectively control if Helidon creates these automatic spans on a request-by-request basis by adding a very small amount of code to your project.
 
@@ -262,6 +271,12 @@ The OpenTelemetry Java Agent may influence the work of MicroProfile Telemetry, o
 
 This way, Helidon will explicitly get all the configuration and objects from the Agent, thus allowing correct span hierarchy settings.
 
+=== Helidon Telemetry Configuration
+
+include::{rootdir}/config/io_helidon_microprofile_telemetry_TelemetryConfig.adoc[leveloffset=+1,tag=config]
+
+The <<Using Span Listeners with Injection, Using Span Listeners with Injection>> section describes the effect of this configuration.
+
 [[examples]]
 == Examples
 

microprofile/telemetry/etc/spotbugs/exclude.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
-    Copyright (c) 2024 Oracle and/or its affiliates.
+    Copyright (c) 2024, 2025 Oracle and/or its affiliates.
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
@@ -28,4 +28,9 @@
         <Method name="&lt;init&gt;"/>
         <Bug pattern = "VA_FORMAT_STRING_USES_NEWLINE"/>
     </Match>
+    <Match>
+        <!-- False positives in multiple methods - see https://github.com/spotbugs/spotbugs/issues/3235 -->
+        <Class name="io.helidon.microprofile.telemetry.WrappedProducer$WrappedSpanBuilder"/>
+        <Bug pattern = "RV_RETURN_VALUE_IGNORED_NO_SIDE_EFFECT"/>
+    </Match>
 </FindBugsFilter>

microprofile/telemetry/pom.xml

@@ -135,19 +135,55 @@
                             <artifactId>helidon-common-features-processor</artifactId>
                             <version>${helidon.version}</version>
                         </path>
+                        <path>
+                            <!-- Codegen integration with Java annotation processing -->
+                            <groupId>io.helidon.codegen</groupId>
+                            <artifactId>helidon-codegen-apt</artifactId>
+                            <version>${helidon.version}</version>
+                        </path>
+                        <path>
+                            <groupId>io.helidon.builder</groupId>
+                            <artifactId>helidon-builder-codegen</artifactId>
+                            <version>${helidon.version}</version>
+                        </path>
+                        <path>
+                            <!-- Config metadata codegen (to generate META-INF/helidon/config-metadata.json) -->
+                            <groupId>io.helidon.config.metadata</groupId>
+                            <artifactId>helidon-config-metadata-codegen</artifactId>
+                            <version>${helidon.version}</version>
+                        </path>
                     </annotationProcessorPaths>
                 </configuration>
             </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <systemPropertyVariables>
+                        <otel.bsp.schedule.delay>${otel.bsp.schedule.delay}</otel.bsp.schedule.delay>
+                    </systemPropertyVariables>
+                </configuration>
                 <executions>
                     <execution>
                         <id>default-test</id>
                         <configuration>
-                            <systemPropertyVariables>
-                                <otel.bsp.schedule.delay>${otel.bsp.schedule.delay}</otel.bsp.schedule.delay>
-                            </systemPropertyVariables>
+                            <excludes>
+                                <exclude>**/TestListenersWithInjection.java</exclude>
+                            </excludes>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <!--
+                            Run separately so other tests do not interfere with the static information about the global tracer.
+                        -->
+                        <id>test-listeners-with-injection</id>
+                        <goals>
+                            <goal>test</goal>
+                        </goals>
+                        <configuration>
+                            <includes>
+                                <include>**/TestListenersWithInjection.java</include>
+                            </includes>
                         </configuration>
                     </execution>
                 </executions>

microprofile/telemetry/src/main/java/io/helidon/microprofile/telemetry/InjectionType.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.helidon.microprofile.telemetry;
+
+/**
+ * Choices for the telemetry injection type config value.
+ */
+public enum InjectionType {
+
+    /**
+     * Inject native OpenTelemetry types.
+     */
+    NATIVE,
+
+    /**
+     * Inject Helidon neutral types which wrap the OpenTelemetry types.
+     */
+    NEUTRAL;
+
+    static final String DEFAULT = "NATIVE";
+}

microprofile/telemetry/src/main/java/io/helidon/microprofile/telemetry/NativeOpenTelemetryProducer.java

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.helidon.microprofile.telemetry;
+
+import java.util.concurrent.TimeUnit;
+
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.SpanContext;
+import io.opentelemetry.api.trace.StatusCode;
+import io.opentelemetry.api.trace.Tracer;
+
+/**
+ * Producer implementation which injects the native OTel objects (which do not participate in the Helidon-specific
+ * span listener feature).
+ */
+class NativeOpenTelemetryProducer implements OpenTelemetryProducer.Producer {
+
+    static NativeOpenTelemetryProducer create(Tracer nativeTracer) {
+        return new NativeOpenTelemetryProducer(nativeTracer);
+    }
+
+    private final Tracer nativeTracer;
+
+    private NativeOpenTelemetryProducer(Tracer nativeTracer) {
+        this.nativeTracer = nativeTracer;
+    }
+
+    @Override
+    public Tracer tracer() {
+        return nativeTracer;
+    }
+
+    @Override
+    public Span span() {
+        return new Span() {
+            @Override
+            public <T> Span setAttribute(AttributeKey<T> key, T value) {
+                return Span.current().setAttribute(key, value);
+            }
+
+            @Override
+            public Span addEvent(String name, Attributes attributes) {
+                return Span.current().addEvent(name, attributes);
+            }
+
+            @Override
+            public Span addEvent(String name, Attributes attributes, long timestamp, TimeUnit unit) {
+                return Span.current().addEvent(name, attributes, timestamp, unit);
+            }
+
+            @Override
+            public Span setStatus(StatusCode statusCode, String description) {
+                return Span.current().setStatus(statusCode, description);
+            }
+
+            @Override
+            public Span recordException(Throwable exception, Attributes additionalAttributes) {
+                return Span.current().recordException(exception, additionalAttributes);
+            }
+
+            @Override
+            public Span updateName(String name) {
+                return Span.current().updateName(name);
+            }
+
+            @Override
+            public void end() {
+                Span.current().end();
+            }
+
+            @Override
+            public void end(long timestamp, TimeUnit unit) {
+                Span.current().end(timestamp, unit);
+            }
+
+            @Override
+            public SpanContext getSpanContext() {
+                return Span.current().getSpanContext();
+            }
+
+            @Override
+            public boolean isRecording() {
+                return Span.current().isRecording();
+            }
+        };
+    }
+}