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.

Starting in version 12.1.0.2.5, the Oracle concrete class checking has been enhanced to recursively expand .ear, .war, and .rar files in addition to .jar files. You no longer need to explode these archives into a directory for checking. This is a big simplification for customers using Java EE applications. Just specify the root directory for your application when setting the command line option -appjar dirname or the environment variable RAT_AC_JARDIR. The orachk utility will do the analysis.

This article will focus a second analysis that can be using Orachk to see if your application workload will be covered by AC. There are three values that control the AC checking (called acchk in orachk) for coverage analysis. Two of them are the same as concrete class checking. The third is different but can be combined to get both checks done in one run. 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

–asmhome jarfilename  

RAT_AC_ASMJAR

This must point to a version of asm-all-5.0.3.jar
that you download from http://asm.ow2.org/.

-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 only since AC
was introduced in that release.

None

RAT_ACTRACEFILE_WINDOW

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.

In addition, you need to turn on a specific tracing flag on the database server to see RDBMS-side program interfaces for AC.

You can turn it on programmatically for a single session using a java.sql.Connection by running something like

Statement statement = conn.createStatement();
statement.executeUpdate("alter session set events 'trace [progint_appcont_rdbms]' ");

More likely, you will want to turn it on for all sessions.  Before running the workload, you need to 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.

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

Then run a shutdown immediate; and startup; on the instance.

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. If you 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 on this topic. 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., ojdbc7_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.