2.10 Using Oracle ORAchk to Confirm System Readiness for Implementing Application Continuity

Application Continuity Checking for Application Continuity enables you to deploy Application Continuity easily and transparently.

• Overview of Application Continuity
  
• Checks for Application Continuity
  
• Application Continuity Protection Check
  

2.10.1 Overview of Application Continuity

Oracle ORAchk identifies any references to deprecated Oracle JDBC concrete classes that need to be changed.

Oracle ORAchk analyzes the database operations in the application and reports the level of protection. It also reports where and why the applications are not protected.

Together, these checks can help you ensure that your application workload is covered by Oracle Application Continuity.

2.10.2 Checks for Application Continuity

Application Continuity Checking for Concrete Classes

Determine whether Java applications use deprecated Oracle JDBC concrete classes.

To use Application Continuity with Java, replace the deprecated Oracle JDBC concrete classes. For information about the deprecation of concrete classes including actions to take if an application uses them, see My Oracle Support note 1364193.1.

To know if the application is using concrete classes, use Application Continuity checking (called acchk in Oracle ORAchk. Verify the application in advance while planning for high availability for your application.

For JDBC driver version 12.2.0.2 and below, Application Continuity is unable to replay transactions that use oracle.sql deprecated concrete classes of the form ARRAY, BFILE, BLOB, CLOB, NCLOB, OPAQUE, REF, or STRUCT as a variable type, a cast, the return type of a method, or calling a constructor.

For JDBC driver version 18c and above, Application Continuity is unable to replay transactions that use oracle.sql deprecated concrete classes of the form OPAQUE, REF, or STRUCT as a variable type, a cast, the return type of a method, or calling a constructor.

Modify them for Application Continuity to work with the application.

There are four values that control the Application Continuity checking for Oracle concrete classes. Set these values either on the command-line, or through shell environment variables, or mixed. The values are as follows:

Table 2-4 Application Continuity Checking for Concrete Classes

Command-Line Argument	Shell Environment Variable	Usage
–asmhome jarfilename	RAT_AC_ASMJAR	This must point to a version of asm-all-5.0.3.jar that you download from ASM Home page.
-javahome JDK8dirname	RAT_JAVA_HOME	This must point to the JAVA_HOME directory for a JDK8 installation.
-appjar dirname	RAT_AC_JARDIR	To analyze the application code for references to Oracle concrete classes, this must point to the parent directory name for the code. The program analyzes .class files, and recursively .jar files and directories.
-jdbcver	RAT_AC_JDBCVER	JDBC versions 12, 12.0.1, 18, 18.2, 19, or 19.1.

Example Application Continuity Concrete Class Checks Summary

The following command checks the Application Continuity checking for Oracle concrete classes.

$ orachk -acchk 
-asmhome /path/orachk/asm-5.0.3/lib/all/asm-all-5.0.3.jar 
-javahome /usr/lib/jvm/jre-1.8.0-openjdk.x86_64 -jdbcver 19.1 
-appjar /scratch/nfs/tmp/jarfiles/app.jar

Outage Type     Status  Message
Concrete class checks   Total : 114 Passed : 110 Warning : 0 Failed : 4 (Failed check count is one per file)
                FAILED  [ac/workload/lobsanity/AnydaaOut][[CAST]desc=oracle/sql/ANYDATAmethodname=getDataInfo,lineno=38]
                FAILED  [ac/workload/lobsanity/AnydataOut][[CAST]desc=oracle/sql/ANYDATAmethodname=getDataInfo,lineno=38]
                FAILED  [ac/workload/lobsanity/AnydataSelect][[CAST]desc=oracle/sql/ANYDATAmethodname=queryAnydata,lineno=32]
                FAILED  [ac/workload/lobsanity/AnydataSelect][[CAST]desc=oracle/sql/ANYDATAmethodname=queryAnydata,lineno=32]

Application Continuity Checking for the Protection Level Application Continuity is Providing Your Application

Measure Coverage

Destructive testing is a good thing to do. However, introducing failures is non-deterministic. The application can fail over in all the tests, and then in production a failure occurs elsewhere and unexpectedly some requests do not fail over.

Using AC Check Coverage Analysis averts this situation by reporting in advance the percentage of requests that are fully protected by Application Continuity, and for the requests that are not fully protected, which they are and where. Use the coverage check before deployment, and after application changes. Developers and management know how to protect an application release from failures of the underlying infrastructure. If there is a problem, then it can be fixed before the application is released or waived knowing the level of coverage.

Executing the coverage check is rather like using SQL_TRACE. First run the application in a representative test environment with Application Continuity trace turned on at the server side. The trace is collected in the standard database user trace directory in user trace files. Then, pass this directory as input to Oracle ORAchk to report the coverage for the application functions. As this check uses Application Continuity, the database and client must be above 12c. The application need not necessarily released with Application Continuity. The check is to help you before release.

The following is a summary of the coverage analysis.

• If a round trip is made to the database server and returns while Application Continuity’ capture is enabled during capture phase, then it is counted as a protected call.

• If a round trip is made to the database server while Application Continuity’ capture is disabled (not in a request, or following a restricted call or a disable replay API was called), then it is counted as an unprotected call.

• Round trips ignored by capture and replay are ignored in the protection-level statistics.

At the end of processing each trace file, a level of protection for the calls sent to the database is computed.

For each trace: PASS (>= 75), WARNING (25 <= value <75), and FAIL (< 25).

Running the Coverage Report

1. Turn on tracing at database level.

   Before running the workload, run the SQL statements as DBA on a test Oracle Database server so that the trace files include the needed information.

   For more details on setting or resetting Application Continuity trace events, please refer to sections Setting Application Continuity Trace Events Online in Memory and Setting Application Continuity Trace Events Offline in SPFILE.

2. Run through the application functions.

   To report on an application function, the application function must be run. The more application functions run, the better the information that the coverage analysis provides.

3. Use Oracle ORAchk to analyze the collected database traces and report the level of protection, and where not protected, reports why a request is not protected.

   To control the Application Continuity checking for coverage, set the following 2 values through command line or shell environment variables (or mixed):

   Table 2-5 Using Application Continuity Checking for Protection Level

   Command-Line Argument	Shell Environment Variable	Usage
   -javahome JDK8dirname	RAT_JAVA_HOME	This must point to the JAVA_HOME directory for a JDK8 installation.
   -apptrc dirname	RAT_AC_TRCDIR	To analyze the coverage, specify a directory name that contains one or more database server trace files. The trace directory is generally, $ORACLE_BASE/diag/rdbms/{DB_UNIQUE_NAME}/$ORACLE_SID/trace

Setting Application Continuity Trace Events Online in Memory

You can set or reset events in memory using the alter system set events command.

1. To turn on tracing online for all sessions in one instance:

   SQL> alter system set events 'trace[progint_appcont_rdbms]:trace[sess_signature] disk highest:10602 
   trace name context forever, level 28:10702 trace name context forever, level 16';

2. To turn off tracing online for all sessions in one instance:

   SQL> alter system set events 'trace[progint_appcont_rdbms] off: trace[sess_signature] off:10602 
   trace name context off:10702 trace name context off';

3. To turn on tracing online per session:

   SQL> alter session set events='trace[progint_appcont_rdbms]:trace[sess_signature] disk highest:10602 
   trace name context forever, level 28:10702 trace name context forever, level 16';

4. To turn off tracing online per session:

   SQL> alter system set events 'trace[progint_appcont_rdbms] off: trace[sess_signature] off:10602 
   trace name context off:10702 trace name context off';

Setting Application Continuity Trace Events Offline in SPFILE

You cannot set or reset events in memory using the alter system set event command with SCOPE set to memory; instead, run the alter system set event command when you want to do changes to the SPFILE.

SQL> alter system set event='10602 trace name context forever, level 28:trace[progint_appcont_rdbms]:10702 
trace name context forever, level 16';

System altered.

You need to restart the database instance after each change to the SPFILE.

Example Coverage Report

$ orachk -javahome /tmp/jdk1.8.0_40 -apptrc $ORACLE_BASE/diag/rdbms/{DB_UNIQUE_NAME}/$ORACLE_SID/trace

Reading the Coverage Report

The coverage check produces a directory named orachk_uname_date_time. This report summaries coverage and lists trace files that have WARNINGS or FAIL status. To ensure all requests PASS (Coverage(%) = 100), check the PASS report, acchk_scorecard_pass.html. under the reports directory.

The output includes the database service name, the module name (from v$session.program, which can be set on the client side using the connection property on Java, for example, oracle.jdbc.v$session.program), the ACTION and CLIENT_ID, which can be set using setClientInfo with OCSID.ACTION and OCSID.CLIENTID respectively.

Example output: found in orachk_.....html#acchk_scorecard

Outage Type           Status  Message
Coverage checks               TotalRequest = 1088 PASS = 1082 WARNING = 1 FAIL = 5
                      FAIL    Trace file name = orcl1_ora_30467.trc Line number of Request start = 1409 Request number = 6
                              SERVICE NAME = (srv_auto_pdb1) MODULE NAME = (SQL*Plus) ACTION NAME = () CLIENT ID = ()
                              Coverage(%) = 12 Protected Calls = 1 Unprotected Calls = 7
                      WARNING Trace file name = orcl1_ora_321597.trc Line number of Request start = 653 Request number = 1
                              SERVICE NAME = (srv_ac_pdb2) MODULE NAME = (JDBC Thin Client) ACTION NAME = () CLIENT ID = ()
                              Coverage(%) = 25 Protected Calls = 1 Unprotected Calls = 3
 	              FAIL    Trace file name = orcl1_ora_292714.trc Line number of Request start = 1598 Request number = 7
                              SERVICE NAME = (srv_ac_pdb2) MODULE NAME = (SQL*Plus) ACTION NAME = () CLIENT ID = ()
                              Coverage(%) = 16 Protected Calls = 1 Unprotected Calls = 5
                      FAIL    Trace file name = orcl1_ora_112022.trc Line number of Request start = 1167 Request number = 3
                              SERVICE NAME = (srv_ac_pdb2) MODULE NAME = (JDBC Thin Client) ACTION NAME = () CLIENT ID = ()
                              Coverage(%) = 0 Protected Calls = 0 Unprotected Calls = 1
                      FAIL    Trace file name = orcl1_ora_112022.trc Line number of Request start = 1353 Request number = 4
                              SERVICE NAME = (srv_ac_pdb2) MODULE NAME = (JDBC Thin Client) ACTION NAME = () CLIENT ID = ()
                              Coverage(%) = 0 Protected Calls = 0 Unprotected Calls = 2
                      FAIL    Trace file name = orcl1_ora_112022.trc Line number of Request start = 1689 Request number = 5
                              SERVICE NAME = (srv_ac_pdb2) MODULE NAME = (JDBC Thin Client) ACTION NAME = () CLIENT ID = ()
                              Coverage(%) = 0 Protected Calls = 0 Unprotected Calls = 1
                      PASS    Report containing checks that passed:
                              /scratch/nfs/orachk/orachk_rwsbj14_060219_184513/reports/acchk_scorecard_pass.html

2.10.3 Application Continuity Protection Check

The Application Continuity Protection Check (ACCHK) feature generates Application Continuity coverage report for your applications.

For more information, see Application Continuity Protection Check in the Oracle Real Application Clusters Administration and Deployment Guide.