Merge pull request #7423 from OpenLiberty/staging

Staging to vNExt 24.0.0.7 issues

.gitignore

@@ -1,2 +1,4 @@
 .DS_STORE
+.vscode/*
+.vscode/**/*
 antora-playbook.yml

modules/ROOT/pages/jdbc-tracing.adoc

@@ -1,4 +1,4 @@
-// Copyright (c) 2022, 2023 IBM Corporation and others.
+// Copyright (c) 2022, 2024 IBM Corporation and others.
 // Licensed under Creative Commons Attribution-NoDerivatives
 // 4.0 International (CC BY-ND 4.0)
 // https://creativecommons.org/licenses/by-nd/4.0/
@@ -22,7 +22,7 @@ You can enable tracing for your third-party JDBC driver in Open Liberty for debu
 
 == Understanding Open Liberty tracing
 
-How you enable trace for your JDBC driver depends on whether the driver supports the `java.util.logging` Java logging library or some other logging library, such as SLF4J or Log4J. In either case, you must identify your driver in the trace specification. Drivers that support the `java.util.logging` library are specified by the package name that the driver uses.
+How you enable trace for your JDBC driver depends on whether the driver supports the `java.util.logging` Java logging library or some other logging library, such as SLF4J or Log4J. In any case, you must configure the trace specification for your driver. Drivers that support the `java.util.logging` library are specified by the package name that the driver uses.
 
 Drivers that do not support the `java.util.logging` library are specified by the log writer name for the JDBC driver. Open Liberty provides log writers for common database vendors that generate logs based on JDBC specification methods such as `getConnection` and `executeQuery`. Open Liberty also provides a generic log writer for drivers that do not support the `java.util.logging` library and for which no driver-specific log writer exists.
 
@@ -66,11 +66,11 @@ Drivers that support the `java.util.logging` library can also be configured in t
 [#customsettings]
 == Configure custom settings
 
-If your JDBC driver has custom trace settings, you can set these custom trace settings as JDBC driver vendor properties in the `server.xml` file.
+If your JDBC driver has custom trace settings, you can configure these custom trace settings as JDBC driver vendor properties in the `server.xml` file.
 
 [source, xml]
 ----
-<logging traceSpecification="*=info:RRA=all:com.ibm.db2=all" ... />
+<logging traceSpecification="*=info:RRA=all:com.ibm.ws.db2.logwriter=all" ... />
 <datasource ...>
   <!-- traceLevel -1 is equivalent to ALL -->
   <properties.db2.jcc traceLevel="-1"/>
@@ -100,11 +100,11 @@ The following subsections contain JDBC driver specific configuration.
 [#DB2JCC]
 === DB2 JCC
 
-The DB2 JCC driver supports the `java.util.logging` library. The driver uses the `com.ibm.db2` package name in the trace specification. The following `server.xml` file example shows you the configuration to enable trace for the DB2 JCC driver and specify a custom property.
+The DB2 JCC does not support the `java.util.logging` library. This driver has its own logging implementations that output directly to a file by using a PrintWriter. Open Liberty provides the `com.ibm.ws.db2.logwriter` log writer name for trace specification that configures a PrintWriter to output JCC driver trace to the ` trace.log` file. The following `server.xml` file example shows you the configuration to enable trace for the DB2 JCC driver and specify a custom property.
 
 [source, xml]
 ----
-<logging traceSpecification="*=info:RRA=all:com.ibm.db2=all" ... />
+<logging traceSpecification="*=info:RRA=all:com.ibm.ws.db2.logwriter=all" ... />
 <datasource ...>
   <!-- traceLevel -1 is equivalent to ALL -->
   <properties.db2.jcc traceLevel="-1"/>
@@ -117,7 +117,7 @@ For more information about valid values for the `traceLevel` attribute, see http
 [#Derby]
 === Derby
 
-The Derby driver does not support the `java.util.logging` library. Open Liberty provides the `com.ibm.ws.derby.logwriter` log writer name in the trace specification. The following `server.xml` file example shows you the configuration to enable trace for the Derby driver.
+The Derby driver does not support the `java.util.logging` library. Open Liberty provides the `com.ibm.ws.derby.logwriter` log writer name for trace specification. The following `server.xml` file example shows you the configuration to enable trace for the Derby driver.
 
 [source, xml]
 ----
@@ -128,7 +128,7 @@ The Derby driver does not support the `java.util.logging` library. Open Liberty
 [#InformixJDBC]
 === Informix using JDBC
 
-The Informix using JDBC driver supports the `java.util.logging` library. The driver uses the `com.informix` package name in the trace specification. The following `server.xml` file example shows you the configuration to enable trace for the Informix using JDBC driver.
+The Informix using JDBC driver supports the `java.util.logging` library. The driver uses the `com.informix` package name for trace specification. The following `server.xml` file example shows you the configuration to enable trace for the Informix using JDBC driver.
 
 [source, xml]
 ----
@@ -139,11 +139,11 @@ The Informix using JDBC driver supports the `java.util.logging` library. The dri
 [#InformixDB2JCC]
 === Informix using DB2 JCC
 
-The Informix using DB2 JCC driver supports the `java.util.logging` library. The driver uses the `com.ibm.db2` package name in the trace specification. The following `server.xml` file example shows you the configuration to enable trace for the Informix using DB2 JCC driver and specify a custom property.
+Informix using the DB2 JCC driver does not support the `java.util.logging` library. This driver has its own logging implementations that output directly to a file by using a PrintWriter. Open Liberty provides the `com.ibm.ws.db2.logwriter` log writer name for trace specification that configures a PrintWriter to output JCC driver trace to the `trace.log` file. The following `server.xml` file example shows you the configuration to enable trace for Informix by using the DB2 JCC driver and specify a custom property.
 
 [source, xml]
 ----
-<logging traceSpecification="*=info:RRA=all:com.ibm.db2=all" />
+<logging traceSpecification="*=info:RRA=all:com.ibm.ws.db2.logwriter=all" />
 
 <datasource ... >
   <!-- traceLevel -1 is equivalent to ALL -->
@@ -157,7 +157,7 @@ For more information on additional valid values for the traceLevel, see https://
 [#SQLServerJDBCdriver]
 === Microsoft SQL Server JDBC driver
 
-The Microsoft SQL Server JDBC driver supports the `java.util.logging` library. The driver uses the `com.microsoft.sqlserver.jdbc` package name in the trace specification. The following `server.xml` file example shows you the configuration to enable trace for the Microsoft SQL Server JDBC driver.
+The Microsoft SQL Server JDBC driver supports the `java.util.logging` library. The driver uses the `com.microsoft.sqlserver.jdbc` package name for trace specification. The following `server.xml` file example shows you the configuration to enable trace for the Microsoft SQL Server JDBC driver.
 
 [source, xml]
 ----
@@ -168,7 +168,7 @@ The Microsoft SQL Server JDBC driver supports the `java.util.logging` library. T
 [#SQLServerDataDirectdriver]
 === Microsoft SQL Server DataDirect driver
 
-The Microsoft SQL Server DataDirect driver does not support the `java.util.logging` library. Open Liberty provides the `com.ibm.ws.sqlserver.logwriter` log writer name in the trace specification. The following `server.xml` file example shows you the configuration to enable trace for the Microsoft SQL Server DataDirect driver.
+The Microsoft SQL Server DataDirect driver does not support the `java.util.logging` library. Open Liberty provides the `com.ibm.ws.sqlserver.logwriter` log writer name for trace specification. The following `server.xml` file example shows you the configuration to enable trace for the Microsoft SQL Server DataDirect driver.
 
 [source, xml]
 ----
@@ -179,16 +179,18 @@ The Microsoft SQL Server DataDirect driver does not support the `java.util.loggi
 [#Oracle]
 === Oracle
 
-Oracle provides two different drivers, one for production and another for debugging purposes. The production driver does not produce any trace, so you need to download and replace your production driver with the debugging driver. The debugging driver has `_g` in the driver name. For example, `ojdbc8.jar` is `ojdbc8_g.jar`. Configure the debugging driver by specifying the `library` subelement within the `jdbcDriver` element. The `library` subelement defines the path to the debugging driver JAR file.
+Prior to Oracle 23c, Oracle provided two different drivers, one for production and another for debugging purposes. The production driver does not produce any trace, so you need to download and replace your production driver with the debugging driver. The debugging driver has `_g` in the driver name. For example, `ojdbc8.jar` is `ojdbc8_g.jar`. Configure the debugging driver by specifying the `library` subelement within the `jdbcDriver` element. The `library` subelement defines the path to the debugging driver JAR file.
 
-The Oracle driver supports the `java.util.logging` library. The driver uses the `oracle` package name in the trace specification. The following `server.xml` file example shows you how to configure the Oracle debugging driver and enable trace.
+In Oracle 23c and later, Oracle no longer provides the `_g` drivers and diagnostic trace is provided in the base JDBC driver.
+
+The Oracle JDBC and Oracle JDBC debug drivers support the `java.util.logging` library. The driver uses the `oracle` package name for trace specification. The following `server.xml` file example shows you how to configure the Oracle debugging driver and enable trace.
 
 [source, xml]
 ----
 <logging traceSpecification="*=info:RRA=all:oracle=all" />
 <jdbcDriver id="oracleDriver">
   <library id="oracleDebug">
-      <file name="path_to_oracle_driver/ojdbcX_g.jar"/>
+      <file name="path_to_oracle_driver/ojdbcX[_g].jar"/>
   </library>
 </jdbcDriver>
 ----
@@ -210,7 +212,7 @@ The following `server.xml` file example shows you how to configure the Oracle de
 ----
 <jdbcDriver id="oracleDriver">
   <library id="oracleDebug">
-      <file name="path_to_oracle_driver/ojdbcX_g.jar"/>
+      <file name="path_to_oracle_driver/ojdbcX[_g].jar"/>
   </library>
 </jdbcDriver>
 ----
@@ -247,14 +249,14 @@ For Oracle recommended settings, see the Oracle documentation.
 [#PostgreSQL]
 === PostgreSQL
 
-The PostgreSQL driver version 42.0.0 and later supports the `java.util.logging` library. The driver uses the `org.postgresql` package name in the trace specification. The following `server.xml` file example shows the configuration to enable trace for the PostgreSQL driver.
+The PostgreSQL driver version 42.0.0 and later supports the `java.util.logging` library. The driver uses the `org.postgresql` package name for trace specification. The following `server.xml` file example shows the configuration to enable trace for the PostgreSQL driver.
 
 [source, xml]
 ----
 <logging traceSpecification="*=info:RRA=all:org.postgresql=all" />
 ----
 
-Prior to version 42.0.0, the PostgreSQL driver  does not support the `java.util.logging` library. Open Liberty provides the `com.ibm.ws.postgresql.logwriter` log writer name in the trace specification. The following `server.xml` file example shows the configuration to enable trace for the PostgreSQL driver in versions earlier than 42.0.0.
+Prior to version 42.0.0, the PostgreSQL driver  does not support the `java.util.logging` library. Open Liberty provides the `com.ibm.ws.postgresql.logwriter` log writer name for trace specification. The following `server.xml` file example shows the configuration to enable trace for the PostgreSQL driver in versions earlier than 42.0.0.
 
 [source, xml]
 ----
@@ -265,7 +267,7 @@ Prior to version 42.0.0, the PostgreSQL driver  does not support the `java.util.
 [#Sybase]
 === Sybase
 
-The Sybase driver does not support the `java.util.logging` library. Open Liberty provides the `com.ibm.ws.sybase.logwriter` log writer name in the trace specification. The following `server.xml` file example shows you the configuration to enable trace for the Sybase driver.
+The Sybase driver does not support the `java.util.logging` library. Open Liberty provides the `com.ibm.ws.sybase.logwriter` log writer name for trace specification. The following `server.xml` file example shows you the configuration to enable trace for the Sybase driver.
 
 [source, xml]
 ----
@@ -276,7 +278,7 @@ The Sybase driver does not support the `java.util.logging` library. Open Liberty
 [#Otherdatabases]
 === Other databases
 
-The generic `com.ibm.ws.database.logwriter` log writer name is used in the trace specification for drivers that do not support the `java.util.logging` library and for which Open Liberty does not provide a driver-specific log writer. The following `server.xml` file example shows you how to enable trace with the generic log writer.
+The generic `com.ibm.ws.database.logwriter` log writer name is used for drivers that do not support the `java.util.logging` library and for which Open Liberty does not provide a driver-specific log writer. The following `server.xml` file example shows you how to enable trace with the generic log writer.
 
 [source, xml]
 ----

modules/ROOT/pages/microprofile-config-properties.adoc

@@ -272,7 +272,7 @@ a| Specifies a list of metric names that are paired with custom sets of histogra
 * Defining a metric name with no bucket values or invalid values has no effect.
 Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values.
 
-This property is available starting in MicroProfile Metrics 5.1.
+This property is available starting in MicroProfile Metrics 3.0.
 |Server startup
 |`mp.metrics.distribution.histogram.buckets=test.alpha.histogram=10.0,50.0,100.0;test.beta.histogram=30.0,50.0,123`
 
@@ -285,7 +285,7 @@ a| When the `mp.metrics.distribution.percentiles-histogram.enabled` property is
 * Defining a metric name with no value or an invalid value has no effect.
 * Value precedence is right to left so values that are defined later in the property definition take precedence over earlier values.
 
-This property is available starting in MicroProfile Metrics 5.1.
+This property is available starting in MicroProfile Metrics 3.0.
 |Server startup
 | `mp.metrics.distribution.histogram.max-value=test.histogram=120`
 
@@ -298,7 +298,7 @@ a| When the `mp.metrics.distribution.percentiles-histogram.enabled` property is
 * Defining a metric name with no value or an invalid value has no effect.
 * Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values.
 
-This property is available starting in MicroProfile Metrics 5.1.
+This property is available starting in MicroProfile Metrics 3.0.
 |Server startup
 | `mp.metrics.distribution.histogram.min-value=test.histogram=50`
 
@@ -312,7 +312,7 @@ a|Specifies a list of metric names that are paired with custom sets of percentil
 * Setting the property without any value disables percentiles for all histogram and timer metrics.
 * Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values.
 
-This property is available starting in MicroProfile Metrics 5.1.
+This property is available starting in MicroProfile Metrics 3.0.
 |Server startup
 |`mp.metrics.distribution.percentiles=test.histogram=0.8,0.86,0.95;test.timer=0.9,0.99;test.*=0.5,0.6;other.*=`
 
@@ -324,7 +324,7 @@ a| Specifies a list of metric names that are paired with a true or false value.
 * Defining a metric name with no values or invalid values has no effect.
 * Values defined later take precedence over values before. Precedence is right to left.
 
-This property is available starting in MicroProfile Metrics 5.1.
+This property is available starting in MicroProfile Metrics 3.0.
 |Server startup
 | `mp.metrics.distribution.percentiles-histogram.enabled=test.timer=true;test.histogram=false`
 
@@ -337,7 +337,7 @@ a| Specifies a list of metric names that are paired with custom sets of histogra
 * Defining a metric name with no bucket values or invalid values has no effect.
 * Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values.
 
-This property is available starting in MicroProfile Metrics 5.1.
+This property is available starting in MicroProfile Metrics 3.0.
 |Server startup
 |`mp.metrics.distribution.timer.buckets=test.*=50s,100s;test.alpha.timer=100,500ms,1s`
 
@@ -350,7 +350,7 @@ a| When the `mp.metrics.distribution.percentiles-histogram.enabled` property is
 * Defining a metric name with no value or an invalid value has no effect.
 * Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values.
 
-This property is available starting in MicroProfile Metrics 5.1.
+This property is available starting in MicroProfile Metrics 3.0.
 |Server startup
 | `mp.metrics.distribution.histogram.max-value=test.timer=5s`
 
@@ -363,7 +363,7 @@ a| When the `mp.metrics.distribution.percentiles-histogram.enabled` property is
 * Defining a metric name with no value or an invalid value has no effect.
 * Value precedence is right to left so values that are specified later in the property definition take precedence over previously specified values.
 
-This property is available starting in MicroProfile Metrics 5.1.
+This property is available starting in MicroProfile Metrics 3.0.
 |Server startup
 | `mp.metrics.distribution.histogram.min-value=test.timer=200`