Update jdbc doc with connection wrapping disclaimer

docs/instrumentation-list.yaml

@@ -4735,7 +4735,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 to cache database metadata. If your connection pool doesn't support unwrapping (java.sql.Wrapper), metadata extraction will occur on every operation, causing higher CPU usage.
+      The instrumentation requires unwrapping pooled connections (via java.sql.Wrapper) to correctly attribute database operations to the underlying connection and to cache metadata. If your connection pool doesn't support unwrapping, the instrumentation may have degraded performance or increased overhead with some JDBC drivers, as metadata extraction may result in database queries on every operation depending on driver implementation and caching behavior.
       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

instrumentation/jdbc/README.md

@@ -8,12 +8,15 @@
 
 ## Connection Pool Unwrapping
 
-The JDBC instrumentation unwraps pooled connections to cache database metadata efficiently. Most
+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, database metadata is extracted on every operation
-instead of being cached, causing higher CPU usage. To fix, ensure your connection pool supports
-unwrapping:
+**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

instrumentation/jdbc/metadata.yaml

@@ -3,9 +3,11 @@ description: >
   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 to cache database metadata. If your connection pool
-  doesn't support unwrapping (java.sql.Wrapper), metadata extraction will occur on every operation,
-  causing higher CPU usage.
+  The instrumentation requires unwrapping pooled connections (via java.sql.Wrapper) to correctly
+  attribute database operations to the underlying connection and to cache metadata. If your connection
+  pool doesn't support unwrapping, the instrumentation may have degraded performance or increased
+  overhead with some JDBC drivers, as metadata extraction may result in database queries on every
+  operation depending on driver implementation and caching behavior.
 
   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.