| Oracle® Clinical Remote Data Capture Onsite Administrator's Guide Release 5.0.1 E37004-02 |
|
|
PDF · Mobi · ePub |
| Oracle® Clinical Remote Data Capture Onsite Administrator's Guide Release 5.0.1 E37004-02 |
|
|
PDF · Mobi · ePub |
If you encounter problems in RDC Onsite, Oracle Support may ask you to collect diagnostic information from the application. There are various diagnostics that can be enabled.
Oracle Support provides instructions on the traces you need to collect depending on the type of error you encounter. This chapter provides instructions on how to collect the various trace files and log files for analysis by Oracle Support.
This chapter includes the following topics:
To enable a SQL trace for searches (queries) executed during a user session, add the &sqlTrace=true parameter to the URL that starts the RDC Onsite application.
For example:
https://server.domain/rdcadfsrnd/faces/Login?setupDone=Y&sqlTrace=true
Note:
If you need a SQL trace for the Data Entry window, you must enable the trace at the user level by a login trigger. Contact Oracle Support for instructions and assistance with this type of trace.Several screens in the RDC Onsite application display the name of the a CRF (document) in the CRF Name column. Recall that the terms CRF (RDC Onsite) and document (Oracle Clinical) are synonyms and used interchangeably.
To assist you with debugging some errors, you can choose to display the document (CRF) number in addition to the document (CRF) name.
To display the document number, specify the &display_docnum=Y parameter in the URL that starts the RDC Onsite application. For example:
https://server.domain/rdcadfsrnd/faces/Login?setupDone=Y&display_docnum=Y
When you set the &display_docnum parameter, the RDC Onsite application inserts a CRF Number column to the right of the CRF Name column:
On the Review CRFs page
On the Review Discrepancies page
In the Discrepancy Details window
On the Review Investigator Comments page
Configuring the &display_docnum parameter is not dependent on enabling the debug feature for other modules.
To display the discrepancy identifier (ID), add the following parameter to the URL that starts the RDC Onsite application:
&display_descpId=Y
For example:
https://server.domain/rdcadfsrnd/faces/Login?setupDone=Y&display_descpId=Y
When you set the &display_descpId parameter, RDC Onsite adds a Discr ID column to the Review Discrepancies page and the Discrepancy Details window. The Discr ID column displays to the right of the CRF Number column.
Configuring the &display_descpId parameter is not dependent on enabling the debug feature for other modules.
To enable the debugging feature for the Patient Data Report:
Log in to the Reports Server.
Stop the Reports Service.
Open the Windows Registry Editor:
Click Start and then select Run.
Type regedit and then click OK.
Navigate to the following location in the registry:
HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\OH_<NUMBER>
Find the registry key OC_RPT_DEBUG and set its value to Y.
Find the registry key OC_RPT_DEBUG_TMP_FOLDER. Set its value to the directory where RDC Onsite will create and store the temporary files for debugging the Patient Data Report. For better performance, Oracle recommends setting the value to a directory on the Reports Server.
Restart the Reports Service.
Submit the request to generate the Patient Data Report.
When you set OC_RPT_DEBUG = Y, RDC Onsite does not delete the records in the following temporary tables when it finishes generating the Patient Data Report:
PDR_TEMP
PDR_SUPERSCRIPTS
PDR_AUDIT_TEMP
In addition, RDC Onsite does not delete the PDR temporary files stored in the directory defined by the OC_RPT_DEBUG_TMP_FOLDER registry key.
When you are finished debugging the Patient Data Report, be sure to turn off the report debugging feature so your system does not accumulate temporary tables and files for every Patient Data Report generated.
To disable the report debugging feature, return to the Windows Registry Editor and change the value of the OC_RPT_DEBUG key to N.
Note:
The jlog file is located in the user's Reports Server Log directory. RDC Onsite creates this file regardless of the value set for the OC_RPT_DEBUG registry key.RDC Onsite provides the following logging files:
Application Pages Java Logs — The default size is 10 MB, and the total log folder size is 100 MB.
Data Entry Java Logs — These logs are subject to the same size limits as the logs for the application pages, unless you set up a separate log file for data entry.
Data Capture Logs — 3 per Data Capture session. Note that due to DCAPI caching, the number of logs is not always related directly to the number of Data Entry windows the user opens. If a DCAPI instance is cached after the first window is closed and reused for another window, the log files will contain entries for the second window.
In addition to these session-based log files, the DCAPI framework generates two log files of its own. These files contain mainly logs from the framework code that launches and manages DCAPI instances. These log files are helpful for troubleshooting issues with launching data entry sessions.
Performance Profile Logs
Scalability Logs
When an error occurs while working in the Data Entry window, RDC Onsite displays an error message in the following format:
Table 14-1 describes the types of errors that can occur and the corresponding error_text that displays with the message.
Table 14-1 Errors and the Text Added to the Message
| Type of Error | Text Added to the Message |
|---|---|
|
Network drop, error from Internet Explorer, or error from the Application Server |
XMLHttp error code error_number, (additional_error_text) Note that under most circumstances, RDC Onsite handles a momentary network drop, and displays a different message that presents a Retry option to the user. However, in some cases, a network drop results in the Data Entry window shutting down. |
|
Error in the data entry code |
Log code error_number, internal error. |
|
Error in the DCAPI |
Log code error_number, data capture error. |
RDC Onsite records all log information for both the application pages and the Data Entry window as part of the OC4J logs. You use the following log files when debugging errors:
OpaServer1-diagnostic.log
OpaServer1.log
OpaServer.out
RDC Onsite stores these log files in the following directory on the application server:
C:\app\oracle\middleware\user_projects\domains\OPADomain\servers\OpaServer1\logs
You can collect debug information for errors that occur when using any of the RDC Onsite application pages and when using the Data Entry window.
To collect this debug information, add the &debug parameter to your URL that starts the RDC Onsite application:
&debug=module-name
where module-name defines the type of debugging you want.
Valid entries for module-name:
surround (only debugs errors pertaining to the application pages, such as the Home page, Casebooks page, and Review CRFs page)
de (only debugs errors pertaining to the Data Entry window)
all (debugs errors pertaining to both the application pages and the Data Entry window)
https://server.domain/rdcadfsrnd/faces/Login?setUpDone=Y&debug=module-name
https://ORACLE.com/rdcadfsrnd/faces/Login?setupDone=Y&debug=de
https://pharma1.usa.atlantic.com/rdcadfsrnd/faces/Login?setupDone=Y&debug=all
On using application with debug turned on (setUpDone=Y&debug=module), the debug logs would be created in the below mentioned locations:
RDC Onsite surround and data entry logs in C:\opapps50\log
Performance logs in C:\\opapps50\rdc\logs
RDC Onsite records all logs against a user identifier that consists of the user name, the database, and the HTTP session ID.
Example 14-1 shows a portion of a sample log from the RDC Onsite application pages. The actual log text is the text enclosed by the <MSG_TEXT> tag.
Example 14-1 Sample Log from RDC Onsite Application Pages
<MESSAGE>
<HEADER>
<TSTZ_ORIGINATING>2009-07-15T14:27:57.968-07:00</TSTZ_ORIGINATING>
<COMPONENT_ID>pharma</COMPONENT_ID>
<MSG_TYPE TYPE="TRACE"></MSG_TYPE>
<MSG_LEVEL>9</MSG_LEVEL>
<HOST_ID>ap7010pha</HOST_ID>
<HOST_NWADDR>140.87.92.79</HOST_NWADDR>
<MODULE_ID>rdc.logging.RdcLogger</MODULE_ID>
<THREAD_ID>13</THREAD_ID>
<USER_ID>SYSTEM</USER_ID>
</HEADER>
<CORRELATION_DATA>
<EXEC_CONTEXT_ID><UNIQUE_ID>5018554431287</UNIQUE_ID><SEQ>2</SEQ></EXEC_CONTEXT_ID> </CORRELATION_DATA>
<PAYLOAD>
<MSG_TEXT>[user@database:e78e5b0fabf40558fdaa63b644191 eefef023608b49bcf0f8e3188f9d301258e] RdcLoginAction: Trying to obtain binding container.</MSG_TEXT>
</PAYLOAD>
</MESSAGE>
You can locate all the log entries for the user for a particular RDC Onsite session by searching for the session ID in the log file. As shown in Example 14-1, the session ID is the alphanumeric string that follows the user@database information in the <MSG_TEXT> tag.
RDC Onsite records all logs against a user identifier that consists of the user name, the database, and the HTTP session ID.
To review the information in the data entry logs:
Locate and check the log files for the application pages. See Section 14.5.4, "Reviewing the Log Entries for the RDC Onsite Application Pages" for more information.
Use the same session ID to locate the data entry logs.
When the user opens a Data Entry window, RDC Onsite assigns a unique ID to the window. In addition, RDC Onsite creates a log entry against the user's HTTP session ID.
You can locate all data entry logs relevant to the user for the data entry session using the HTTP session ID and the Window context ID. The following example highlights these IDs in bold.
[9e46412a075dc5104ec7e9a06b704bbfb121525115d20e641d6835974ac786e8] Window context Id for this CRF: 4750992751934458
In the case of a fatal failure, RDC Onsite displays the error message and log code information. See Figure 14-1.
Figure 14-1 Fatal Error Dialog Box with Log Code information
When the error occurs, the RDC Onsite user should record the log code number and the error text, and then report the information to you. For example:
Log code 9522631529, data capture error.
You can use the log code to search the log file and get more details on the error. Two important notes:
The exact code can be in any one of the log files in the log folder.
The particular log file that contains the log code may be deleted if you do not read the log within a reasonable time after the failure because the log size limits can force the logger to delete log files and create new files to accommodate new logs.
Note:
In case of critical errors or failures in the Data Entry window, RDC Onsite automatically generates a log entry even if you did not enable logging from the URL. RDC Onsite users should always record the log code when the error occurs. Subsequently, you can use the log code to reference additional information about the error.Every data entry session is supported by a data capture engine running on the middle tier for that session. This engine consists of the following parts:
A Java layer
A process (olsadcapiservice.exe)
A DLL (olsadcapi.dll) loaded by the process
Each part generates a log file when logging is enabled.
DCAPI log files contain internal technical messages that may be meaningful to Oracle support and development only.
The DCAPI log files are located as defined in the RdcConfig.properties file. By default, they are placed in the following directory:
OPA_HOME\log
The name of these log files use the following format:
Java layer: DcapiJava_user-name_date-time.dbg
Process layer: DcapiExec_user-name_date-time.dbg
DLL layer: DcapiHtml_user-name_date-time.dbg
where:
user-name is the user's login ID.
date-time is the date and time of the event. For example, 2009Aug15134550236.
You can enable RDC Onsite to generate DCAPI framework logs that capture logs from the common code that creates, manages, and closes DCAPI instances. The DCAPI generates two log files for each JVM instance running WebLogic Admin Server. These log files help when troubleshooting issues with launching data entry sessions.
To enable DCAPI framework logging:
Stop the WebLogic Admin Server.
Log in to the RDC Onsite application server.
Navigate to OPA_CONFIG_FOLDER. Its path comes from registry entry opa50 under HKEY_LOCAL_MACHINE > Software > Oracle > opa50.
Open the dcapi.properties, located at \olsardc.ear\RdcSurroundAdfWebUIWebApp.war\WEB-INF\, with a text editor.
Find the following parameter and set the value to 1:
frameworklog=1
Find the following parameter:
frameworkloglocation=
Specify the location for the DCAPI framework log files. For example, if you want the DCAPI to save the framework log files in the RDC log folder, set the parameter as follows:
frameworkloglocation=drive:\\RDC_HOME\\log
Note that you must specify the double forward slash throughout the directory path. Otherwise, the Java APIs read the single slash as an escape character.
Save your changes.
Restart the WebLogic Admin Server.
Once you log in to RDC Onsite and open a CRF, the DCAPI generates the framework log files and continuously adds logs to the files. The names for the framework log files use the following format:
OHSA_DCAPI_Framework_Java_n.log
OHSA_DCAPI_Framework_Native_n.log
where n is the JVM instance number. (If a single JVM is running the OC4J instance, then n is 1.)
A fatal failure in a data entry session always generates a dump file on the middle tier that contains information relevant to the failure. This information will help Oracle support and developers troubleshoot issues.
The name of the dump file uses the following format:
logcode.dump
where logcode is the log code that appears in the Data Entry window in case of a fatal failure.
RDC Onsite creates this file on the middle tier in the RDC_HOME\log directory.
RDC Onsite always creates dump files in the case of a fatal failure in data entry, with or without logging enabled. However, it is helpful to Oracle support if you generate and gather more information by enabling logging for data entry. For critical errors, Oracle suggests that you set the data entry log level to FINEST, and then reproduce the failure to generate the maximum amount of log information.
When a fatal failure occurs in a data entry session, the RDC Onsite user should note the log code and report it to you. You can use the log code to locate the dump file in the RDC_HOME\log directory.
The dump files has several key sections to help with troubleshooting.
As shown in Example 14-2, the first long alphanumeric string in the first section provides the following important identifiers:
The session ID for the user
The user name and database
The session ID for the Data Entry window where the failure happened
The time stamp for the DCAPI log
Example 14-2 Important Identifiers in the Dump File
#Starting dump of context parameters for failureId: 9522631529
#---------------------------------------------------------------
refids=0a957842231c103dc782a58e44a49c2089684b16a007, <user>@<database>,28905006072188144,2009Jul15161040954
You use the user's session ID, the user name, the database, and the window session ID to search the OC4J logs (log.xml) for all relevant entries. You use the time stamp to locate the DCAPI log files. See Section 14.5.7, "Data Capture API (DCAPI) Logs" for more information.
The next section of the log file lists the actual exception stack.
#---------------------------------------------------------------
Exception Details:Error in DCAPI Module.
oracle.pharma.rdc.de.exception.FailedOperationException: Error in DCAPI Module.
at
oracle.pharma.rdc.de.exception.FailedOperationException.<init>(FailedOperationException.java:75)
at
oracle.pharma.rdc.de.service.dcs.DciFormData.doFieldUpdate(DciFormData.java:6274)
.
.
.
The section that follows contains the JVM instance number serving the user. This number is important when OC4J is running in a multi-JVM environment because you can use the number to easily locate the OC4J log files.
#--------------------------------------------------------------- jvmid=1
The remaining sections in the file provide the JVM parameters and environment, CRF, Study, Site, and other details that can aid in troubleshooting.
Table 14-2 lists the additional log files that Oracle Support may request when working with you to debug or troubleshoot an error. You do not need to configure any settings to generate these log files. RDC Onsite automatically creates these files on the application server and continuously collects debug information.
Table 14-3 provides a mapping of the RDC Onsite 5.0.0 logs to their counterpart in RDC Onsite 4.6.2, RDC Onsite 4.6 and RDC Onsite 4.5.3.
Table 14-3 Comparison of the Log Files in RDC Onsite 5.0.0, 4.6.2, 4.6, and 4.5.3
| Log Files | Location |
|---|---|
|
RDC Onsite application pages |
RDC Onsite 4.6.2 ORACLE_AS10gR3_HOME\j2ee\rdc\log\rdc_default_group_n\oc4j\log.xml where n is the JVM instance |
|
RDC Onsite 4.6 ORACLE_AS10gR2_HOME\j2ee\rdc\log\rdc_default_island_n\oc4j\log.xml where n is the JVM instance |
|
|
RDC Onsite 4.5.3 RDC_Home\log\RdcOnsite0.xml |
|
|
RDC Onsite 5.0.0 C:\app\oracle\middleware\user_projects\domains\OPADomain\servers\OpaServer1\logs\OpaServer1.out C:\app\oracle\middleware\user_projects\domains\OPADomain\servers\OpaServer1\logs\OpaServer1-diagnostic.log C:\app\oracle\middleware\user_projects\domains\OPADomain\servers\OpaServer1\logs\ OpaServer1.log |
|
|
Data entry |
RDC Onsite 4.6.2 (if set up with the log files for the application pages) ORACLE_AS10gR3_HOME\j2ee\rdc\log\rdc_default_group_n\oc4j\log.xml where n is the JVM instance RDC Onsite 4.6.2 (if set up separately) ORACLE_AS10gR3_HOME\j2ee\rdc\log\rdc_default_group_n\oc4j\de\log.xml where n is the JVM instance |
|
RDC Onsite 4.6 (if set up with the log files for the application pages) ORACLE_AS10gR2_HOME\j2ee\rdc\log\rdc_default_island_n\oc4j\log.xml where n is the JVM instance RDC Onsite 4.6 (if set up separately) ORACLE_AS10gR2_HOME\j2ee\rdc\log\rdc_default_island_n\oc4j\de\log.xml where n is the JVM instance |
|
|
RDC Onsite 4.5.3 RDC_Home\log\delog0.log |
|
|
RDC Onsite 5.0.0 Dataentry_log_path configured in RdcConfig.properties or drive:\C:\opapps50\log |
|
|
Data Capture API (Java Log) |
RDC Onsite 4.6.2 and RDC Onsite 4.6 RDC_Home\log\DcapiJava_user-name_date-time.dbg RDC Onsite 4.5.3 RDC_Home\log\DcapiJava_user-name_number.dbg RDC Onsite 5.0.0 Dataentry_log_path configured in RdcConfig.properties or drive:\C:\opapps50\log |
|
Data Capture API (Process Log) |
RDC Onsite 4.6.2 and RDC Onsite 4.6 RDC_Home\log\DcapiExec_user-name_date-time.dbg RDC Onsite 4.5.3 RDC_Home\log\log-number.log RDC Onsite 5.0.0 Dataentry_log_path configured in RdcConfig.properties or drive:\C:\opapps50\log |
|
Data Capture API (DLL Log) |
RDC Onsite 4.6.2 and RDC Onsite 4.6 RDC_Home\log\DcapiHtml_user-name_date-time.dbg RDC Onsite 4.5.3 RDC_Home\log\DcapiPdf_user-name_number.dbg RDC Onsite 5.0.0 Dataentry_log_path configured in RdcConfig.properties or drive:\C:\opapps50\log |
Performance profiling can provide Oracle Support with diagnostic information for all the activities that are conducted in the Data Entry window for a particular user session.
In addition to the log files for the application pages and for data entry, RDC Onsite lets you monitor performance in different parts of the code. RDC Onsite supports performance profiling for the data entry client and for the data entry server code.
You can monitor the performance of specific requests from the data entry client user interface to get an overall idea of the time spent in different parts of the code.
To profile a single user session:
Start an RDC Onsite session using the following URL:
https://server.domain/rdcadfsrnd/faces/Login?setupDone=Y&deparams=profile:1
Open a CRF where you are seeing the problem of interest. Note that because profiling is turned on, RDC Onsite adds the View Profile link to the session information line above the tool bar:
Execute the problematic scenario.
Click the View Profile link. RDC Onsite displays the client profile logs in a separate window. Note that the log shows the times spent on the client in different parts of the JavaScript code including network round-trip times.
Copy and paste information from the View Profile window into a text file that you can forward to Oracle Support. (This information is related only to actions around opening the CRF.)
Collect the log information and forward to Oracle Support. This includes:
Content of the View Profile windows that you copied into a text file.
Content of the RDC_HOME\log\requestprofilelog.xml file located on the application server.
On the server side, RDC Onsite also creates a new log entry for the same request in the requestprofilelog.xml in the RDC_HOME\log folder. This log entry breaks down the time spent on the server side for the same request in different parts of the code. For example:
<request id="1">
<user>user@database</user>
<windowcontext>50645505678382780</windowcontext>
<profiles>
<profile name="generateRDciData">484</profile>
<profile name="loadDciForm">156</profile>
<profile name="cmdDocData">656</profile>
<profile name="cmdPostInitialLoad">94</profile>
<profile name="cmdGetSettings">94</profile>
<profile name="cmdOpenConfirm">0</profile>
<profile name="RuntimeController">922</profile>
</profiles>
</request>
A combination of the client profile data and server profile data gives a complete picture of a request-response life cycle that originated from the data entry client code.
Another kind of profiling supported by the data entry code gives the average, minimum, and maximum times spent in specific portions of the server code over time and across multiple data entry users. All time values are in milliseconds.
To enable server profiling:
Stop the WebLogic Admin Server instance.
Log in to the RDC Onsite application server.
Navigate to the following directory:
ORACLE_AS11gR2_HOME\j2ee\rdc\applications\olsardc\rdconsite\WEB-INF
Open the web.xml file with a text editor.
Insert the following lines into the file:
<context-param> <param-name>performanceprofile</param-name> <param-value>1</param-value></context-param>
Make sure the parameter value is set to 1 to enable profiling. Any other value disables the profiling feature. In addition, make sure the XML syntax is preserved when you insert these lines.
Save your changes.
Restart the WebLogic Admin Server.
Start the RDC Onsite application, and the open a CRF in the Data Entry window.
Because you enabled server profiling, RDC Onsite adds the Server Profile link to the session information line above the toolbar in the Data Entry window: 
Description of the illustration debug_perfprofile4.gif
When you click the Server Profile link, RDC Onsite opens a separate window with data about the server profile.
The server profile data includes the Profile Name, the number of calls, and the minimum, maximum, and average time. All time values are in milliseconds. For example:
RDC Onsite provides the capability to track the change in certain data related to the scalability of the system. When you enable this feature, RDC Onsite tracks the following metrics:
Number of RDC Onsite users
Number of Business Components for Java (BC4J) application modules
Number of data entry sessions
Number of DCAPI instances
To enable tracking of scalability:
Stop the WebLogic Admin Server.
Log in to the RDC Onsite application server.
Navigate to the following directory:
ORACLE_AS11gR2_HOME\j2ee\rdc\applications\olsardc\rdconsite\WEB-INF
Open the web.xml file with a text editor.
Insert the following lines into the file:
<context-param> <param-name>enablesensor</param-name> <param-value>1</param-value></context-param>
Make sure the XML syntax is preserved when you insert these lines.
Save your changes.
Restart the WebLogic Admin Server.
Once you enable tracking of scalability data, RDC Onsite will generate sensor reports at specific intervals. The sensor reports are CSV files. RDC Onsite saves the files in the RDC log folder (RDC_HOME\log).
For each JVM running the WebLogic Admin Server, RDC Onsite creates a new folder in the RDC log folder:
opasensorreport_n
where n is the JVM instance number.
The opasensorreport_n folder has four files that correspond to the metrics collected:
NumberOfRdcUsers.csv — number of RDC Onsite users
RdcAM.csv — number of BC4J application modules
NumberOfDEWindows.csv — number of data entry sessions
NumberOfDcapi.csv — number of DCAPI instances
Each file records a new entry whenever an event that triggers a change in value occurs, for example, when a user logs in or logs out. Note that RDC Onsite updates the files only at specific intervals (every 10 minutes). Therefore, the files may not always reflect the latest data.
In each file, the first column is the number of milliseconds since the WebLogic Admin Server was started. The second column represents the number (metric) that is being tracked.
|
 Copyright © 2007, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|