Update jdbc doc with connection wrapping disclaimer

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 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

@@ -5,3 +5,26 @@
 | `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 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,13 @@ 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 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