| Oracle® Fusion Applications Administrator's Guide 11g Release 6 Refresh 4 (11.1.6) Part Number E14496-14 |
|
|
PDF · Mobi · ePub |
| Oracle® Fusion Applications Administrator's Guide 11g Release 6 Refresh 4 (11.1.6) Part Number E14496-14 |
|
|
PDF · Mobi · ePub |
This chapter describes how to use diagnostics tests to support normal operations for Oracle Fusion Applications and to prepare for future troubleshooting.
This chapter contains the following topics:
Section 16.2, "Configuring the Diagnostic Testing Framework for Normal Operation"
Section 16.3, "Using Diagnostic Tests to Monitor Normal System Health"
For information about troubleshooting using diagnostic tests, incidents, log files, and QuickTrace, see Chapter 17. For more information about using incidents, log files, and QuickTrace during normal operation see Chapter 15.
Diagnostic tests are executables that are designed to exercise particular aspects of Oracle Fusion applications, to determine whether they are operating correctly and to help identify and resolve any problems. The Oracle Fusion Applications Diagnostic Testing Framework (Diagnostic Testing Framework) lets you execute diagnostic tests and collects the results into detailed diagnostic reports. Oracle provides diagnostics tests that are installed along with Oracle Fusion Applications releases and patches.
This section contains the following topics:
Section 16.1.1, "Relationships Between Diagnostic Tests, Incidents, and Log Messages"
Section 16.1.2, "Standard Diagnostic Testing Administration Tasks and Tools"
Oracle developers create diagnostic tests that you can use to help diagnose and resolve Oracle Fusion application problems.
Oracle developers use mechanisms such as application programming interface (API) calls in Oracle Fusion Applications code to record application operations in log files and to provide error messages as appropriate. A diagnostic test may or may not be associated with a particular error message.
If an Oracle Fusion application handles a particular error in a way that triggers the creation of an incident, then any diagnostic tests that are associated with the error message for the incident run automatically. Oracle developers accomplish this by setting the value of each diagnostic test's APPS_MSG_ID tag to match the identifier of any error message that should trigger the automatic execution of that test. There is no configuration setting for disabling this automatic execution of diagnostic tests.
The results of any automatically run diagnostic test are automatically associated with the related incident, and the identity of the user who received the error message is recorded.
For more information about using diagnostic tests specifically for troubleshooting, see and Chapter 17.
For more information about using logs to help diagnose a problem, see Chapter 17. For more information about configuring and using log files during normal operation, see Chapter 15.
It is important to be familiar with the following additional concept that is related to diagnostic tests:
Seed data is information that Oracle provides to you in the form of database records. Diagnostic tests are included in seed data.
Under ordinary circumstances, the following administrative tasks are associated with Oracle Fusion Applications diagnostic tests:
Configuring security to provide appropriate access to diagnostic tests. You can assign job roles to particular users to grant those users the ability to perform various diagnostic operations. For more information, see Section 16.2.1.
Note:
In the current release, a job role for diagnostic operations grants the user the ability to perform the specified operations for all diagnostic tests that are provided with Oracle Fusion Applications. When choosing whether to grant a diagnostic job role to specific users, be aware that some diagnostic tests may include sensitive information in their results.
Running diagnostic tests. You can use diagnostic tests for the following purposes:
Routinely checking the health of your Oracle Fusion applications
Troubleshooting a problem with an Oracle Fusion application
Collecting detailed data that may help Oracle Support to resolve a problem for you
Some diagnostic tests require a specific Oracle Fusion application to be running while the test is performed—these diagnostic tests are called internal diagnostic tests. Other diagnostic tests can perform their functions even if the Oracle Fusion application to be tested is not running—these tests are called external diagnostic tests.
The distinction between internal and external tests is important because it affects both when you can run the tests and which interfaces you can use to run the tests. The Diagnostic Testing Framework provides two interfaces:
The Diagnostic Dashboard application provides a graphical user interface that lets you perform the following tasks:
Execute and monitor both internal and external diagnostic tests for Oracle Fusion applications
Purge diagnostic test results
Register any special-purpose diagnostic tests that Oracle Support may provide to you
The diagctl command-line interface lets you perform the following tasks:
Execute external diagnostic tests (tests that do not require a specific Oracle Fusion application to be running)
Note:
Technical constraints prevent the diagctl command-line interface from returning useful results for internal diagnostic tests (tests that require a specific Oracle Fusion application to be running when the test is performed). You must use the Diagnostic Dashboard to run any internal diagnostic tests.
You must also use the Diagnostic Dashboard to determine whether a particular test is an internal or an external test. For more information about making this determination, see Step 9 through Step 11 in Section 16.3.1.1.
View diagnostic test results
Register any special-purpose diagnostic tests that Oracle Support may provide to you
You can use diagnostic tests to check normal system health and to troubleshoot system problems. You can configure your Oracle Fusion Applications environment to run all Oracle Fusion Applications diagnostic tests using the Diagnostic Dashboard application, and to run external diagnostic tests using the diagctl command-line interface.
This section contains the following topics:
Note:
Technical constraints prevent the diagctl command-line interface from returning useful results for internal diagnostic tests (tests that require a specific Oracle Fusion application to be running when the test is performed). You must use the Diagnostic Dashboard to run any internal diagnostic tests.
You must also use the Diagnostic Dashboard to determine whether a particular test is an internal or an external test. For more information about making this determination, see Step 9 through Step 11 in Section 16.3.1.1.
Both the Diagnostic Dashboard application and the diagctl command-line interface are automatically installed and configured as part of the Oracle Fusion Applications installation. However, you must assign appropriate job roles to specific users to give them the ability to display and perform operations using the Diagnostic Dashboard application. Access to the diagctl command-line interface is controlled at the level of the server operating system. For more information about granting appropriate access, see Section 16.2.1.
To help you locate diagnostic tests for specific purposes, the diagnostic tests that you receive with Oracle Fusion applications are all assigned to predefined categories.
Note:
You cannot change the tag name and tag value assignments that Oracle uses to categorize diagnostic tests, and you cannot remove those tag names or tag values from the database. The following related links in the Task pane of the Diagnostic Dashboard application are intended for use by Oracle personnel only:
Add New Tag
Add New Tag Value
Assign Tags to Tests
Unassign Tags from Tests
Remove Tag
Remove Tag Value
Caution:
Do not attempt to modify the diagnostic test seed data provided to you by Oracle. Unauthorized modification of this seed data may prevent diagnostic tests from functioning correctly, lengthening the amount of time required to resolve both current and future problems.
Access to diagnostic testing functionality is controlled separately for the Diagnostic Dashboard and the diagctl command-line interface.
For the diagctl command-line interface, access is controlled at the level of the server operating system. If a user can log in to the server where diagctl is stored, and if that user has operating system permissions to read and execute diagctl, then that user can use diagctl to perform all diagnostic operations that the command-line interface supports.
For the Diagnostic Dashboard, you can use Oracle Identity Manager to assign specific users to any of the four preconfigured job roles that grant users access to the Diagnostic Dashboard. Each of these four job roles provides access to a different amount of the functionality of the dashboard.
Note:
Oracle Fusion applications display the Troubleshooting > Run Diagnostic Tests command in the Help menu only for users who are associated with the preconfigured job roles that grant access to Diagnostic Dashboard operations.
The Diagnostic Viewer job role can view and analyze diagnostic test results for Oracle Fusion applications.
The Diagnostic Regular User job role can execute diagnostic test runs and view diagnostic test results for Oracle Fusion applications, and cancel diagnostic test runs that were started by the current user.
The Diagnostic Advanced User job role can schedule and execute diagnostic test runs, view diagnostic test results, attach test results to application incidents for Oracle Fusion applications, and cancel diagnostic test runs that were started by the current user. In general, this job role is recommended for running Oracle Fusion Applications diagnostic tests, because its added capabilities allow users to work with administrators more flexibly during troubleshooting.
The Diagnostic Administrator job role can use all of the diagnostic testing functionality provided for Oracle Fusion applications, including purging test results from the database and canceling test runs started by other users.
Note:
In the current release, any job role for diagnostic operations grants the user the ability to perform the role's specified operations for all diagnostic tests that are provided with Oracle Fusion applications. When choosing whether to grant any diagnostic job role to specific users, be aware that some diagnostic tests may include sensitive information in their results.
To grant specific users permission to use the Diagnostic Dashboard:
Decide which users need the capabilities of each of the four preconfigured job roles for diagnostic operations.
Use Oracle Identity Manager to assign the appropriate job role to each user.
The Diagnostic Dashboard application for Oracle Fusion Applications provides a graphical user interface that lets you execute and monitor diagnostic tests, display and purge test results, and register any special-purpose diagnostic tests that Oracle Support may provide to you. Each product family within Oracle Fusion Applications has its own instance of the Diagnostic Dashboard. Provided that you are assigned to an appropriate job role, you can navigate to the Diagnostic Dashboard from any Oracle Fusion application or from Oracle Enterprise Manager Cloud Control (Cloud Control).
If you want to use the Diagnostic Dashboard to execute or monitor diagnostic tests or display or purge test results while you are using an Oracle Fusion application, you can navigate to the Diagnostic Dashboard directly from the application.
To display to the Diagnostic Dashboard from an Oracle Fusion application:
Sign in to the relevant Oracle Fusion application as a user who has access to the specific Diagnostic Dashboard operations that you need.
For more information about the job roles that grant access to Diagnostic Dashboard operations, see Section 16.2.1.
From the Help menu in the application, choose Troubleshooting > Run Diagnostic Tests to display the Diagnostic Dashboard.
Note:
Oracle Fusion applications display the Troubleshooting > Run Diagnostic Tests command in the Help menu only for users who are assigned to the preconfigured jobs roles that grant access to Diagnostic Dashboard operations. For more information about these job roles, see Section 16.2.1.
If you want to use the Diagnostic Dashboard to execute or monitor diagnostic tests or display or purge test results while you are using Cloud Control, such as while you are using Support Workbench to gather additional information about an existing incident, you can navigate to the Diagnostic Dashboard directly from Cloud Control.
To display to the Diagnostic Dashboard from Cloud Control:
In Oracle Enterprise Manager, select the product family or cluster application for which you want to run diagnostic tests or view diagnostic test results.
From the dynamic dropdown menu, choose Diagnostics > Fusion Applications Diagnostic Dashboard.
A login screen for the Diagnostic Dashboard appears in a new window.
Log in using an account for the Oracle Fusion Applications product family that you intend to test.
The account that you use must also be assigned to a job role that provides access to the Diagnostic Dashboard. For more information, see Section 16.2.1.
Oracle Fusion Applications diagnostic tests are designed to help you to monitor the health of your system and to help you troubleshoot when necessary.
This section contains the following topics:
Section 16.3.2, "Searching for Diagnostic Tests by Name, Categorization Tag, or Module"
Section 16.3.4, "Providing Input Parameters for Diagnostic Tests"
Section 16.3.10, "Identifying Diagnostic Test Start Methods from Test Run Names"
Section 16.3.11, "Purging the Results of Selected Diagnostic Test Runs"
Note:
The user name that you use to sign in to an Oracle Fusion application affects which diagnostic operations are available to you. Be sure that you sign in using an account that has a job role for the diagnostic operations that you need. For more information, see Section 16.2.1.
Some diagnostic tests can be used with all Oracle Fusion applications. Other tests apply to specific product families within Oracle Fusion Applications. For information about the individual diagnostic tests that are provided with this release, see the Oracle Fusion Applications Common User Guide in Oracle Fusion Applications Help.
You can use either the Diagnostic Dashboard or the diagctl command-line interface to run external diagnostic tests—tests that do not depend on the availability of any specific Oracle Fusion application. However, for technical reasons, you must use the Diagnostic Dashboard to run internal diagnostic tests—tests that require a specific Oracle Fusion application to be running at the time when the test is run. For information about determining whether a particular test is an internal or an external test, see Step 9 through Step 11 in Section 16.3.1.1.
This section contains the following topics:
Section 16.3.1.1, "Using the Diagnostic Dashboard to Run Diagnostic Tests"
Section 16.3.1.2, "Using the diagctl Command-Line Interface to Run Diagnostic Tests"
The Diagnostic Dashboard application provides a graphical user interface that lets you execute and monitor diagnostic tests, display and purge test results, and register any special-purpose diagnostic tests that Oracle Support may provide to you.
To run a diagnostic test from the Diagnostic Dashboard:
Navigate to the Diagnostic Dashboard for the Oracle Fusion applications you are administering, and log in using an account for the application you intend to test that has one of the following job roles:
Diagnostic Regular User
Diagnostic Advanced User
Diagnostic Administrator
For more information about these job roles, see Section 16.2.1. For more information about navigating to the Diagnostic Dashboard, see Section 16.2.2.
In the Regional area on the left side of the Diagnostic Dashboard, locate, and, if necessary, expand one of the following panels:
Search by Tests
Search by Tags
In the search panel, use standard Oracle query techniques to specify the test characteristics that you want to search for, and then click Search.
For information about the kinds of test characteristics that you can specify, see Section 16.3.2.
The results of the search appear in a table below the Search button.
Note:
In the current release, you can search for and display information about all diagnostic tests that are associated with a tag name that you specify. You cannot currently limit those searches to particular pairs of tag names and tag values. If you need to locate diagnostic tests that are associated with a particular tag name and tag value, you must search for the tag name and then scan the results for the tag value you require.
In the search results table, select the checkbox for each test that you want to run, then click Add To Run.
The Choose Tests to Run and Supply Inputs table appears in the upper Local area of the screen, listing characteristics of the tests you selected.
From the View menu, use standard techniques to adjust how the table displays its data.
If you want to display nested tests and test steps, you can also expand the tree structure in the Choose Tests to Run and Supply Inputs table.
In the Choose Tests to Run and Supply Inputs table, inspect the Input Status column and perform the appropriate action for the value you find:
For any root level test that displays the message Required Input Values Missing, either clear the checkbox to omit that test (and its nested tests and test steps) from the test run and skip to Step 8, or click the alert icon in the Input Status column to display the Input Parameters dialog and go to Step 7.
For any root level test that displays the message Required Input Values Validated or the message Input Values Validated, consider whether you want to inspect the parameter values the test is currently set to use. If so, or if you know that you want to change an existing input parameter value, click the check mark icon in the Input Status column to display the Input Parameters dialog and go to Step 7.
Note:
You can use the Input Parameters dialog to override current input parameter values, including in tests that have a valid input status.
For any root level test that displays the message No Inputs Required, skip to Step 8. A test that displays this message does not use input parameters.
If you clicked the alert icon in the Input Status column to display the Input Parameters dialog, specify new parameter values as needed, according to the parameter type, as follows; otherwise, skip this step.
For Boolean parameters, click the appropriate button in the New Value field.
For numerical parameters and general text parameters, enter the appropriate value in the New Value field.
For date parameters, click the icon in the New Value field to display a calendar pop-up menu, and then select an appropriate year, month, and day.
For parameters that must be supplied from a list of values (LOV), click the magnifying glass icon in the New Value field to display the Search and Select dialog. In the Search and Select dialog, select the appropriate value for the parameter and click OK.
Note:
The values that are available in the list of values are determined in the metadata for the diagnostic test.
If you want to save your current input values for convenient future use, then click Save to display the Save As Input Set dialog. Supply a name for the set of values that you are saving, plus any additional information about the input set that you want to store, and then click OK.
If you want to use a set of previously stored input values, then select the appropriate set from the Input Set dropdown list, and click Load.
If you want to revert to the default values for all parameters in the current test, then click Defaults. The Diagnostic Test Framework removes all values for text parameters and resets other parameter types to default values.
After you finish setting input parameters for the current test, click OK.
Repeat Step 6 through Step 7 for any other tests that are missing input values, or that have parameter values that you want to override in your test run.
From the View menu for the Choose Tests to Run and Supply Inputs table, choose Availability to display the Diagnostic Test Availability dialog.
In the Select a Diagnostic Test for Details table, select each test and inspect the icon displayed in its Availability column:
If the Availability column shows a check mark icon, then the selected test is currently available to be run.
If the Availability column shows a triangular warning icon, or if you want to determine whether the test is internal or external, then click Detach in the Available Details table header to display the Available Details table in a larger window, and then go to Step 11.
If all of the listed tests are available to be run and if you do not need to know whether they are internal or external, then skip to Step 13.
Inspect the expanded Detached Table for messages about whether the selected test depends on particular Oracle Fusion applications or about why the test is not available, and take the appropriate action:
If you want to know whether the selected test is internal or external, then inspect the Details of Required Test Components column of the Web Applications Accessible row.
If that cell of the Detached Table contains the name of an Oracle Fusion application, then the test is an internal diagnostic test that you can run only by using the Diagnostic Dashboard when the specified application is available. You cannot run an internal diagnostic test by using the diagctl command-line interface or when the application is not present.
If that cell of the Detached Table does not list an application, then the test is an external diagnostic test.
If the text in the Error column is "The following Java classes were not loadable," then this message indicates that the diagnostic testing framework cannot locate the JAR file that contains the selected test. Contact your help desk for assistance in searching for a solution in the My Oracle Support Knowledge Base. If the Knowledge Base does not provide a solution, ask your help desk to open an Oracle Support service request.
If the text in the Error column is "The following PL/SQL procedures were not located in the database," then this message indicates that the diagnostic testing framework cannot locate the test code for the selected PL/SQL diagnostic test in your database. Contact your help desk for assistance in searching for a solution in the My Oracle Support Knowledge Base. If the Knowledge Base does not provide a solution, ask your help desk to open an Oracle Support service request.
If the text in the Error column is "The following Web Applications were inaccessible," then use the Oracle WebLogic Server console or Fusion Applications Control to check whether the listed applications are running correctly. This message indicates that the Diagnostic Testing Framework must have access to running instances of the listed Oracle Fusion applications to run the selected diagnostic test—the test is an internal test.
For more information about installing and deploying Oracle Fusion Applications, see the "Provisioning a New Applications Environment" chapter of the Oracle Fusion Applications Installation Guide.
If the problem persists when the listed Oracle Fusion applications and the relevant database instance are all running, contact Oracle Support for assistance.
If the text in the Error column is "The current user does not have execution privileges for the following tests," then you must log in as a user who has appropriate privileges to execute the selected test. For information about the privileges required, see Section 16.2.1.
If the text in the Error column is "The current user does not have privileges to view reports for the following tests," then you must log in as a user who has appropriate privileges to view the results of the selected test. For information about the privileges required, see Section 16.2.1.
Note:
It is possible to have the necessary privileges to view diagnostic test results without having the necessary privileges to run those tests. Use an appropriate user account for the actions you want to perform.
If you have not already done so, close the Detached Table window and the Diagnostic Test Availability dialog, repeat Step 9 and Step 10 to verify that all listed tests are now available to be run, and then go to Step 13.
If you wish, enter a name for your test run in the Run Name field in the control bar.
Note:
Do not use the word error in your test run name. If you use the word error, or if you leave the Run Name field blank, the Diagnostic Testing Framework automatically assigns the test run a name. For information about the formats used in automatically assigned test run names, see Section 16.3.10.
When the Input Status column of the Choose Tests to Run and Supply Inputs table displays Required Input Values Validated in all of the selected rows, choose one of the following from the Run Options menu:
Run Now: Runs the selected test or tests immediately after you click Run.
Run Later: Schedules when the test or tests will be run. This option is integrated with Oracle Enterprise Scheduler Service. When you select this option, the Run button on the toolbar changes to a Schedule Run button. Complete the following substeps to schedule when the test or tests will be run:
Click the Schedule Run button to display a Schedule Tests dialog.
Click the Schedule tab and then select Use a schedule.
From the Frequency dropdown list, select how often to run the selected test or tests.
In the Start field, specify the date and time to start the testing.
Click Submit.
Adjust option settings to determine whether or not to run the prerequisite tests for the diagnostic tests you selected:
If you want to run prerequisite tests, make sure that the No Prerequisites option in the Run Options menu is not selected.
If you do not want to run prerequisite tests, make sure that the No Prerequisites option in the Run Options menu is selected.
Adjust option settings to determine how many threads to use when running the selected diagnostic tests:
To use multiple threads, choose Run in Parallel from the Run Options menu. Then choose Number of Threads from the Run Options menu and select a value from 2 through 5. The default number of threads for running in parallel is 3.
To use a single thread, choose Run Synchronously from the Run Options menu.
If you chose Run Now in Step 14, then click Run to start executing the test run.
If you chose Run Later in Step 14, then the test run starts executing at the time you set in the Schedule Tests dialog.
The Diagnostic Test Framework command-line utility, diagctl, lets you specify which tests to run in several different ways: by test name, by associated product codes, by associated tag names and tag values, and by associated module IDs or module keys.
You can run one or more diagnostic tests using a single diagctl command. It is particularly appropriate to use diagctl when you do not have access to a WebLogic Server.
Note:
Technical constraints prevent the diagctl command-line interface from returning useful results for internal diagnostic tests (tests that require a specific Oracle Fusion application to be running when the test is performed). You must use the Diagnostic Dashboard to run any internal diagnostic tests.
You must also use the Diagnostic Dashboard to determine whether a particular test is an internal or an external test. For more information about making this determination, see Step 9 through Step 11 in Section 16.3.1.1.
To run Diagnostic Tests from the diagctl command-line interface:
Obtain the user name and password for the Oracle Fusion Applications account that will run the diagnostic test or tests, and the password for that account.
A user name and password is required for any diagnostic test that you run using the diagctl command-line interface. The command-line syntax for specifying the user name and password is un=user_name and pwd=password.
Decide which of the following methods to use to specify the diagnostic test or tests that you want to run:
Specify a single test name: To run a single specific test without specifying input parameters, the command-line syntax is test=test_name
Specify a test name and parameters: To run a single specific test with one or more input parameters, the command-line syntax is test=test_name input:parameter_name1=parameter_value1 input:parameter_name2=parameter_value2
Specify multiple test names: To run several specific tests, the command-line syntax is test=test_name1,test_name2,test_name3
Note:
If you are specifying multiple tests on a single command line, then you cannot specify input parameters on that command line.
Specify by product codes: To run all of the tests that are associated with one or more specific product codes in the Applications taxonomy, the command-line syntax is app=product_code1,product_code2,product_code3
Specify by module ID: To run all of the tests that are associated with specific module IDs in the Applications taxonomy, and all of the tests that are associated with child modules of the module that you specify, the command-line syntax is modid=moduleID1,moduleID2,moduleID3
Specify by module key: To run all of the tests that are associated with specific module keys in the Applications taxonomy, the command-line syntax is modkey=module_key1,module_key2,module_key3
Specify by tag name and tag value: To run all of the tests that are associated with a specific tag and tag value in the diagnostic test repository, and to run any tests that are associated with any child tag values of the tag name and tag value that you specify, the command-line syntax is tag:tagname1=tagvalue1 tag:tagname2=tagvalue2 tag:tagname3=tagvalue3
You must use at least one of these options in each command to run a diagnostic test from diagctl. You can include more than one of these options in a single command, if you prefer.
Decide whether to use any, some, or all of the following additional options for the test run:
Specify a test run name: To specify a particular name for the test run, use the command-line syntax runname=run_name.
Note:
Do not include the word error in your test run name. If you include the word error, or if you do not specify a test run name, the command-line utility automatically generates a name for the test run. Automatically generated test run names start with the test name, product code, module ID, module key, or tag name and value that you specified, followed by a colon, a timestamp, another colon, and a sequence number.
Specify whether to test recursively: To run all of the specified tests recursively, use the command-line syntax recurse=Y. The default value is N.
Specify whether to run prerequisite tests: To identify and run any tests that are prerequisites before running the specified tests, use the command-line syntax prereq=Y. The default value is N.
Specify the monitoring interval: To specify how often the status of the test run is uploaded to the test repository, use the command-line syntax moninterval=time_in_seconds. The default value is 30 seconds.
Specify the number of threads: To specify the number of parallel threads to spawn for processing this test run, use the command-line syntax nthreads=number_of_threads. The default value is 5. A value of 1 directs the utility to run the tests serially.
At a command prompt for your operating system, enter the following commands that are appropriate for your operating system, making these substitutions:
Replace FA_MW_HOME with the location of the fusionapps Oracle Fusion Applications Middleware Home directory.
Replace JROCKIT_ORACLE_HOME with the location of the jdk6 Oracle JRockit Oracle Home directory (the Java Development Kit that was included in the Oracle Fusion Applications media pack).
Replace ATGPF_ORACLE_HOME with the location of the atgpf Applications Core Oracle Home directory.
For more information about the locations of Oracle Fusion Applications home directories, see Figure 1-6.
(UNIX) export JAVA_HOME=JROCKIT_ORACLE_HOME (UNIX) export MW_HOME=FA_MW_HOME (UNIX) export DIAGJPSCONFIGFILE=ATGPF_ORACLE_HOME/bin/jps-config-jse.xml (Windows) set JAVA_HOME=JROCKIT_ORACLE_HOME (Windows) set MW_HOME=FA_MW_HOME (Windows) set DIAGJPSCONFIGFILE=ATGPF_ORACLE_HOME/bin/jps-config-jse.xml
Note:
For successful authentication, the DIAGJPSCONFIGFILE environment variable must be correctly set for any operating system session in which the diagctl.sh command-line interface is used.
Still at an operating system command prompt, navigate to the location of the diagctl executable:
(UNIX) ATGPF_ORACLE_HOME/bin/diagctl.sh (Windows) ATGPF_ORACLE_HOME\bin\diagctl.cmd
Enter diagctl.sh run (for UNIX) or diagctl run (for Windows) followed by the user name and password from Step 1 and the options that you decided upon in Step 2 and Step 3, using the syntax described in those steps.
Note:
You can list command arguments that appear after the word run in any order. If you do not specify the password on the command line, the utility prompts you to supply it. For detailed help about running diagnostic tests, enter diagctl.sh run help (for UNIX) or diagctl run help (for Windows)
For example, to run a single test with two input parameter values specified, you enter a command such as the following:
(UNIX) diagctl.sh run test=oracle.apps.fnd.appltest.sampleTest input:param1=value1 input:param2=value2 un=sysadmin (WINDOWS) diagctl run test=oracle.apps.fnd.appltest.sampleTest input:param1=value1 input:param2=value2 un=sysadmin
Note:
If you specify an invalid parameter value, the command-line interface returns an error message and does not run the test.
To run all of the tests that belong to the Application Object Library (FND) and Oracle Fusion General Ledger products, and to run them recursively and with prerequisite analysis, you enter a command such as:
(UNIX) diagctl.sh run app=FND,GL recurse=Y prereq=Y un=sysadmin (WINDOWS) diagctl run app=FND,GL recurse=Y prereq=Y un=sysadmin
To run all of the tests that are associated with the given module ID, you enter:
(UNIX) diagctl.sh run modid=module1,module2 un=sysadmin (WINDOWS) diagctl run modid=module1,module2 un=sysadmin
You can use the Diagnostic Dashboard to search for available diagnostic tests.
One way you can search is to use Search by Tags to search for diagnostic tests that are associated with a particular categorization tag name that you specify.
Another way you can search is to use Search by Tests to search for tests with values that you specify for one or more of the following characteristics:
Test name
Test description
Name of the Oracle Fusion Applications code module that the test checks.
The Diagnostic Testing Framework treats any search value that you enter as a case-insensitive matching pattern, returning the result if the pattern appears anywhere in the specified field. However, if you specify more than one search value to match, the framework returns results only for diagnostic tests that match all of the values that you specify (logical AND).
In general, searching for diagnostic tests is done as a portion of the process of running diagnostic tests from the Diagnostic Dashboard. For more information, see Section 16.3.1.1.
Whether or not you can run a diagnostic test at any given time depends on both the specific requirements of the test and the current state of your Oracle Fusion Applications system. Any of the following factors can prevent a test from being available:
Java class availability
PL/SQL procedure availability
Oracle Fusion Applications accessibility
Execution privileges for the test
Report viewing privileges for the test
In general, checking the availability of diagnostic tests is done as a portion of the process of running diagnostic tests. For more information, see Section 16.3.1.1.
Note:
Some diagnostic tests require a specific Oracle Fusion application to be running while the test is performed—these diagnostic tests are called internal diagnostic tests. Other diagnostic tests can perform their functions even if the Oracle Fusion application to be tested is not running—these tests are called external diagnostic tests.
Diagnostic tests often have input parameters. Oracle supplies default values for some input parameters. When you are preparing to run one or more diagnostic tests, you can change the values for input parameters that have default values and enter values for input parameters that do not have default values. If you know that you will use the same parameter values more than once, you can save those values into an input set that you can reuse for later test runs.
All required input parameters must have values assigned before you can run a diagnostic test. If there are required parameter values missing, the Diagnostic Dashboard application displays Required Input Values Missing in the Input Status column of the Choose Tests to Run and Supply Inputs table.
To specify input parameter values, click the icon in the Input Status column to display the Input Parameters dialog. Then, you can either enter parameter values individually in the New Value column of the Edit Input Set table, or you can select a previously saved set of values from the Input Set dropdown list. After you specify all of the required input parameters, the Diagnostic Dashboard application displays a check mark icon with the message Inputs Edited: Required Input Values Validated. For more information, see Section 16.3.1.1.
You can use either the Diagnostic Dashboard or the diagctl command-line interface to run diagnostic tests immediately.
In the Diagnostic Dashboard, you specify that you want to run a diagnostic test immediately by choosing Run Now from the Run Options menu.
For the diagctl command-line interface, you specify that you want to run a diagnostic test immediately by entering the command to run the test from an interactive session prompt.
For more information, see Section 16.3.1.
In the Diagnostic Dashboard, you can specify a particular time to run diagnostic tests by choosing Run Later from the Run Options menu. For more information, see Section 16.3.1.1.
To run a delayed diagnostic test using the diagctl command-line interface, create a script that calls diagctl.sh (for UNIX) or diagctl.cmd (for Windows), and then use standard Oracle Enterprise Scheduler techniques to schedule when the script runs. For information about submitting and monitoring Oracle Enterprise Scheduler jobs, see Chapter 7.
You can check the status of a diagnostic test from the Diagnostic Dashboard or from the diagctl command-line interface. The command-line interface is primarily intended for use if the Diagnostic Dashboard is temporarily unavailable.
This section contains the following topics:
In the Diagnostic Dashboard, the Diagnostic Test Run Status table displays two types of status information:
Execution Status: This column displays status information about whether or not a test run request can be executed successfully.
Diagnostic Status: This column displays status information about whether or not individual diagnostic tests detect problems.
Note:
After running a diagnostic test using the Diagnostic Dashboard, you may need to click Refresh to display the latest status information, including rows for the following kinds of test runs:
Test runs that were run immediately from the Diagnostic Dashboard
Test runs that were scheduled to be run later from the Diagnostic Dashboard
Test runs that were submitted using the diagctl command-line interface
When you click Refresh, the Diagnostic Dashboard lists any additional test runs that you or other users have submitted in your current Oracle WebLogic Server domain. If your Oracle Fusion Applications deployment uses Global Single Instance (GSI), the Diagnostic Dashboard also lists test runs that were submitted in other domains.
To check the status of a diagnostic test using the Diagnostic Dashboard:
If you started the diagnostic test from your current Diagnostic Dashboard application session, then the Diagnostic Test Run Status table automatically displays in the lower right portion of the screen after you click Run. Skip to Step 4.
If you are not already displaying the Diagnostic Dashboard for the Oracle Fusion applications you are administering, navigate to the dashboard and log in using an account for the application you are testing. For more information, see Section 16.2.2.
In the Regional area of your screen, expand the Tasks panel and click Run Status.
If you want the Diagnostic Test Run Status table to display only certain types of rows, then select one of the following options from the Find dropdown list:
All Runs Submitted in Last Hour
All Runs Submitted in Last 24 Hours
All Running
All Running Submitted in Last Hour
All Runs with Diagnostic Failures in Last 24 Hours
All Runs with Diagnostic Failures
All Runs with Diagnostic Warnings
All Runs with Execution Errors
All Completed
All Completed with No Issues
All Runs
All Runs Run By the Current User in the Last Hour
All Runs Run By the Current User
If you want to search for specific rows in the Diagnostic Test Run Status table, then click the Search Test Runs icon, enter the search criteria, and click OK.
The available search criteria include:
Test run dates
Test run names
Test display names
User names of those who started test runs
Execution status
If you want to display additional columns in the Diagnostic Test Run Status table, then choose the additional columns from the View menu.
Expand the test run nodes as needed to view the list of test executions for each test, and then inspect the Execution Status column for information about whether tests and test runs have completed or encountered execution errors.
Inspect the Diagnostic Status column for information about whether completed tests and test runs encountered any issues before completing.
For additional information about any test execution, click the icon in the Report column of the appropriate row of the table.
The Diagnostic Test Framework command-line utility, diagctl, provides three different ways that you can specify the diagnostic test for which you want status information: by test run name, by test run ID, and by test execution ID.
To check the status of a diagnostic test using the diagctl command-line interface:
Obtain the user name and password for the Oracle Fusion Applications account that will run the diagnostic test or tests, and the password for that account.
A user name and password is required whenever you use the diagctl command-line interface to check the status of a diagnostic test. The command-line syntax for specifying the user name and password is un=user_name and pwd=password.
Decide which of the following methods to use to specify the diagnostic test run for which you want status information:
Specify a test run name: To check the status of a diagnostic test run for which you have the run name, the command-line syntax is runName=run_name
Specify a test run ID: To check the status of a diagnostic test for which you have the test run ID, the command-line syntax is runid=run_ID
Specify a test execution ID: To check the status of a diagnostic test for which you have the execution ID, the command-line syntax is execid=execution_ID
You must use at least one these options in each command to check the status of a diagnostic test using diagctl.
Decide whether you want to view the status of nested test runs.
To check the status of all diagnostic tests that are nested within the specified test, the command-line syntax is printtree=Y. This setting defaults to a value of N, meaning that the status is reported only for the specified test.
At a command prompt for your operating system, navigate to the location of the diagctl executable under the fusionapps Oracle Fusion Middleware home directory:
(UNIX) FA_MW_HOME/atgpf/bin/diagctl.sh (Windows) FA_MW_HOME\atgpf\bin\diagctl.cmd
Enter diagctl.sh status (for UNIX) or diagctl status (for Windows) followed by the user name and password from Step 1 and the options that you decided upon in Step 2 and Step 3, using the syntax described in those steps.
Note:
You can list command arguments that appear after the word status in any order. If you do not specify the password as part of the command, the utility will prompt you to supply it. For detailed help about getting status information, enter diagctl.sh status help (for UNIX) or diagctl status help (for Windows).
For example, to check the status of a test by using a test run name, you enter a command such as:
(UNIX) diagctl.sh status runName=TrialRun1 un=sysadmin (Windows) diagctl status runName=TrialRun1 un=sysadmin
To check the status of a test and its nested test runs by using a run ID, you enter a command such as:
(UNIX) diagctl.sh status runid=RunID1 printtree=Y un=sysadmin (Windows) diagctl status runid=RunID1 printtree=Y un=sysadmin
To check the status of a test by using an execution key, you enter:
(UNIX) diagctl.sh status execid=TestExecID1 un=sysadmin (Windows) diagctl status execid=TestExecID1 un=sysadmin
From time to time, you may want to stop a diagnostic test or test run that is running. Several constraints affect your ability to cancel a diagnostic test or test run:
In the current release, you must use the Diagnostic Dashboard to cancel a diagnostic test or test run that is running. The diagctl command-line interface does not provide this capability.
To cancel a test or test run that you started, you must use an account that has been assigned the Diagnostic Regular User, Diagnostic Advanced User, or Diagnostic Administrator job role.
To cancel a test or test run that another user started, you must use an account that has been assigned the Diagnostic Administrator job role.
When a diagnostic test is scheduled to run at a later time, it is immediately submitted to the Oracle Enterprise Scheduler Service. The procedure for canceling this type of test depends on whether or not the test has already started to execute when you want to cancel it:
To cancel a scheduled diagnostic test that has not yet started to execute, use standard Oracle Enterprise Scheduler techniques to cancel the job. For more information about canceling scheduled jobs, see the "Cancelling Oracle Enterprise Scheduling Service Job Requests" section in the Oracle Fusion Middleware Administrator's Guide for Oracle Enterprise Scheduler.
To cancel a scheduled diagnostic test that the Diagnostic Test Run Status dashboard panel indicates is already running, use the Diagnostic Dashboard to cancel it in the same way that you would cancel a test that ran immediately.
When you cancel a diagnostic test or test run, the consequences may vary depending on how much of the test run has executed and the language in which the test code is written:
If you cancel a diagnostic test run while a test step from that test run is in progress, the test step that is currently running is canceled. No additional tests or test steps in the remainder of the canceled test run are executed. The Diagnostic Test Run Status panel displays an Execution Status of Canceled for the run, and a pop-up window displays a message such as the following, but no log messages are recorded to indicate that a diagnostic test run was canceled:
Test Run "test_name" has been canceled.
Please check the test run report for further details.
When you cancel a diagnostic test step that is implemented in Java, the diagnostic framework automatically closes the test step's database connection, using an asynchronous command to terminate the thread. However, when you cancel a diagnostic test step that is implemented using PL/SQL, the diagnostic framework cannot interrupt the test step and use the existing database connection to close that connection. To reclaim the resources allocated to a canceled PL/SQL diagnostic test step, you must establish a separate connection to the database and use an alter system kill session command to close the connection that the canceled test step was using, as described later in this section.
To cancel a diagnostic test using the Diagnostic Dashboard:
If you started the diagnostic test from your current Diagnostic Dashboard application session, then the Diagnostic Test Run Status table automatically displays in the lower right portion of the screen after you click Run. Skip to Step 4.
If you are not already displaying the Diagnostic Dashboard for the Oracle Fusion applications you are administering, then navigate to the dashboard and log in using an account for the application you are testing. For more information, see Section 16.2.2.
In the Regional area of your screen, expand the Tasks panel and click Run Status.
In the Diagnostic Test Run Status panel, locate and select the test run that you want to cancel, verify that its Execution Status is Running, and then click Cancel.
In the Diagnostic Test Run Status panel, click the Report icon for the canceled test run.
Inspect the test run report to determine whether the canceled test step was implemented using Java or PL/SQL.
If the canceled test step was implemented using Java, then skip all of the remaining steps in this procedure.
If the canceled test step was implemented using PL/SQL, then go to Step 7.
If the canceled test step was implemented using PL/SQL, then make a note of the session ID and serial number for the database connection that the step was using.
For example, the report might display information similar to the following:
Step Report - Diagnostics_Engine_Log Session Information The test test_name is using a database connection with Session Id 944 and Serial Number 817
Using your preferred database client or database monitoring application and a separate connection to the database, determine whether the database connection for the canceled test step is still open.
For example, you could use a SQL client to execute the following query, substituting the session identifier and serial number values that you obtained in Step 7 for session_Id and serial_number:
select * from v$session where sid = session_Id and serial# = serial_number
If this query returns a row that contains the session ID and serial number that you specified, then the database connection from the canceled test is still open and using resources. Go to Step 9.
If the query does not return a row that contains the session ID and serial number that you specified, then the database connection from the canceled test has been closed. In this case, skip Step 9.
If the database connection for the canceled test step is still open, use a command such as the following to close that connection, substituting the correct session identifier and serial number values for session_Id and serial_number.
alter system kill session 'session_Id, serial_number';
You can use either the Diagnostic Dashboard or the diagctl command-line interface to view reports that show the results of diagnostic tests, whichever you prefer.
This section contains the following topics:
Section 16.3.9.1, "Using the Diagnostic Dashboard to View the Results of Diagnostic Tests"
Section 16.3.9.2, "Using the diagctl Command-Line Interface to View the Results of Diagnostic Tests"
You can view the results of a diagnostic test in the dashboard by checking the status of the test and then clicking the icon in the Report column of the selected table row. For more information, see Section 16.3.7.1.
The diagctl command-line utility provides three different ways of requesting the results of diagnostic test results: by test run name, by test run ID, and by test execution ID.
To view diagnostic test result reports using the diagctl command-line interface:
Obtain the user name and password for the Oracle Fusion Applications account that you will use to view the test results, and the password for that account.
A user name and password is required whenever you use the diagctl command-line interface to view the results of a diagnostic test. The command-line syntax for specifying the user name and password is un=user_name and pwd=password.
Decide which of the following methods to use to specify the diagnostic test run for which you want to view results:
Specify a test run name: To view the results of a diagnostic test run for which you have the run name, the command-line syntax is runName=run_name. This option includes results for all of the executions in the test run.
Specify a test run ID: To view the results of a diagnostic test for which you have the test run ID, the command-line syntax is runid=run_ID. This option includes results for all of the executions in the run.
Specify a test execution ID: To view the results of a diagnostic test for which you have the execution ID, the command-line syntax is execid=execution_ID. This option includes results for the specified execution and any nested executions.
You must use at least one of these options in each command to view the results of a diagnostic test using diagctl.
Decide whether you want to use one or more of the following additional options:
Specify a destination directory for results: To write the test results to a specific directory, the command-line syntax is destdir=destination_directory. If you do not specify a directory, reports are placed in the java.io.tmpdir/user.name/diagfwk directory where java.io.tmpdir and user.name are Java system properties.
Specify a format for the result report: Valid values are XML and HTML. The default value is HTML. XML report files are created as a step toward creating HTML report files. These XML report files remain in the same directory as the HTML report files.
Specify if the report should be translated: Valid values are Y and N. If the value is Y, any NLS keys that are specified in the report are translated to your session language. If the value is N, no translation is performed. The default value is Y.
At a command prompt for your operating system, navigate to the location of the diagctl executable under the fusionapps Oracle Fusion Middleware home directory:
(UNIX) FA_MW_HOME/atgpf/bin/diagctl.sh (Windows) FA_MW_HOME\atgpf\bin\diagctl.cmd
Enter diagctl.sh report (for UNIX) or diagctl report (for Windows), followed by the user name and password from Step 1 and the options that you decided upon in Step 2 and Step 3, using the syntax described in those steps.
Note:
You can list command arguments that appear after the word report in any order. If you do not specify the password as part of the command, the utility will prompt you to supply it. For detailed help about viewing reports, enter diagctl.sh report help (for UNIX) or diagctl report help (for Windows).
For example, to view the results of a test by using a run name, and to place the results in a particular directory, you enter a command such as:
(UNIX) diagctl.sh report runName=TrialRun1 destdir=/d1/testreport un=sysadmin (Windows) diagctl report runName=TrialRun1 destdir=/d1/testreport un=sysadmin
To view the results of a test run by using a run ID, with the results placed in the default location, you enter a command such as:
(UNIX) diagctl.sh report runid=RunID1 un=sysadmin (Windows) diagctl report runid=RunID1 un=sysadmin
To check the status of a test by using an execution key, with the results placed in the default location, you enter:
(UNIX) diagctl.sh report execid=TestExecID1 un=sysadmin (Windows) diagctl report execid=TestExecID1 un=sysadmin
Navigate to the location of the results file, and use a browser or text editor of your choice to view it.
Any test run name that the Diagnostic Testing Framework supplies follows naming conventions that reflect how the test was started. If you find that an unfamiliar diagnostic test run occurred at an unexpected time, then knowing the test run naming conventions can help you to understand the circumstances in which the test run was started:
When you submit a test run to run immediately, without specifying a run name, the name that is automatically assigned to the test run has the format TestRun_runID, where runID is a unique string of alphanumeric characters generated by the Diagnostic Testing Framework, such as TestRun_91D818BA54BB29C8E040578C495D6956. This naming convention applies both when tests are submitted from the Diagnostic Dashboard and when tests are submitted using diagctl.
When you schedule a diagnostic test run to run later, using Oracle Enterprise Scheduler Service, the name that is automatically assigned to the test run has the format [TestRunName_]ESS_requestID_timestamp, where TestRunName is an optional name that the you may specify when submitting the test, requestID is a unique identifier supplied by the Oracle Enterprise Scheduler when it schedules the job, and timestamp indicates the time when the job is scheduled to run. This naming convention applies to tests that are submitted from the Diagnostic Dashboard to run later. (Tests that are submitted using diagctl always run immediately.)
For example, if you enter the test run name routine, the full test run name might be:
routine_ESS-417-2010-09-09T17:07:09.115-0700
When a test run is submitted automatically because an incident occurred, the name that is automatically assigned to the test run has the format AppsLogger-DiagnosticTestingFrameworkIntegration_id_timestamp, where id is a number that uniquely identifies the incident, and timestamp indicates when the diagnostic test run starts.
From time to time, you may want to remove diagnostic test run results from your database, to keep the Run Status table from becoming too large.
Note:
To remove the results of one or more diagnostic test runs from your database, you must use the Diagnostic Dashboard application with an account that has been assigned the Diagnostic Administrator job role.
The diagctl command-line interface does not currently provide a way to purge test run results.
To purge selected diagnostic test run results from the database:
If you started the diagnostic test from your current application session, then the Diagnostic Test Run Status table automatically displays in the lower right portion of the screen after you click Run. Skip to Step 4.
If you are not already displaying the Diagnostic Dashboard for the Oracle Fusion applications you are administering, then navigate to the dashboard and log in using an account for the application that needs its test results purged. For more information see Section 16.2.2.
In the Regional area of your screen, expand the Tasks panel and click Run Status.
In the Diagnostic Test Run Status table header, use either of the following methods to locate the test run status records that represent the test results that you want to remove from the database:
Select any appropriate filter from the Find dropdown list.
Click the search button, enter search criteria, and click OK.
After searching or filtering, inspect the listings displayed in the Diagnostic Test Run Status table, and decide whether you want to remove listed test results from the database individually or as a group:
To remove a single test run status result record from the database, complete the following substeps in the Diagnostic Test Run Status table:
Select the test run status record that represents the results that you want to remove from the database, and click the delete button in the Diagnostic Test Run Status table header.
In the Delete Test Run dialog, select Delete test run "TestRunName" and click OK.
The selected record is removed from the database immediately.
To remove all of the listed test run status result records from the database, click the delete button in the Diagnostic Test Run Status table header.
Depending on whether or not you selected a record in the Diagnostic Test Run Status table, either the Delete Test Run dialog or the Confirm Test Run Delete dialog appears.
Complete the purge process using the appropriate instructions for the dialog displayed on your screen:
If your screen displays the Delete Test Run dialog, then select Delete all test runs in the list and click OK to remove all of the listed test run results from the database immediately.
If your screen displays the Confirm Test Run Delete dialog, then click Yes to remove all of the listed test run results from the database immediately.
|
 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|