Update jdbc doc with connection wrapping disclaimer (#14884)

Author: jaydeluca

docs/instrumentation-list.yaml

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

instrumentation/jdbc/README.md

@@ -6,3 +6,12 @@
 | `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 instrumentation unwraps pooled connections (via java.sql.Wrapper) to cache database metadata
+against the underlying physical connection. Most connection pools support this by default.
+
+In the case that a connection pool doesn't support this, 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.

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