Skip to content

Migrate runtime-telemetry to use declarative configuration API #15734

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
trask merged 2 commits into from
Dec 30, 2025
Merged

Migrate runtime-telemetry to use declarative configuration API #15734

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2c69484
Migrate runtime-telemetry to use declarative configuration API
trask Dec 25, 2025
c2522b0
Use instrumentation_mode
trask Dec 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions ...etry/instrumentation/config/bridge/ConfigPropertiesBackedDeclarativeConfigProperties.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,12 @@ public final class ConfigPropertiesBackedDeclarativeConfigProperties

private static final String GENERAL_PEER_SERVICE_MAPPING = "general.peer.service_mapping";

private static final String AGENT_INSTRUMENTATION_MODE = "java.agent.instrumentation_mode";
private static final String SPRING_STARTER_INSTRUMENTATION_MODE =
"java.spring_starter.instrumentation_mode";
private static final String COMMON_DEFAULT_ENABLED =
"otel.instrumentation.common.default-enabled";

private static final Map<String, String> SPECIAL_MAPPINGS;

static {
Expand Down Expand Up @@ -109,6 +115,17 @@ private ConfigPropertiesBackedDeclarativeConfigProperties(
@Nullable
@Override
public String getString(String name) {
String fullPath = pathWithName(name);

if (fullPath.equals(AGENT_INSTRUMENTATION_MODE)
|| fullPath.equals(SPRING_STARTER_INSTRUMENTATION_MODE)) {
Boolean value = configProperties.getBoolean(COMMON_DEFAULT_ENABLED);
if (value != null) {
return value ? "default" : "none";
}
return null;
}

return configProperties.getString(resolvePropertyKey(name));
}

Expand Down
55 changes: 55 additions & 0 deletions .../instrumentation/config/bridge/ConfigPropertiesBackedDeclarativeConfigPropertiesTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,61 @@ void testWithoutJavaPrefix_doesNotMatch() {
.isNull();
}

@Test
void testAgentInstrumentationMode_getString_booleanTrue() {
DeclarativeConfigProperties config =
createConfig("otel.instrumentation.common.default-enabled", "true");

assertThat(
config.getStructured("java").getStructured("agent").getString("instrumentation_mode"))
.isEqualTo("default");
}

@Test
void testAgentInstrumentationMode_getString_booleanFalse() {
DeclarativeConfigProperties config =
createConfig("otel.instrumentation.common.default-enabled", "false");

assertThat(
config.getStructured("java").getStructured("agent").getString("instrumentation_mode"))
.isEqualTo("none");
}

@Test
void testSpringStarterInstrumentationMode_getString_booleanTrue() {
DeclarativeConfigProperties config =
createConfig("otel.instrumentation.common.default-enabled", "true");

assertThat(
config
.getStructured("java")
.getStructured("spring_starter")
.getString("instrumentation_mode"))
.isEqualTo("default");
}

@Test
void testSpringStarterInstrumentationMode_getString_booleanFalse() {
DeclarativeConfigProperties config =
createConfig("otel.instrumentation.common.default-enabled", "false");

assertThat(
config
.getStructured("java")
.getStructured("spring_starter")
.getString("instrumentation_mode"))
.isEqualTo("none");
}

@Test
void testAgentInstrumentationMode_notSet() {
DeclarativeConfigProperties config = createConfig("some.other.property", "value");

assertThat(
config.getStructured("java").getStructured("agent").getString("instrumentation_mode"))
.isNull();
}

private static DeclarativeConfigProperties createConfig(String key, String value) {
Map<String, String> properties = new HashMap<>();
properties.put(key, value);
Expand Down
6 changes: 4 additions & 2 deletions ...emetry/javaagent/instrumentation/runtimemetrics/java17/Java17RuntimeMetricsInstaller.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.instrumentation.runtimemetrics.java17.RuntimeMetrics;
import io.opentelemetry.instrumentation.runtimemetrics.java17.internal.RuntimeMetricsConfigUtil;
import io.opentelemetry.javaagent.bootstrap.internal.AgentInstrumentationConfig;
import io.opentelemetry.javaagent.extension.AgentListener;
import io.opentelemetry.javaagent.tooling.config.AgentConfig;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

/** An {@link AgentListener} that enables runtime metrics during agent startup. */
Expand All @@ -21,7 +21,9 @@ public class Java17RuntimeMetricsInstaller implements AgentListener {
public void afterAgent(AutoConfiguredOpenTelemetrySdk autoConfiguredSdk) {
RuntimeMetrics runtimeMetrics =
RuntimeMetricsConfigUtil.configure(
RuntimeMetrics.builder(GlobalOpenTelemetry.get()), AgentInstrumentationConfig.get());
RuntimeMetrics.builder(GlobalOpenTelemetry.get()),
GlobalOpenTelemetry.get(),
AgentConfig.instrumentationMode());
if (runtimeMetrics != null) {
Runtime.getRuntime()
.addShutdownHook(
Expand Down
24 changes: 14 additions & 10 deletions ...pentelemetry/instrumentation/runtimemetrics/java17/internal/RuntimeMetricsConfigUtil.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@

package io.opentelemetry.instrumentation.runtimemetrics.java17.internal;

import io.opentelemetry.instrumentation.api.incubator.config.internal.InstrumentationConfig;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.instrumentation.api.incubator.config.internal.DeclarativeConfigUtil;
import io.opentelemetry.instrumentation.runtimemetrics.java17.RuntimeMetrics;
import io.opentelemetry.instrumentation.runtimemetrics.java17.RuntimeMetricsBuilder;
import javax.annotation.Nullable;
Expand All @@ -19,31 +20,34 @@ private RuntimeMetricsConfigUtil() {}

@Nullable
public static RuntimeMetrics configure(
RuntimeMetricsBuilder builder, InstrumentationConfig config) {
RuntimeMetricsBuilder builder, OpenTelemetry openTelemetry, String instrumentationMode) {

@zeitlinger zeitlinger Dec 30, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if a proper enum is warranted here

/*
By default, don't use any JFR metrics. May change this once semantic conventions are updated.
If enabled, default to only the metrics not already covered by runtime-telemetry-java8
*/
boolean defaultEnabled = config.getBoolean("otel.instrumentation.common.default-enabled", true);
if (config.getBoolean("otel.instrumentation.runtime-telemetry-java17.enable-all", false)) {
if (DeclarativeConfigUtil.getInstrumentationConfig(openTelemetry, "runtime_telemetry_java17")
.getBoolean("enable_all", false)) {
builder.enableAllFeatures();
} else if (config.getBoolean("otel.instrumentation.runtime-telemetry-java17.enabled", false)) {
} else if (DeclarativeConfigUtil.getInstrumentationConfig(
openTelemetry, "runtime_telemetry_java17")
.getBoolean("enabled", false)) {
// default configuration
} else if (config.getBoolean(
"otel.instrumentation.runtime-telemetry.enabled", defaultEnabled)) {
} else if (DeclarativeConfigUtil.getInstrumentationConfig(openTelemetry, "runtime_telemetry")
.getBoolean("enabled", instrumentationMode.equals("default"))) {
// This only uses metrics gathered by JMX
builder.disableAllFeatures();
} else {
// nothing is enabled
return null;
}

if (config.getBoolean(
"otel.instrumentation.runtime-telemetry.emit-experimental-telemetry", false)) {
if (DeclarativeConfigUtil.getInstrumentationConfig(openTelemetry, "runtime_telemetry")
.getBoolean("emit_experimental_telemetry/development", false)) {
builder.emitExperimentalTelemetry();
}

if (config.getBoolean("otel.instrumentation.runtime-telemetry.capture-gc-cause", false)) {
if (DeclarativeConfigUtil.getInstrumentationConfig(openTelemetry, "runtime_telemetry")
.getBoolean("capture_gc_cause", false)) {
builder.captureGcCause();
}

Expand Down
6 changes: 4 additions & 2 deletions ...elemetry/javaagent/instrumentation/runtimemetrics/java8/Java8RuntimeMetricsInstaller.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.instrumentation.runtimemetrics.java8.RuntimeMetrics;
import io.opentelemetry.instrumentation.runtimemetrics.java8.internal.RuntimeMetricsConfigUtil;
import io.opentelemetry.javaagent.bootstrap.internal.AgentInstrumentationConfig;
import io.opentelemetry.javaagent.extension.AgentListener;
import io.opentelemetry.javaagent.tooling.config.AgentConfig;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

/** An {@link AgentListener} that enables runtime metrics during agent startup. */
Expand All @@ -25,7 +25,9 @@ public void afterAgent(AutoConfiguredOpenTelemetrySdk autoConfiguredSdk) {

RuntimeMetrics runtimeMetrics =
RuntimeMetricsConfigUtil.configure(
RuntimeMetrics.builder(GlobalOpenTelemetry.get()), AgentInstrumentationConfig.get());
RuntimeMetrics.builder(GlobalOpenTelemetry.get()),
GlobalOpenTelemetry.get(),
AgentConfig.instrumentationMode());
if (runtimeMetrics != null) {
Runtime.getRuntime()
.addShutdownHook(
Expand Down
16 changes: 9 additions & 7 deletions ...opentelemetry/instrumentation/runtimemetrics/java8/internal/RuntimeMetricsConfigUtil.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@

package io.opentelemetry.instrumentation.runtimemetrics.java8.internal;

import io.opentelemetry.instrumentation.api.incubator.config.internal.InstrumentationConfig;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.instrumentation.api.incubator.config.internal.DeclarativeConfigUtil;
import io.opentelemetry.instrumentation.runtimemetrics.java8.RuntimeMetrics;
import io.opentelemetry.instrumentation.runtimemetrics.java8.RuntimeMetricsBuilder;
import javax.annotation.Nullable;
Expand All @@ -19,19 +20,20 @@ private RuntimeMetricsConfigUtil() {}

@Nullable
public static RuntimeMetrics configure(
RuntimeMetricsBuilder builder, InstrumentationConfig config) {
boolean defaultEnabled = config.getBoolean("otel.instrumentation.common.default-enabled", true);
if (!config.getBoolean("otel.instrumentation.runtime-telemetry.enabled", defaultEnabled)) {
RuntimeMetricsBuilder builder, OpenTelemetry openTelemetry, String instrumentationMode) {
if (!DeclarativeConfigUtil.getInstrumentationConfig(openTelemetry, "runtime_telemetry")
.getBoolean("enabled", instrumentationMode.equals("default"))) {
// nothing is enabled
return null;
}

if (config.getBoolean(
"otel.instrumentation.runtime-telemetry.emit-experimental-telemetry", false)) {
if (DeclarativeConfigUtil.getInstrumentationConfig(openTelemetry, "runtime_telemetry")
.getBoolean("emit_experimental_telemetry/development", false)) {
builder.emitExperimentalTelemetry();
}

if (config.getBoolean("otel.instrumentation.runtime-telemetry.capture-gc-cause", false)) {
if (DeclarativeConfigUtil.getInstrumentationConfig(openTelemetry, "runtime_telemetry")
.getBoolean("capture_gc_cause", false)) {
builder.captureGcCause();
}

Expand Down
6 changes: 3 additions & 3 deletions ...g/autoconfigure/internal/instrumentation/runtimemetrics/Java17RuntimeMetricsProvider.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@
package io.opentelemetry.instrumentation.spring.autoconfigure.internal.instrumentation.runtimemetrics;

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.instrumentation.api.incubator.config.internal.InstrumentationConfig;
import io.opentelemetry.instrumentation.runtimemetrics.java17.RuntimeMetrics;
import io.opentelemetry.instrumentation.runtimemetrics.java17.internal.RuntimeMetricsConfigUtil;
import javax.annotation.Nullable;
Expand All @@ -29,8 +28,9 @@ public int minJavaVersion() {

@Nullable
@Override
public AutoCloseable start(OpenTelemetry openTelemetry, InstrumentationConfig config) {
public AutoCloseable start(OpenTelemetry openTelemetry, String instrumentationMode) {
logger.debug("Use runtime metrics instrumentation for Java 17+");
return RuntimeMetricsConfigUtil.configure(RuntimeMetrics.builder(openTelemetry), config);
return RuntimeMetricsConfigUtil.configure(
RuntimeMetrics.builder(openTelemetry), openTelemetry, instrumentationMode);
}
}
6 changes: 3 additions & 3 deletions ...ng/autoconfigure/internal/instrumentation/runtimemetrics/Java8RuntimeMetricsProvider.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@
package io.opentelemetry.instrumentation.spring.autoconfigure.internal.instrumentation.runtimemetrics;

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.instrumentation.api.incubator.config.internal.InstrumentationConfig;
import io.opentelemetry.instrumentation.runtimemetrics.java8.RuntimeMetrics;
import io.opentelemetry.instrumentation.runtimemetrics.java8.internal.RuntimeMetricsConfigUtil;
import javax.annotation.Nullable;
Expand All @@ -29,8 +28,9 @@ public int minJavaVersion() {

@Nullable
@Override
public AutoCloseable start(OpenTelemetry openTelemetry, InstrumentationConfig config) {
public AutoCloseable start(OpenTelemetry openTelemetry, String instrumentationMode) {
logger.debug("Use runtime metrics instrumentation for Java 8");
return RuntimeMetricsConfigUtil.configure(RuntimeMetrics.builder(openTelemetry), config);
return RuntimeMetricsConfigUtil.configure(
RuntimeMetrics.builder(openTelemetry), openTelemetry, instrumentationMode);
}
}
17 changes: 14 additions & 3 deletions ...utoconfigure/internal/instrumentation/runtimemetrics/RuntimeMetricsAutoConfiguration.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@
package io.opentelemetry.instrumentation.spring.autoconfigure.internal.instrumentation.runtimemetrics;

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.instrumentation.api.incubator.config.internal.InstrumentationConfig;
import io.opentelemetry.instrumentation.api.incubator.config.internal.DeclarativeConfigUtil;
import io.opentelemetry.instrumentation.spring.autoconfigure.internal.ConditionalOnEnabledInstrumentation;
import io.opentelemetry.sdk.autoconfigure.spi.ConfigurationException;
import java.util.Comparator;
import java.util.Optional;
import javax.annotation.Nullable;
Expand Down Expand Up @@ -45,7 +46,6 @@ public void stopMetrics() throws Exception {
public void handleApplicationReadyEvent(ApplicationReadyEvent event) {
ConfigurableApplicationContext applicationContext = event.getApplicationContext();
OpenTelemetry openTelemetry = applicationContext.getBean(OpenTelemetry.class);
InstrumentationConfig config = applicationContext.getBean(InstrumentationConfig.class);

double version =
Math.max(8, Double.parseDouble(System.getProperty("java.specification.version")));
Expand All @@ -56,9 +56,20 @@ public void handleApplicationReadyEvent(ApplicationReadyEvent event) {
.findFirst();

if (metricsProvider.isPresent()) {
this.closeable = metricsProvider.get().start(openTelemetry, config);
this.closeable =
metricsProvider.get().start(openTelemetry, instrumentationMode(openTelemetry));
} else {
logger.debug("No runtime metrics instrumentation available for Java {}", version);
}
}

private static String instrumentationMode(OpenTelemetry openTelemetry) {
String mode =
DeclarativeConfigUtil.getInstrumentationConfig(openTelemetry, "spring_starter")
.getString("instrumentation_mode", "default");
if (!mode.equals("default") && !mode.equals("none")) {
throw new ConfigurationException("Unknown instrumentation mode: " + mode);
}
return mode;
}
}
3 changes: 1 addition & 2 deletions .../spring/autoconfigure/internal/instrumentation/runtimemetrics/RuntimeMetricsProvider.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@
package io.opentelemetry.instrumentation.spring.autoconfigure.internal.instrumentation.runtimemetrics;

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.instrumentation.api.incubator.config.internal.InstrumentationConfig;
import javax.annotation.Nullable;

/**
Expand All @@ -19,5 +18,5 @@ public interface RuntimeMetricsProvider {
int minJavaVersion();

@Nullable
AutoCloseable start(OpenTelemetry openTelemetry, InstrumentationConfig config);
AutoCloseable start(OpenTelemetry openTelemetry, String instrumentationMode);
}
13 changes: 13 additions & 0 deletions javaagent-tooling/src/main/java/io/opentelemetry/javaagent/tooling/config/AgentConfig.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,26 @@

package io.opentelemetry.javaagent.tooling.config;

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.instrumentation.api.incubator.config.internal.DeclarativeConfigUtil;
import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
import io.opentelemetry.sdk.autoconfigure.spi.ConfigurationException;

public final class AgentConfig {

public static boolean isDebugModeEnabled(ConfigProperties config) {
return config.getBoolean("otel.javaagent.debug", false);
}

public static String instrumentationMode() {
String mode =
DeclarativeConfigUtil.getInstrumentationConfig(GlobalOpenTelemetry.get(), "agent")
.getString("instrumentation_mode", "default");
if (!mode.equals("default") && !mode.equals("none")) {
throw new ConfigurationException("Unknown instrumentation mode: " + mode);
}
return mode;
}
Comment thread
zeitlinger marked this conversation as resolved.

private AgentConfig() {}
}
Loading