Update jdbc doc with connection wrapping disclaimer

docs/instrumentation-list.yaml

@@ -5148,6 +5148,7 @@ libraries:
   - name: jdbc
     description: |
       The JDBC instrumentation provides database client spans and metrics. Each call produces a span named after the SQL verb, enriched with standard DB client attributes (system, database, operation, sanitized statement, peer address) and error details if an exception occurs.
+      The instrumentation unwraps pooled connections (via java.sql.Wrapper) to cache database metadata against the underlying physical connection. Without proper unwrapping support, caching is limited to the wrapper instance, which typically changes each time a connection is retrieved from the pool. This can result in repeated metadata extraction, potentially causing performance degradation.
       There is also a "jdbc-datasource" instrumentation that creates spans for datasource connections, but is disabled by default due to the volume of telemetry produced.
     library_link: https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html
     source_path: instrumentation/jdbc
@@ -5484,6 +5485,13 @@ libraries:
         Enables experimental receive telemetry, which will cause consumers to start a new trace, with only a span link connecting it to the producer trace.
       type: boolean
       default: false
+  - name: kafka-connect-2.6
+    source_path: instrumentation/kafka/kafka-connect-2.6
+    scope:
+      name: io.opentelemetry.kafka-connect-2.6
+    target_versions:
+      javaagent:
+      - org.apache.kafka:connect-api:[2.6.0,)
   - name: kafka-streams-0.11
     library_link: https://kafka.apache.org/documentation/streams/
     source_path: instrumentation/kafka/kafka-streams-0.11
@@ -7611,9 +7619,9 @@ libraries:
       - org.springframework.security:spring-security-config:[6.0.0,]
       library:
       - io.projectreactor:reactor-core:3.5.0
+      - jakarta.servlet:jakarta.servlet-api:[6.0.0,6.1.0)
       - org.springframework.security:spring-security-config:6.0.0
       - org.springframework:spring-web:6.0.0
-      - jakarta.servlet:jakarta.servlet-api:6.0.0
       - org.springframework.security:spring-security-web:6.0.0
     configurations:
     - name: otel.instrumentation.common.enduser.id.enabled

instrumentation/jdbc/README.md

@@ -6,3 +6,26 @@
 | `otel.instrumentation.jdbc.experimental.capture-query-parameters` | Boolean | `false` | Enable the capture of query parameters as span attributes. Enabling this option disables the statement sanitization. <p>WARNING: captured query parameters may contain sensitive information such as passwords, personally identifiable information or protected health info.                                                                |
 | `otel.instrumentation.jdbc.experimental.transaction.enabled`      | Boolean | `false` | Enables experimental instrumentation to create spans for COMMIT and ROLLBACK operations.                                                                                                                                                                                                                                                     |
 | `otel.instrumentation.jdbc.experimental.sqlcommenter.enabled`     | Boolean | `false` | Enables augmenting queries with a comment containing the tracing information. See [sqlcommenter](https://google.github.io/sqlcommenter/) for more info. WARNING: augmenting queries with tracing context will make query texts unique, which may have adverse impact on database performance. Consult with database experts before enabling. |
+
+## Connection Pool Unwrapping
+
+The JDBC instrumentation requires unwrapping pooled connections (via `java.sql.Wrapper`) to
+correctly attribute database operations to the underlying connection and to cache metadata. Most
+connection pools support this by default.
+
+**Performance issue?** If unwrapping fails, the instrumentation may have degraded performance or
+increased overhead with some JDBC drivers. Metadata extraction may result in database queries on
+every operation (depending on driver implementation and caching behavior) instead of being cached,
+and operations may be attributed to the wrong database connection. To fix, ensure your connection
+pool supports unwrapping:
+
+**Vibur DBCP example:**
+```java
+ds.setAllowUnwrapping(true);
+```
+
+**Custom wrappers:** Implement `java.sql.Wrapper` correctly to delegate `isWrapperFor()` and
+`unwrap()` to the underlying connection.
+
+**Failover note:** Cached metadata uses the unwrapped connection object as the key. If your pool
+reuses the same connection object after failover, telemetry may show stale host attributes.

instrumentation/jdbc/metadata.yaml

@@ -2,7 +2,12 @@ description: >
   The JDBC instrumentation provides database client spans and metrics. Each call produces a span
   named after the SQL verb, enriched with standard DB client attributes (system, database,
   operation, sanitized statement, peer address) and error details if an exception occurs.
-
+
+  The instrumentation unwraps pooled connections (via java.sql.Wrapper) to cache database metadata
+  against the underlying physical connection. Without proper unwrapping support, caching is limited
+  to the wrapper instance, which typically changes each time a connection is retrieved from the pool.
+  This can result in repeated metadata extraction, potentially causing performance degradation.
+
   There is also a "jdbc-datasource" instrumentation that creates spans for datasource connections,
   but is disabled by default due to the volume of telemetry produced.
 library_link: https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html