Skip to content

Commit

Permalink
Allow config to enable injection of OTel types which notify span list…
Browse files Browse the repository at this point in the history
…eners

Signed-off-by: Tim Quinn <[email protected]>
  • Loading branch information
tjquinno committed Dec 18, 2024
1 parent e36b9d4 commit 89ae56f
Show file tree
Hide file tree
Showing 15 changed files with 1,060 additions and 85 deletions.
15 changes: 15 additions & 0 deletions docs/src/main/asciidoc/mp/telemetry.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions microprofile/telemetry/etc/spotbugs/exclude.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
42 changes: 39 additions & 3 deletions microprofile/telemetry/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
/*
* Copyright (c) 2024 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";
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
/*
* Copyright (c) 2024 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();
}
};
}
}
Loading

0 comments on commit 89ae56f

Please sign in to comment.