Update jdbc doc with connection wrapping disclaimer

Author: jaydeluca

docs/instrumentation-list.yaml

@@ -4735,6 +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.
       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

@@ -5,3 +5,23 @@
 | `otel.instrumentation.jdbc.statement-sanitizer.enabled`           | Boolean | `true`  | Enables the DB statement sanitization.                                                                                                                                                                                                                                        |
 | `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.                                                                                                                                                                                      |
+
+## Connection Pool Unwrapping
+
+The JDBC instrumentation unwraps pooled connections to cache database metadata efficiently. 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:
+
+**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,11 @@ 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.
+
   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