up

Author: trask

.github/agents/knowledge/config-property-stability.md

@@ -52,7 +52,7 @@ Defined in [VERSIONING.md](../../../VERSIONING.md):
 Examples (flat ↔ YAML):
 
 - `otel.instrumentation.http.client.capture-request-headers` ↔ `request_captured_headers` — **stable**
-- `otel.instrumentation.common.experimental.db-sqlcommenter.enabled` ↔ `sqlcommenter/development: { enabled: true }` — **experimental**
+- `otel.instrumentation.common.db.experimental.sqlcommenter.enabled` ↔ `sqlcommenter/development: { enabled: true }` — **experimental**
 - `otel.instrumentation.http.client.emit-experimental-telemetry` ↔ `emit_experimental_telemetry/development: true` — **experimental**
 
 ## Deprecation Communication

CHANGELOG.md

@@ -16,6 +16,9 @@
   `*.query-sanitization.enabled` names, and deprecated the declarative config name
   `statement_sanitizer` in favor of `query_sanitization`
 - Deprecated the declarative config group `common.database` in favor of `common.db`
+- Deprecated the common DB sqlcommenter system property name
+  `otel.instrumentation.common.experimental.db-sqlcommenter.enabled` in favor of
+  `otel.instrumentation.common.db.experimental.sqlcommenter.enabled`
 - Deprecated the GraphQL system property name
   `otel.instrumentation.graphql.query-sanitizer.enabled` and declarative config name
   `query_sanitizer` in favor of `otel.instrumentation.graphql.query-sanitization.enabled` and

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/config/internal/DbConfig.java

@@ -87,8 +87,9 @@ private static Boolean getCommonSqlCommenterEnabled(OpenTelemetry openTelemetry)
     Boolean deprecatedPropertyValue =
         commonConfig.get("db_sqlcommenter/development").getBoolean("enabled");
     if (deprecatedPropertyValue != null) {
-      warnIfDeprecatedSystemPropertyUsed(
-          "otel.instrumentation.common.experimental.db-sqlcommenter.enabled");
+      warnIfDeprecatedExperimentalSystemPropertyUsed(
+          "otel.instrumentation.common.experimental.db-sqlcommenter.enabled",
+          "otel.instrumentation.common.db.experimental.sqlcommenter.enabled");
       return deprecatedPropertyValue;
     }
 
@@ -170,13 +171,15 @@ private static void warnIfDeprecatedSystemPropertyUsed(
     }
   }
 
-  private static void warnIfDeprecatedSystemPropertyUsed(String deprecatedProperty) {
+  private static void warnIfDeprecatedExperimentalSystemPropertyUsed(
+      String deprecatedProperty, String replacementProperty) {
     if (warnedDeprecatedProperties.add(deprecatedProperty)) {
       logger.warning(
           "The "
               + deprecatedProperty
-              + " system property is deprecated and will be removed in a future version. Use"
-              + " equivalent declarative configuration instead.");
+              + " system property is deprecated and will be removed in a future version. Use "
+              + replacementProperty
+              + " instead.");
     }
   }
 

instrumentation/jdbc/library/src/main/java/io/opentelemetry/instrumentation/jdbc/OpenTelemetryDriver.java

@@ -52,6 +52,8 @@
 /** JDBC driver for OpenTelemetry. */
 public final class OpenTelemetryDriver implements Driver {
 
+  private static final Logger logger = Logger.getLogger(OpenTelemetryDriver.class.getName());
+
   // visible for testing
   static final OpenTelemetryDriver INSTANCE = new OpenTelemetryDriver();
 
@@ -62,21 +64,43 @@ public final class OpenTelemetryDriver implements Driver {
 
   private static final String URL_PREFIX = "jdbc:otel:";
   private static final AtomicBoolean REGISTERED = new AtomicBoolean();
+  private static final AtomicBoolean warnedDeprecatedCommonSqlCommenterProperty =
+      new AtomicBoolean();
   private static final List<Driver> DRIVER_CANDIDATES = new CopyOnWriteArrayList<>();
 
   @SuppressWarnings("deprecation") // library flat config fallback remains supported until 3.0
   private static SqlCommenter getSqlCommenter(OpenTelemetry openTelemetry) {
+    Boolean deprecatedCommonSqlCommenterEnabled = getDeprecatedCommonSqlCommenterEnabled();
     boolean enabled =
         DbConfig.isSqlCommenterEnabled(
             openTelemetry,
             "jdbc",
             ConfigPropertiesUtil.getBoolean(
                 "otel.instrumentation.jdbc.experimental.sqlcommenter.enabled",
                 ConfigPropertiesUtil.getBoolean(
-                    "otel.instrumentation.common.experimental.db-sqlcommenter.enabled", false)));
+                    "otel.instrumentation.common.db.experimental.sqlcommenter.enabled",
+                    deprecatedCommonSqlCommenterEnabled != null
+                        ? deprecatedCommonSqlCommenterEnabled
+                        : false)));
     return SqlCommenter.builder().setEnabled(enabled).build();
   }
 
+  @Nullable
+  @SuppressWarnings("deprecation") // library flat config fallback remains supported until 3.0
+  private static Boolean getDeprecatedCommonSqlCommenterEnabled() {
+    Boolean deprecatedValue =
+        ConfigPropertiesUtil.getBoolean(
+            "otel.instrumentation.common.experimental.db-sqlcommenter.enabled");
+    if (deprecatedValue != null
+        && warnedDeprecatedCommonSqlCommenterProperty.compareAndSet(false, true)) {
+      logger.warning(
+          "The otel.instrumentation.common.experimental.db-sqlcommenter.enabled system property"
+              + " is deprecated and will be removed in a future version. Use"
+              + " otel.instrumentation.common.db.experimental.sqlcommenter.enabled instead.");
+    }
+    return deprecatedValue;
+  }
+
   static {
     try {
       int[] version = parseInstrumentationVersion();