Oracle® Real User Experience Insight Accelerator for Oracle E-Business Suite Guide Release 6.5.0 for Linux x86-64 Part Number E17193-02 |
|
|
View PDF |
This chapter describes the procedure for installing the EBS accelerator package, and configuring your application definitions within RUEI to enable the accurate monitoring of EBS-based applications.
This accelerator package for RUEI enables out-of-the-box monitoring of EBS modules. This monitoring supports user session tracking, the discovery of end-user performance issues, and the identification of application issues associated with EBS modules running both the OA and JTT frameworks, as well as Oracle Forms applications running in servlet and socket mode.
This accelerator package automatically discovers all installed EBS modules, and translates network objects to business functions. This facilitates the measurement and monitoring of real-user transactions, from initial query to their commit as part of business transactions. Individual user actions are automatically matched to the correct module, form, or formblock in order to provide contextual analysis. This state-of-the-art monitoring solution supports the creation of KPIs for critical packaged applications, and the analysis of real-user business transactions.
Note:
The dependency in previous versions of RUEI on enabling End User Monitoring (for Oracle Forms version 10.1.2 and higher) or Chronos Monitoring (for Oracle Forms version 6i) was removed in RUEI version 6.0. Note that if enabled, database time reporting is available within RUEI.The information presented in this guide is relevant to all customers. However, customers working within a Forms-only environment should pay particular attention to the issues highlighted in this section.
In order for RUEI to accurately report on EBS-based applications, it needs information about your production environment. In particular, it needs to map functional areas to reported names. As explained in Section 1.9, "Synchronizing RUEI With the EBS Production Environment", this is done through running the create_EBS_info.pl
Perl script. Customers within Forms-only environments are also recommended to run this script and upload the generated .txt
files within a .zip
file.
Manually Creating Functional Mappings
The create_EBS_info.pl
script uses a number of EBS database tables to retrieve information about the installation and configuration of your Oracle Forms instance. The exact database tables used are described in Section 2.2, "Database Tables".
However, the APPLSYS.FND_APPLICATION, APPLSYS.FND_APPLICATION_TL, APPLSYS.FND_FORM, APPLSYS.FND_FORM_TL and other tables used by the script do not exist in a Forms-only environment. Therefore, you can either rely on the default (template) mappings provided with RUEI (described later in this section), or you can specify the required mappings by creating the associated .txt
files manually.
When creating these files manually, the following tab-separated files are required:
EBS_formname2details.txt
: specifies a functional description for each form. Each line in the file should have the following format:
formname{TAB}form_description
For example:
ADSAPCRD Credit Card Expense Transaction Entry ADSAPPRC Procurement Card Transaction Entry ADSCONC Running Jobs ADSCONC Tax Locations ADSCSCRC Healthcare CC ADSMAILI Mail InformationADSRSETUP ADS Repurpose Setup ADSSOE Custom Order EntryADSSOE View Person Life Event Information AKDAPREG Application Module Parameters Registry
EBS_formname2appshort.txt
: specifies the short (3-letter) version of the application name of which each form is part. Each line in the file should have the following format:
formname{TAB}short_application_name
For example:
ADSAPCRD ads ADSAPPRC ads ADSCONC ads ADSCSCRC ads ADSMAILI ads ADSRSETUP ads ADSSOE ads AKDAPREG ak AKDATTRS ak AKDFLOWB ak
EBS_appsort2appname.txt
: specifies the mapping between the short (3-letter) application name and the full application name. It has the following format:
short_application_name{TAB}application_name
For example:
abm Activity Based Management (Obsolete) ad Applications DBA ads Applications Demonstration Services ads_dev ADS Development ahl Complex Maintenance Repair and Overhaul ahm Hosting Manager(Obsolete) ak Common Modules-AK alr Alert ame Approvals Management amf Fulfillment Services (Obsolete)
Be aware that the created configuration files must be uploaded for each required suite in a .zip
file. This may only contain non-empty .txt
files. In addition, all files must be in the root directory. That is, subdirectories are not permitted. It is important that you upload the correct configuration file for the required suite, and that it is based on the actual production environment. The procedure to update the configuration file is described in Section 1.9, "Synchronizing RUEI With the EBS Production Environment".
Relying on the Default (Template) Mapping
If manually creating the required mappings is not practical, you can simply rely on the default (template) mappings already configured within RUEI. While this approach provides an adequate level of reporting, it is subject to the following restrictions:
form_name
: normally this would be the 8-character technical name translated to a functional description. However, because this is not available, the 8-character technical name is reported instead.
app
: normally this would be derived from the mapping file that connects the form name with the application. However, because this is not available, the first three letters of the form name are reported instead.
application_name
: normally this would be derived from the mapping file. However, because this is not available, the app
is reported instead. For example, eds
instead of Application
Demonstration
Services
as shown in Figure 2-1.
Keeping Matching Information Up-to-Date
Because Forms-only environments typically change over time, it is strongly recommended that you regularly review your mapping information. Be aware that the above restrictions will also apply to any forms that have been added to your environment since your last ran the create_EBS_info.pl
script or manually created the mapping files.
Memory Requirements for Forms-Based Environments
Be aware that the monitoring of Forms-based traffic requires significant amounts of memory. For example, the monitoring of 10,000 simultaneous Forms sessions would require approximately 10 GB of Collector memory. Therefore, it is recommended that you deploy the Collector monitoring Forms-based traffic as a remote Collector with at least 16 GB of RAM. Alternatively, if you are using a single-server deployment, the server should have at least 32 GB of RAM.
In addition, it is recommended that you review the level of system memory available to the Collector. For a single-server deployment with 24 GB of RAM, this should be set to 50%, while for a server with 32 GB of RAM, this should be set to 40%. Information about how to increase the amount of available Collector memory is available at https://metalink2.oracle.com/metalink/plsql/f?p=130:14:7170176407577419410::::p14_database_id,p14_docid,p14_show_header,p14_show_help,p14_black_frame,p14_font:NOT,762361.1,1,1,1,helvetica
.
EBS is based on several frameworks. Because these frameworks allow customers to extend their applications with their own functionality, RUEI requires information about their implementation in order to correctly monitor them.
The EBS monitoring functionality provided with this accelerator package supports all out-of-the-box EBS functionality, as well as some level of customization. However, it is possible that certain EBS customizations may provide unexpected reporting results within RUEI. This mainly concerns the mapping of functional areas to reported names.
In order to facilitate the correct monitoring of EBS-based applications by RUEI, you need to do the following:
Install the accelerator package RPMs on the RUEI Reporter system.
Verify the scope of monitored traffic.
Specify the cookie technology used to track user sessions.
Create and configure the EBS suite(s) required for your EBS-based applications.
Synchronize the information held within RUEI with the EBS production environment.
Verify and evaluate the EBS suite configuration.
Each of these steps are discussed in more detail in the following sections.
Important:
The upgrade of an existing Oracle E-Business Suite accelerator package to release 6.5 must be performed at the same time as the upgrade of the RUEI system to version 6.5.Note it is assumed that a working RUEI system has been installed and configured (as described in the Oracle Real User Experience Insight Installation Guide), and is fully operational. Install the EBS accelerator package on the RUEI Reporter system using the following commands as the root
user:
cd /root/RUEI/65 ./ruei-install.sh suites
Often the EBS software is configured to use a non-standard port, such as 8000. The port on which your EBS installation is running can be found by examining the login URL. This takes the following format:
https(s)://hostname:portnumber/OA_HTML/AppsLogin
Verify that the portnumber
is configured as one of the defined ports (these are described below). In addition, if a HTTPS port is specified, ensure that a copy of the Web server's private SSL key is imported into the Collector system. See Appendix A, "Checking Socket and Servlet Mode" for information about how to identify the mode and port number.
To verify the port number, do the following:
Select Configuration, then Security, and then Protocols. The currently monitored ports are displayed. An example is shown in Figure 1-1:
Important:
The port numbers specified within each protocol must be mutually exclusive. That is, a port number should only appear in one protocol's list of assigned port numbers.Use the View menu to select each Collector. The System (localhost) item represents the local server system.
If the port number is not already listed, click the required protocol setting. The following settings are available:
HTTP/Forms servlet mode: specifies the port(s) on which the Collector should listen for Forms servlet traffic.
Forms socket mode: specifies the port(s) on which the Collector should listen for Forms traffic in socket mode.
HTTP: specifies the port(s) on which the Collector should listen for HTTP traffic. This setting should only be used for "pure" HTTP traffic.
HTTPS: specifies the port(s) on which the Collector should listen for HTTPS traffic.
A dialog similar to the one shown in Figure 1-2 appears.
To add a new port number, enter the required number in the Port number field, and click Add. The default Oracle Forms port is 8000. Note, if required, this needs to be manually added. To remove a port from the list, click the Remove icon to the right of the port number. When ready, click Save.
Important:
The port numbers specified within each protocol setting should be mutually exclusive. That is, a port number (such as 8000) should only appear in one protocol's list of assigned port numbers.For each Collector, you are prompted to restart the Collector. This is necessary in order to make your changes effective. Note you can also restart the selected Collector by clicking the Restart Collector icon shown in Figure 1-1.
For HTTPS traffic, you should also verify that, for each Collector, the required SSL key is installed by selecting Configuration, then Security, and then SSL keys. Use the View menu to select the required Collector. If the host name does not match one of the already listed SSL keys, import the required SSL key. The procedure to do this is fully described in the Oracle Real User Experience Insight User's Guide. In addition, you should verify that the key is not expired, and activated.
Note:
If a port carries HTTPS-based traffic, and also servlet mode traffic, the port should be configured under the HTTPS protocol setting (described above).Within the RUEI Reporter, create and configure the suite definition(s) required for your EBS-based applications. Do the following:
Select Configuration, then Applications, and then Suites. Click New suite. The dialog shown in Figure 1-3 appears.
Specify a name for the suite. The name must be unique across suites, services, and applications, and is restricted to a maximum of six characters. Note that the suite cannot be renamed later.
Use the remaining fields to specify the scope of the suite. This is defined in terms of partial page URLs. Note that as you enter this information, you can see the effect of your definition through the Filter preview column. Note that if a wildcard character (*) is not specified within the Domain field, network traffic arriving on a non-standard port (that is, 80/443), is not associated with the suite. The use of blank filters is not permitted. All specified characters (other than the wildcard character) are interpreted as literals. When ready, click Next. The dialog shown in Figure 1-4 appears.
Important:
It is recomended that filters definitions be mutually exclusive across suites, applications, and services. For example, do not define a suite filtered on the domainus.oracle.com
, and then another suite, application, or service filtered on us.oracle.com/application_servlet
. The use of non-mutually exclusive filter definitions can lead to unpredictable results.This dialog allows you to specify the Oracle Enterprise architecture upon which the suite is based. The number of options available in this menu depends on the suite packages currently installed. Select the option E-Business Suite. When ready, click Finish. The suite definition you have specified is displayed. An example is shown in Figure 1-5.
If your EBS suite instance uses socket mode, click the Identification tab, and use the Add new filter item to ensure that the IP addresses and port numbers for all Forms servers are specified. An example is shown in Figure 1-5.
Note that the filter definition must specify both the IP address and port number, as well as the domain and any URL prefix you wish to specify. In addition, be aware that wildcard characters (*) within IP address and port number definitions are not supported.
If your EBS applications make use of Forms, click the Forms tab. The suite overview changes to that shown in Figure 1-6 appears.
The use of these settings is explained in the following section.
Within RUEI, session information is based on cookies. The cookies are used to connect hits to a specific visit. In general, the cookie is also connected to the user login page which allows RUEI to include a user name to all subsequent hits with the same cookie. There are already some cookies available in EBS. However, these are not generally usable. The main problems with them are they not sufficiently unique (for instance, oracle.uix
), and not wide enough (for instance, JSESSIONID is only used for the /OA_HTML/
part of the Web site).
It is recommended that you implement a client-side cookie mechanism. The procedure to do so is described in the Oracle Real User Experience Insight User's Guide.
Note:
Within a Forms-only environment, if visitors logon to applications within Forms, the user ID is automatically tracked on the Forms logon page.To verify your cookie configuration, do the following:
Clear all cookies in the browser.
(Re)login to the EBS application.
Execute some actions that load Oracle Forms.
Execute some actions in Oracle Forms.
Logout.
Wait for at least 10 minutes.
Open the RUEI Reporter environment.
Select Browse data, open the All sessions group, select Session diagnostics, and locate the recorded session (by user ID or time). You can filter on applications.
Open the session and verify that:
There where more page views than just the login page. This verifies that the session ID is preserved in the OA framework after the login.
At least some Oracle Forms activity has been recorded with "unidentified action". This verifies that servlet calls are recorded correctly.
The page names reported within the Data Browser indicate events similar to those highlighted in Figure 1-7.
When not all hits are connected with the same cookie, it is recommended that you investigate where the problem is located (for instance, the domain or path option of the cookie), and resolve it in the appropriate manner.
The tracking mechanisms that should be specified for the Correlation variable and Session URL argument are best determined through a number of flow charts.
Forms Session URL Argument
Figure 1-8 shows how the Session URL argument can be determined. If running in socket mode, this setting is not applicable. Otherwise, the Forms URL should be examined for an argument that provides a unique value for each Forms session. Typically, this argument is located after a semicolon or question mark character in the URL. For example, jsessionid
or JServSessionIdforms
.
Correlation Variable
The Correlation variable allows the sessions (on TCP and socket mode) to be merged into one end-user session. Figure 1-9 shows how the Correlation variable can be determined.
If unique client IP addresses are used, then this setting is not applicable. If running in socket mode, sessions are annotated with the value from the Correlation variable (available via "INDEX_INITIAL_CMDLINE") available on both HTTP and socket-mode traffic. For EBS environments, this will always include the icx_ticket
variable. For non-EBS environments, some other variable must be specified. On the HTTP layer, the variables are found in the query part of Forms-initializing calls, or in constructions such as gp1
=....&
gv1
=...
, where gp1
specifies the value name.
On the HTTP layer, you might observe the following:
/OA_HTML/frmservlet?…&gp15=icx_ticket&gv15=255. 184.210.99jE82BtqiYLHJ8T6-bLxTLw…
Alternatively:
/OA_HTML/frmservlet?…&env=NLS_LANG='AMERICAN_AMERICA'+…+icx_ticket='255.184.210.99.jE82BtqiYLHJ8T6-bLxTLw..'+…
Note that, on the Forms layer, the variable "INDEX_INITIAL_CMDLINE" can be found in the Collector log files. For example:
&Runform-001.INDEX_INITIAL_CMDLINE=server module=/oracle/r12/VIS12/apps/apps_st/appl/fnd/12.0.0/forms/US/FNDSCSGN fndnam=APPS config='VIS12' icx_ticket='255.184.210.99.jE82BtqiYLHJ8T6-bLxTLw..' resp='FND/APPLICATION_DEVELOPER' secgrp='STANDARD' start_func='FND_FNDPOMPO' other_params=…
Session Tracking Cookie
Figure 1-10 shows how the session tracking cookie can be determined.
If unique client IP addresses can be identified, then the default client IP-based tracking can be used. Otherwise, if a cookie with a unique value across the full host is available, then this can be created using JavaScript (as described in the Oracle Real User Experience Insight User's Guide). Otherwise, the default EBS (JSESSIONID) tracking scheme should be used.
For example, consider the situation in which it is not possible to modify the login page to add a session cookie. In that case, some other EBS cookie within the non-Forms traffic might be selected (for example, JSESSIONID), and the correlation variable can be used in this case to connect non-Forms traffic with Forms-based traffic. Here, non-Forms hits would be identified using JSESSIONID, shared hits identified by a combination of JSESSIONID and the correlation argument, and Forms hits by the combination of the session-tracking variable jsessionid
and the correlation argument in the initial command line.
The Forms socket mode setting enables you to prevent active socket-mode sessions being discarded by the Collector after they have been inactive for a few minutes. It is recommended that you specify the timeout used within your EBS environment. Note this setting is only relevant for Forms socket mode.
To specify the Forms socket mode timeout, do the following:
Select Configuration, then General, then Advanced settings, and then Collector Forms settings. Use the View menu to select the required Collector. The System (localhost) represents the Collector running on the Reporter system. Click the currently defined Forms socket mode timeout setting. The dialog shown in Figure 1-11 appears.
Specify (in minutes) the socket mode timeout. The default is 10 minutes. When ready, click Save.
You are prompted to restart the Collector. This is necessary in order to make your changes effective. Note you can also restart the selected Collector by clicking the Restart Collector icon in the toolbar.
Note that you can specify the Forms socket mode timeout to be somewhat higher than the EBS environment timeout. However, be aware that while this has the advantage that sessions are more likely to be successfully detected and monitored, it can increase the amount of required memory.
In order for RUEI to understand how the EBS frameworks are implemented within your environment, do the following:
Copy the create_EBS_info.pl
script to the home directory of the EBS server. It is located in the /var/opt/ruei/processor/local/download/ebs
directory of the RUEI system.
Run the create_EBS_info.pl
script as any user on the EBS serverFoot 1 . This script assigns an identification to the identified page IDs within the environment. The create_EBS_info.pl
script must be run with the following syntax:
create_EBS_info.pl -part=all|DB|JTT|FORM [-connectstring=connectstring] [-debug] [-exeloc=exedir] [-dir=dir1,dir2]
where:
the part
option specifies the subset of files to be generated. You can specify the following:
all
: generates all files. This is the default, and is a combination of the three options listed below.
DB
: this option is primarily intended for EBS environments, and generates a subset of the configuration file. If you use this option (or the all
option), you must specify the -connectstring
parameter. In addition, you must specify the -exeloc
parameter. This should specify the location of the SQLPlus executable if it is not in one of the directories in the PATH.
JTT
: this option is primarily intended for EBS environments, and generates all Java-based files. The location of the Java files is based on the APPL_TOP setting. Otherwise, the directories specified with the -dir
parameter are used.
FORM
: this option is primarily intended for Forms-based environments, and generates all Forms-based files. If you specify this option (or the all
option), you must specify the -exeloc
parameter. This should specify the location of the frmcmp
or frmcmp_batch
executable if they are not in one of the directories in the PATH. The location of the Forms (.fmb
) files is based on the APPL_TOP setting. Otherwise, the directories specified with the -dir
parameter are used.
connectstring
specifies the string passed to SQLPlus to gain access to the database.
debug
specifies debug mode should be enabled.
execloc
specifies that the executable is not in one of the directories in the PATH, and that the exedir
directory should be searched. Note that multiple directories must be separated with a comma, or by specifying the -exeloc
option multiple times.
dir1
, dir2
, and so on, specify the directories to search for Java or Forms-related information. Note that multiple directories must be separated with a comma, or by specifying the -dir
option multiple times.
The script reads from the APPLSYS schema, and generates .txt
files in the current directory. For example:
perl create_EBS_info.pl -part=all -connectstring=APPS/APPS@linux-ebs-r12-pc:1522/VIS12 perl create_EBS_info.pl -part=all -connectstring=APPS/APPS@VIS12
In multiple instance environments, run the script for each required instance, and separately preserve their created .txt
files. In addition, create a separate suite definition for each instance, as described in Section 1.6, "Creating the EBS Suite Definition".
Note:
If you create new customizations (or make changes to existing customizations) to your EBS applications, you will need to re-run the script, and re-import the generated zip file.The script creates a number of .txt
files in the directory where the script is executed. All relevant .txt
files are collected and stored in a .zip
file. Copy this .zip
file to a location that can be used for uploading the files to the RUEI Reporter system.
Select Configuration, then Applications, then Suites, and select the suite you defined earlier in Section 1.6, "Creating the EBS Suite Definition,". Click Upload Configuration. The dialog shown in Figure 1-12 appears.
Specify the name of the .zip
file containing the generated .txt
files. If you manually create .txt
files, you should use the same structure present in the .zip
file. To protect against receiving empty definitions, the upload will fail when it contains empty .txt
files. When ready, click Upload.
Note:
If you receive warning or error messages while running thecreate_EBS_info.pl
script, see Section B.7, "create_EBS_info.pl Script Generates Warnings/Errors," for important troubleshooting information.The Perl Interpreter
By default, the Perl interpreter is not shipped with Microsoft Windows. It is often installed as part of the Oracle database, as well as some other Oracle products. To locate the Perl interpreter on a Microsoft Windows system, select Start > Find > Find for files > perl.exe
. Use the located executable to run the configuration script.
When no Perl executable is available, you can run the DB
part of the above query from the RUEI system (providing that a connection to the EBS database from it is possible). This can be achieved by using the -part=DB
option with a connectstring
that refers to the APPS scheme in the EBS database on the remote host. Note that only the database-based EBS customizations are generated (and not the JTT/Java-based customizations or Forms-based changes).
Note that if you skip running the create_EBS_info.pl
script, RUEI will still report on EBS and Forms activities. However, the reported names will not reflect your customizations. For example, responsibilities will be reported using the responsibility-key instead of the responsibility name, and Forms will be reported using the formname instead of a functional description of the form. This may be acceptable in environments with little customization.
To ensure the quality of the data being collected and reported by RUEI for your EBS-based applications, it is strongly recommended that you verify their reported details. You should pay particular attention to the number of associated pages detected for the defined suite(s).
Select Browse data, then select the All pages group, and then the Application sub-group. Within the individual dimensions, such as Page views and hits, you can see that page views are reported for several applications. The suite name in the definition is shown between brackets. An example is shown in Figure 1-13.
Note:
The Unique pages identified counter and the Last page identified indicator (shown in Figure 1-5) are disabled. Similarly, the manual page naming facility (described in the Oracle Real User Experience Insight User's Guide) is not available.You can also open an overview of the monitored network traffic by selecting System, then Status, and then Data processing. This provides you with immediate information about hits, pages, and session processing, as well as the system load.
For further information on the user of this and other monitoring facilities, refer to the Oracle Real User Experience Insight User's Guide.
Currently, RUEI does not work with all EBS functionality. In particular, the following known limitations exist:
The Forms framework includes functionality to create reports. This functionality is highly configurable by customers. As a result, it is not possible to track reports automatically. In addition, there is no useful translation table with a relevant business-oriented name for the reports. The only solution would to rewrite the known report URLs to correct report names based on a translation file.
An additional side note on this issue is that some customers are using the 'jobs' functionality to create reports. This is an insecure way to do this, because the next and previous numbers can easily be guessed, and allows users to see reports they may not be authorized to view. Because of the randomness of the name (only a number), it is not useful to report on these type of reports when they are used.
As a result of the issues described above, Forms reports are not monitored.
Reporting is based on the last activated area. Hence, when an end-user is browsing simultaneously in multiple browser windows, the reported page name might contain incorrect information.
Currently, only applications based on the OA and JTT frameworks are supported. Therefore, such packages as Oracle Applications Manager (OAM) and Oracle Portal are not supported at this time.
Footnote Legend
Footnote 1: The script can also be run in the acceptance environment if it is equivalent to the production environment.