Oracle® Clinical Remote Data Capture Onsite Administrator's Guide Release 5.1 E53568-01 |
|
|
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:
Several screens in the RDC Onsite application display the name of the 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>
Create or find the registry key OC_RPT_DEBUG and set its value to Y.
Create or 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 registry key OC_RPT_DEBUG 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:
WebLogic Server Logs — These log files are created by WebLogic server as configured in logging.xml.
RDC Onsite Application Logs (Surround and Data Entry Java Logs) — These log files are also created by WebLogic server as configured in logging.xml.
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
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.The WebLogic server by default records logs which contain logs of the deployed applications. You use the following log files when debugging errors:
OpaServer1-diagnostic.log
OpaServer1.log
OpaServer1.out
RDC Onsite stores these log files in the following directory on the application server:
middleware_home\user_projects\domains\OPADomain\servers\OpaServer1\logs
Note:
OpaServer1 is the name of the WebLogic server instance that is created when installing Oracle Clinical Front End.For more information on how to configure the WebLogic server logs, see the Oracle Clinical Administrator's Guide.
For more information on WebLogic servers, see Oracle WebLogic Server 10.3.6 at http://docs.oracle.com/cd/E23943_01/wls.htm
.
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 debug errors pertaining to the RDC Onsite application pages, such as the Home page, Casebooks page, Review CRFs page, PSDV page, etc.)
de (only debug errors pertaining to the RDC Onsite Data Entry window)
all (debug errors pertaining to both the RDC Onsite application pages and the Data Entry window)
https://server.domain/rdcadfsrnd/faces/Login?setUpDone=Y&debug=module-name
https://pharma.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 in the application_path\log defined in the rdcConfig.properties file.
Note:
If a path is not specified for application_path, the default location used is OPA_HOME/log. e.g. C:\opapps51\logIn order to enable the debug information for the errors that occur when using any RDC Onsite application page, the Data Entry window or both, the logging.xml file needs to be updated as follows.
Go to the following location:
middleware_home\user_projects\domains\OPADomain\config\fmwconfig\servers\OpaServer1
Open logging.xml, the logging configuration file and insert the following:
<?xml version='1.0' encoding='UTF-8'?> <logging_configuration> <log_handlers> .. .. <log_handler name='rdchandler' class='oracle.core.ojdl.logging.ODLHandlerFactory' filter='oracle.dfw.incident.IncidentDetectionLogFilter'> <property name='path' value='${domain.home}/servers/${weblogic.Name}/logs/${weblogic.Name}-rdc_1.log'/> <property name='maxFileSize' value='10485760'/> <property name='maxLogSize' value='104857600'/> <property name='encoding' value='UTF-8'/> <property name='useThreadName' value='true'/> <property name='supplementalAttributes' value='J2EE_MODULE.name,composite_name,component_name'/> </log_handler> <log_handler name='dehandler' class='oracle.core.ojdl.logging.ODLHandlerFactory' filter='oracle.dfw.incident.IncidentDetectionLogFilter'> <property name='path' value='${domain.home}/servers/${weblogic.Name}/logs/${weblogic.Name}-de_1.log'/> <property name='maxFileSize' value='10485760'/> <property name='maxLogSize' value='104857600'/> <property name='encoding' value='UTF-8'/> <property name='useThreadName' value='true'/> <property name='supplementalAttributes' value='J2EE_MODULE.name,composite_name,component_name'/> </log_handler> .. .. </log_handlers> <loggers> .. .. <logger name='oracle.pharma.rdc.logging' level='ALL' useParentHandlers='false'> <handler name='rdchandler'/> </logger> <logger name='oracle.pharma.rdc.de' level='ALL' useParentHandlers='false'> <handler name='dehandler'/> </logger> .. .. </loggers> </logging_configuration>
To get the RDC Onsite Surround and the Data Entry logs, add the following parameter to the URL that starts the RDC Onsite application:
?setUpDone=Y&debug=all - to get all debug
?setUpDone=Y&debug=surround - to debug RDC Surround alone
?setUpDone=Y&debug=de - to debug RDC Data Entry alone
After you perform these steps, you can find all the necessary debug information in the ${weblogic.Name}-rdc_1.log and in the ${weblogic.Name}-de_1.log files in the following location:
middleware_home\user_projects\domains\OPADomain\servers\OpaServer1\logs
For example:
C:\oracle\middleware\user_projects\domains\OPADomain\servers\OpaServer1\logs\OpaServer1-rdc_1.log C:\oracle\middleware\user_projects\domains\OPADomain\servers\OpaServer1\logs\OpaServer1-de_1.log
Locate and check the ${weblogic.Name}-rdc_1.log log files for the application pages.
RDC Onsite records all logs against a user identifier that consists of the user name, the database, and the HTTP session ID.
You can locate all the log entries for the user for a particular RDC Onsite session by searching for the HTTP session ID in the log file. The HTTP 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 ${weblogic.Name}-de_1.log log files for the data entry window.
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
When an error occurs while working in the Data Entry window, RDC Onsite displays an error message in the following format:
Table 15-1 describes the types of errors that can occur and the corresponding error_text that displays with the message.
Table 15-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. |
In the case of a fatal failure, RDC Onsite displays the error message and log code information. See Figure 15-1.
Figure 15-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 OpaServer1 log location 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 application_path\log defined in the rdcConfig.properties file.
Note:
If a path is not specified for application_path, the default location used is OPA_HOME\log, for example C:/opapps51/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.
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 inthe application_path\log directory defined in the rdcConfig.properties file.
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.
You can set the level of detail for the Data Entry logs with the value of the parameter level, found in the dataentrylogger.properties file. Any of the following is valid:
FINE
FINER
FINEST
WARNING
SEVERE
To modify the value, perform the following steps:
Login to admin server console for OPADomain and locate olsardc. See Section D.1, "Locating the olsardc.ear File" in Appendix D, "Deploying Customizations." for details.
Open olsardc.ear using any utility to unzip. See Section D.5, "Manually Extracting and Repacking the olsardc.ear File" in Appendix D, "Deploying Customizations." for details.
Navigate to the following path: middleware_home\user_projects\domains\OPADomain\servers\AdminServer\upload\olsardc.ear\RdcS urroundAdfWebUIWebApp.war\WEB-INF\
Open the dataentrylogger.properties file with a text editor, find the parameter level and set the value to FINEST:
level=FINEST
Save your changes.
Re-deploy olsardc. See Section D.2, "Deleting the Existing Deployment" in Appendix D, "Deploying Customizations." for details.
Restart the OpaServer. See Section D.3, "Redeploying a Version with Customizations" in Appendix D, "Deploying Customizations." for details.
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 application_path\log directory.
The dump files has several key sections to help with troubleshooting.
As shown in Example 15-1, the first long alphanumeric string in the first section provides the following important identifiers:
The HTTP session ID for the user
The user name and database
The Window Context session ID for the Data Entry window where the failure happened
The time stamp for the DCAPI log
Example 15-1 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 ${weblogic.Name}-de_1.log (as configured in logging.xml) for all relevant entries. You use the time stamp to locate the DCAPI log files. See Section 15.4.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) . . .
jvmid=1
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 instance running WebLogic Admin Server. These log files help when troubleshooting issues with launching data entry sessions.
To enable DCAPI framework logging:
Login to admin server console for OPADomain and locate olsardc. See Section D.1, "Locating the olsardc.ear File" in Appendix D, "Deploying Customizations." for details.
Open olsardc.ear using any utility to unzip. See Section D.5, "Manually Extracting and Repacking the olsardc.ear File" in Appendix D, "Deploying Customizations." for details.
Navigate to the following path: middleware_home\user_projects\domains\OPADomain\servers\AdminServer\upload\olsardc.ear\RdcS urroundAdfWebUIWebApp.war\WEB-INF\
Locate and open dcapi.properties 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.
Re-deploy olsardc. See Section D.2, "Deleting the Existing Deployment" in Appendix D, "Deploying Customizations." for details.
Restart the OpaServer. See Section D.3, "Redeploying a Version with Customizations" in Appendix D, "Deploying Customizations." for details.
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.)
Table 15-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.
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 application_path\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 folder as configured in the application_path folder as configured in rdcConfig.properties file. 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:
Navigate to OPA_CONFIG_FOLDER. Its path comes from registry entry opa51 under HKEY_LOCAL_MACHINE > Software > Oracle > opa51.
Open the rdcConfig.properties file.
Set the performanceprofile parameter value to 1.
Save your changes.
Restart the OpaServer. See Section D.4, "Restarting the OpaServer" in "Deploying Customizations" for details.
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:
Login to admin server console for OPADomain and locate olsardc. See Section D.1, "Locating the olsardc.ear File" in Appendix D, "Deploying Customizations." for details.
Open olsardc.ear using any utility to unzip. See Section D.5, "Manually Extracting and Repacking the olsardc.ear File" in Appendix D, "Deploying Customizations." for details.
Navigate to the following path: middleware_home\user_projects\domains\OPADomain\servers\AdminServer\upload\olsardc.ear\RdcS urroundAdfWebUIWebApp.war\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.
Re-deploy olsardc. See Section D.2, "Deleting the Existing Deployment" in Appendix D, "Deploying Customizations." for details.
Restart the OpaServer. See Section D.3, "Redeploying a Version with Customizations" in Appendix D, "Deploying Customizations." for details.
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 application_path\log folder defined in rdcConfig.properties file.
For each instance running, RDC Onsite creates a new folder in the application_path\log folder:
opasensorreport_n
where n is the 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 Server was started. The second column represents the number (metric) that is being tracked.