X

Proactive insights, news and tips from Oracle WebLogic Server Support. Learn Oracle from Oracle.

Using Orachk for Application Continuity Coverage Analysis

Stephen Felts
Manager

As I described in the blog Part2 - 12c Database and WLS - Application continuity, Application Continuity (AC) is a great feature for avoiding errors to the user with minimal changes to the application and configuration. In the blog Using Orachk to Clean Up Concrete Classes for Application Continuity, I described the one of the many uses of the Oracle utility program, focusing on checking for Oracle concrete class usage that needs to be removed to run with AC.

The download page for Orachk is at https://support.oracle.com/epmos/faces/DocumentDisplay?id=1268927.2.

This article will focus a second analysis that can be using Orachk to see if your application workload will be protected by AC.

Before running the workload to test AC, you need to turn on a specific tracing flag on the database server to see RDBMS-side program interfaces for AC. Run the following statement on the database server so that the trace files will output the needed information.  Normally this would be run as the DBA, likely in sqlplus or sqldeveloper.  This will enable tracing for all sessions.

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

Then run the application workload.  This will produce trace output that can be analyzed with orachk.

There are three values that control the AC checking (called acchk in orachk) for protection analysis. The values can be set either on the command line or via shell environment variable (or mixed). They are the following.

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 trace files for AC coverage, specify a
directory name that contains one or more database server trace files. The trace directory is generally

$ORACLE_BASE/diag/rdbms/$ORACLE_UNQNAME/$ORACLE_SID/trace

This test works 12 database server and later since AC
was introduced in that release.

NONE

RAT_ACTRACEFILE_WINDOW

Optionally, when scanning the trace directory for trace files, this optional value limit the analysis to the specified most recent number of days. There may be thousands of files and this parameter drops files older than the specified number of days.

For example, $ ./orachk -acchk -javahome /tmp/jdk1.8.0_40 -apptrc $ORACLE_BASE/diag/rdbms/$ORACLE_UNQNAME/$ORACLE_SID/trace

Understanding the analysis requires some understanding of how AC is used. First, it’s only available when using a replay driver, e.g., oracle.jdbc.replay.DataSourceImpl. Second, it’s necessary to identify request boundaries to the driver so that operations can be tracked and potentially replayed if necessary. The boundaries are defined by calling beginRequest by casting the connection to oracle.jdbc.replay.ReplayableConnection, which enables replay, and calling endRequest, which disables replay.

1. If you are using UCP or WLS, the boundaries are handled automatically when you get and close a connection.

2. If you aren’t using one of these connection pools that are tightly bound to the Oracle replay driver, you will need to do the calls directly in the application.

3. If you are using a UCP or WLS pool but you get a connection and hold onto it instead of regularly returning it to the connection pool, you will need to handle the intermediate request boundaries. This is error prone and not recommended.

4. If you call commit on the connection, replay is disabled by default.  For customers using 19.x and later, the recommendation is to use TAC.  For customers using earlier releases, you can set the service SESSION_STATE_CONSISTENCY to STATIC mode instead of the default DYNAMIC mode, then a commit does not disable replay. See the first link above for further discussion of SESSION_STATE_CONSISTENCY. If you are using the default, you should close the connection immediately after the commit. Otherwise, the subsequent operations are not covered by replay for the remainder of the request.

5. It is also possible for the application to explicitly disable replay in the current request by calling disableReplay() on the connection.

6. There are also some operations that cannot be replayed and calling one will disable replay in the current request.

The following is a summary of the coverage analysis.

- If a round-trip is made to the database server after replay is enabled and not disabled, it is counted as a protected call.

- If a round-trip is made to the database server when replay has been disabled or replay is inactive (not in a request, or it is a restricted call, or the disable API was called), it is counted as an unprotected call until the next endRequest or beginRequest.

- Calls that are ignored for the purpose of replay are ignored in the statistics.

At the end of processing a trace file, it computes

(protected * 100) / (protected + unprotected)

to determine PASS (>= 75), WARNING ( 25 <= value <75) and FAIL (< 25).

Running orachk produces a directory named orachk_<uname>_<date>_<time>. If you want to see all of the details, look for file named o_coverage_classes*.out under the outfiles subdirectory. It has the information for all of the trace files.

The program generates an html file that is listed in the program output. It drops output related to trace files that PASS (but they might not be 100%). If you PASS but you don’t get 100%, it’s possible that an operation won’t be replayed.

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 oracle.jdbc.v$session.program), the ACTION and CLIENT_ID (which can be set using setClientInfo with "OCSID.ACTION" and "OCSID.CLIENTID” respectively).

The following is an actual table generated by orachk.

Outage
Type

Status

Message

     
     

Coverage checks

 

TotalRequest = 25

PASS = 20

WARNING = 5

FAIL = 0

     
 

WARNING

[WARNING] Trace file name =
orcl1_ora_10046.trc Row number = 738

SERVICE NAME = (dbhost.us.oracle.com) MODULE NAME = (ac_1_bt) ACTION NAME =
(qryOrdTotal_SP@alterSess_OrdTot) CLIENT ID =
(clthost-1199-Default-3-jdbc000386)

Coverage(%) = 66 ProtectedCalls = 2 UnProtectedCalls = 1

 

WARNING

[WARNING] Trace file name =
orcl1_ora_10046.trc Row number = 31878

SERVICE NAME = (dbhost.us.oracle.com) MODULE NAME = (ac_1_bt) ACTION NAME =
(qryOrder3@qryOrder3) CLIENT ID = (clthost-1199-Default-2-jdbc000183)

Coverage(%) = 66 ProtectedCalls = 2 UnProtectedCalls = 1

 

WARNING

[WARNING] Trace file name =
orcl1_ora_10046.trc Row number = 33240

SERVICE NAME = (dbhost.us.oracle.com) MODULE NAME = (ac_1_bt) ACTION NAME =
(addProduct@getNewProdId) CLIENT ID = (clthost-1199-Default-2-jdbc000183)

Coverage(%) = 66 ProtectedCalls = 2 UnProtectedCalls = 1

 

WARNING

[WARNING] Trace file name =
orcl1_ora_10046.trc Row number = 37963

SERVICE NAME = (dbhost.us.oracle.com) MODULE NAME = (ac_1_bt) ACTION NAME =
(updCustCredLimit@updCustCredLim) CLIENT ID =
(clthost-1199-Default-2-jdbc000183-CLOSED)

Coverage(%) = 66 ProtectedCalls = 2 UnProtectedCalls = 1

 

WARNING

[WARNING] Trace file name =
orcl1_ora_32404.trc Row number = 289

SERVICE NAME = (orcl_pdb1) MODULE NAME = (JDBC Thin Client) ACTION NAME =
null CLIENT ID = null

Coverage(%) = 40 ProtectedCalls = 2 UnProtectedCalls = 3

 

PASS

Report containing checks that
passed:
/home/username/orachk/orachk_dbhost_102415_200912/reports/acchk_scorecard_pass.html

 

If you are not at 100% for all of your trace files, you need to figure out why. Make sure you return connections to the pool, especially after a commit. To figure out exactly what calls are disabling replay or what operations are done after commit, you should turn on replay debugging at the driver side. This is done by running with the debug driver (e.g., ojdbc8_g.jar), setting the command line options -Doracle.jdbc.Trace=true  -Djava.util.logging.config.file=file.properties, and including the following line in the properties file: oracle.jdbc.internal.replay.level=FINEST.

The orachk utility can help you get your application up and running using Application Continuity.

- Get rid of Oracle concrete classes.

- Analyze the database operations in the application to see if any of them are not protected by replay.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.