Forms Diagnostics Agent

Forms Diagnostics Agent or Forms Metrics Agent enables the user to analyze various performance-related information about Forms applications running in your environment.

Note:

For Forms Diagnostics Agent to work, see Installing and Configuring Oracle Forms.

This agent accesses the metrics data (available in DMS) at regular time intervals and populates the database tables. This process allows the user to access the data collected as historical data. The deployment of Forms Diagnostics agent is optional. The agent application provides an interactive interface where the user can specify the frequency of data collection and also control the starting and stopping of data collection. This can be achieved by performing the tasks in the following sections:

Setting up the Database Schema

To set up DB schema for Forms Diagnostics Agent, you must create a user and schema in the database. The user can choose a database instance of their choice. There is no special database that is installed with Forms or the diagnostic agent.

Create a User in Database

Note:

Before creating a user in the database, ensure that the user name provided by you is new and does not already exist. This is because the .sql script (used to create the user in the database) overwrites the user (user name provided during the creation) with the new user.

To create a user in the database, perform the following steps:

Log in to the database as sysdba as shown below:

sqlplus sys/<sys-password>@<DB> as sysdba
Run the following script:

@ORACLE_HOME/forms/forms_create_diagnostics_user.sql.
The user must enter the userID and password.

The user is created in the database.

Create a Schema in Database

Note:

Before creating a schema in the database, ensure that the user name provided by you is new and does not already exist. This is because the .sql script (used to create the schema in the database) overwrites the schema (user name provided during the creation) with the new schema.

To create a schema in the database, perform the following steps:

Log in to the database as the user that you created in the above steps:

sqlplus <user>/<password>@<DB>
Run the following script:

@ORACLE_HOME/forms/forms_create_diagnostics_schema.sql

The schema is created in the database.

Setting up a Data Source in WebLogic

After setting up the database to work with the Forms Diagnostics Agent, you must set up a data source using the Weblogic console.

To setup a data source using the Weblogic console, perform the following steps:

Log into the WebLogic console.
In the left navigation panel, select Services and navigate to Data Sources.

Click Lock and Edit in the Change Center window to make changes.
In the Summary of JDBC Data Sources page, click Configuration.

In the Data Sources table, click New and select Generic Data Sources from the list.
Enter the values for the following parameters:

name for the JDBC Data Sources

The user can enter any name.

JNDI name

oracle/forms/agentDS

Database Type

Choose type of database that you used to create user and schema in the previous steps.

Click Next. The Create a new JDBC data sources page appears.
Select Database driver from the list of drivers available for the type of database you have selected. Click Next.
Enter the values for the following parameters:

Database Name

Host Name

Port

Database User Name

Enter the user name that you used while creating a user in the database in the steps above.

Password

Enter the password that you used while creating a user in the database in the steps above.

Click Next.
In the next page, click Test Configurations at the top left corner to check if the database has been configured successfully.

Click Next.
Select Admin Server as a target to deploy the data source.

Click Finish.
Click Activate Changes in the Change Center window to save changes.

You have now set up a JDBC data source.

Deploying Forms Diagnostics Agent

After setting up a data source in Weblogic, Forms Diagnostics agent must be deployed to the Weblogic Admin Server.

To deploy Forms Diagnostics agent, perform the following steps in the Weblogic console:

Log into the Weblogic Console.
In the left navigation panel, select Deployments.

Click Lock and Edit in the Change Center window to make changes.
In the Summary of Deployments page, click Install.

The Install Application Assistant page appears.
Enter the path of the .war file as shown below:

ORACLE_HOME/forms/j2ee

This is the location of the formsagentapp.war file.
Select the formsagentapp.war file. Click Next.

The Choose Targeting Style page appears.
Select Install this deployment as an application.
Select Admin Server as a target to deploy Forms Diagnostics Agent. Click Next.
Leave the optional settings at their default values and click Finish.

Click Activate Changes in the Change Center window to save changes.

The Forms Diagnostics agent has been successfully deployed to the Weblogic Admin Server.

To start the application, select formsagentapp from the list of deployed applications and Click Start.

Managing the Data Collection

The Forms Diagnostics agent allows the users to manage data collection using an interface.

The user can specify the frequency of data collection and control the starting or stopping of data collection. This can be achieved by performing the following steps:

Log in to the agent console by using the following url:

http://<host>:<admin port>/formsagent/AgentConsole.jsp
Enter the user ID and password.

Any user with administrator's privileges can log in to the console.
Enter a value for the Frequency of Data Collection. This parameter is the time difference between two consecutive data collections.

The default value is 10 minutes. The minimum value should be one minute.
Click Start.

You will see a message indicating that the Forms Diagnostics Agent is running. Click Stop whenever you want to stop the collection of metrics by the agent.

Use the Agent Application

When the user prompts the agent application to start the collection of metrics, the agent collects the metrics from DMS and populates the database tables. The user can access this collected metrics in the database tables.

To bring this collected metrics into use, the user can create a frontend application which will be able to read this data and analyze the historical performance of Forms applications running in your environment by preparing charts, graphs, etc.

The primary and foreign key in each table has been mentioned in the respective tables. The following are the database tables that get populated during the collection of metrics by the Forms Diagnostics agent:

Table -52 ADMIN_SERVER Database Table

Serial Number	Column Name	Sample Value	Description
01	AGENT_ID	1	AGENT_ID is the primary key in the ADMIN_SERVER database table. ID of the agent application. Any integer value beginning with 1
02	ADMIN_HOSTNAME	myhost.mydomain.com	Name of the machine where admin server is deployed
03	ADMIN_PORT	7001	Port of the admin server

Serial Number

Column Name

Sample Value

Description

AGENT_ID

AGENT_ID is the primary key in the ADMIN_SERVER database table.

ID of the agent application. Any integer value beginning with 1

ADMIN_HOSTNAME

myhost.mydomain.com

Name of the machine where admin server is deployed

ADMIN_PORT

7001

Port of the admin server

Table -53 AGENT Database Table

Serial Number	Column Name	Sample Value	Description
01	AGENT_STATUS	Running	Status of the Agent
02	REAL_TIME	2009.07.23 at 17:11:41	Date and time when status is recorded All time entries are in UTC/GMT
03	SEQUENCE_ID	205	ID created by the agent each time the agent status is recorded
04	FREQUENCY	40	Time difference (in minutes) between two consecutive data collections
05	AGENT_ID	1	AGENT_ID is a foreign key in this database table. It refers to AGENT_ID in the ADMIN_SERVER database table ID of the agent application. Any integer value beginning with 1

Table -54 FRM_DB Database Table

Serial Number	Column Name	Sample Value	Description
01	FRM_DB_ID	8769	FRM_DB_ID is the primary key in the FRM_DB database table. ID assigned to the database that is used by the Forms application
02	DB_NAME	v11g	The database to which frmweb is connected. If it is connected to v11g, the this field will display v11g. This can be NULL when frmweb is not connected to any database
03	TNS_ENTRY	(DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = sample.host.com)(PORT = 1521))) (CONNECT_DATA = (SERVICE_NAME = v11g)))	TNS entry of the database to which frmweb is connected
04	USER_NAME	scott	The database user who has logged in

Table -55 FRM_DB_LOGIN Database Table

Serial Number	Column Name	Sample Value	Description
01	FRM_DB_LOGIN_ID	345	FRM_DB_LOGIN_ID is the primary key in the FRM_DB_LOGIN database table. ID assigned to each row in the table
02	FRM_RUNTIME_ID	107	FRM_RUNTIME_ID is a foreign key in this database table. It refers to FRM_RUNTIME_ID in the FRM_RUNTIME database table
03	FRM_DB_ID	1025	FRM_DB_ID is a foreign key in this database table. It refers to FRM_DB_ID in the FRM_DB database table ID assigned to the database that is used by the Forms application
04	REAL_TIME	2009.07.23 at 17:11:41	Date and time when status is recorded and metric data collected to update the table All time entries are in UTC/GMT

Table -56 FRM_RUNTIME Database Table

Serial Number	Column Name	Sample Value	Description
01	FRM_RUNTIME_ID	107	FRM_RUNTIME_ID is a primary key in the FRM_RUNTIME database table. ID that identifies the Forms process
02	WLS_APP_ID	5005	WLS_APP_ID is a foreign key in this database table. It refers to WLS_APP_ID in the WLS_APP database table Determines the Forms application in the WLS_APP table
03	FRM_USER_ID	1310	FRM_USER_ID is a foreign key in this database table. It refers to FRM_USER_ID in the FRM_USER database table ID assigned to the Forms client or client instance
04	CONFIG_VALUE		Configuration section name from `formsweb.cfg`
05	CONNECT_TIME	2009.07.23 at 17:11:41	Date and time when frmweb is spawned All time entries are in UTC/GMT
06	DISCONNECT_TIME	2009.07.23 at 18:15:43	Date and time when frmweb terminates All time entries are in UTC/GMT
07	STARTING_FORM_NAME	emp	Name of starting form
08	PROCESS_ID	8020	Process Id of frmweb on the middle tier machine
09	FRM_STATUS	Running / Exited	Status of frmweb
10	FRM_CPU_TIME_ON_EXIT	256	CPU time on exit of frmweb
11	FRM_PRIVATE_MEMORY_ON_EXIT	6385	Memory used by the Forms process at the time of exit
12	FRM_EXIT_CODE

Table -57 FRM_TRACE Database Table

Serial Number Column Name Sample Value Description

Serial Number	Column Name	Sample Value	Description
01	FRM_TRACE_ID	2679	FRM_TRACE_ID is the primary key in this database table. ID assigned to the rows in the FRM_TRACE database table
02	TRACE_FILE	forms_1055.trc	Name of the trace file when `ftrace` is enabled. It can be NULL if `ftrace` is disabled
03	TRACING	mytrace	The name of the trace group selected by the application

FRM_TRACE_ID

2679

FRM_TRACE_ID is the primary key in this database table.

ID assigned to the rows in the FRM_TRACE database table

TRACE_FILE

forms_1055.trc

Name of the trace file when ftrace is enabled. It can be NULL if ftrace is disabled

TRACING

mytrace

The name of the trace group selected by the application

Table -58 FRM_TRACE_USE Database Table

Serial Number	Column Name	Sample Value	Description
01	FRM_TRACE_USE_ID	1906	FRM_TRACE_USE_ID is the primary key in this database table. ID assigned to the rows in the database table
02	FRM_RUNTIME_ID	107	FRM_RUNTIME_ID is a foreign key in this database table. It refers to FRM_RUNTIME_ID in the FRM_RUNTIME database table ID that identifies the Forms process
03	FRM_TRACE_ID	2679	FRM_TRACE_ID is a foreign key in this database table. It refers to FRM_TRACE_ID in the FRM_TRACE database table ID assigned to the row in the database table
04	REAL_TIME	2009.07.23 at 17:11:41	Date and time when status is recorded and metric data collected to update the table All time entries are in UTC/GMT

Table -59 FRM_USER Database Table

Serial Number	Column Name	Sample Value	Description
01	FRM_USER_ID	1310	FRM_USER_ID is the primary key in this database table. ID assigned to the Forms client or client instance
02	CLIENT_IP	255.255.255.255	IP address of client machine from where the browser was launched and through which the user connected to the middle tier
03	SSO_USERID	fname.lname@myapp.com	Single Sign-On ID of the user who logged in.

Serial Number

Column Name

Sample Value

Description

FRM_USER_ID

1310

FRM_USER_ID is the primary key in this database table.

ID assigned to the Forms client or client instance

CLIENT_IP

255.255.255.255

IP address of client machine from where the browser was launched and through which the user connected to the middle tier

SSO_USERID

fname.lname@myapp.com

Single Sign-On ID of the user who logged in.

Table -60 HISTORY Database Table

Serial Number	Column Name	Sample Value	Description
01	FRM_RUNTIME_ID	107	FRM_RUNTIME_ID is a foreign key in this database table. It refers to FRM_RUNTIME_ID in the FRM_RUNTIME database table ID that identifies the Forms process
02	REAL_TIME	2009.07.23 at 17:11:41	Date and time when the snapshot is taken All time entries are in UTC/GMT
03	SEQUENCE_ID	205	ID created by the agent each time agent status is recorded.
04	FRM_BYTES_SENT	400	Number of bytes sent from the server to the client for this process so far
05	FRM_BYTES_SENT_DELTA	37	Difference in the number of bytes sent from the server to the client for this process since the previous reading of the agent was taken
06	FRM_BYTES_RECEIVED	200	Number of bytes sent from the client to the sever for this process so far
07	FRM_BYTES_RECEIVED_DELTA	23	Difference in the number of bytes sent from the client to the server for this process since the previous reading of the agent was taken
08	FRM_NETWORK_ROUND_TRIPS	30	Number of network round trips between the client and the server for this process so far
09	FRM_NETWORK_ROUND_TRIPS_DELTA	3	Difference in the number of network roundtrips between the client and the server for this process since the previous reading of the agent was taken
10	FRM_CPU_TIME	230	Total processing time taken by frmweb (in milliseconds) for this process so far
11	FRM_CPU_TIME_DELTA	47	Difference in the value of FRM_CPU_TIME since the previous reading of the agent was taken
12	FRM_PRIVATE_MEMORY	7998	Memory used by the Forms process at the time when snapshot was taken.
13	ITERATION	50	Number of times data is collected into the database table.

Table -61 WLS_APP Database Table

Serial Number	Column Name	Sample Value	Description
01	WLS_APP_ID	5005	WLS_APP_ID is the primary key in this database table. Determines the Forms application in the WLS_APP table
02	SERVER_TYPE	MANAGED	Type of the server (For example, MANAGED or ADMIN)
03	SERVER_NAME	WLS_FORMS	Name of the server
04	DEPLOYED_APPLN_NAME	formsapp	Forms Application name
05	FORMS_HOSTNAME	host52.example.com	Middle tier machine on which Forms runtime is running
06	INSTANCE_HOME_NAME	asinst_1	Name of the FMW instance home, where Forms runtime is deployed
07	CLUSTER_NAME	cluster_xyz	Name of the cluster where the Forms application is deployed
08	AGENT_ID	1	AGENT_ID is a foreign key in this database table. It refers to AGENT_ID in the ADMIN_SERVER database table. ID of the agent application. Any integer value beginning with 1

Limitations of the Agent Application

Forms Diagnostics agent has certain limitations on its deployment and usage.

The limitations are as follows:

The deployment of the Forms Diagnostics Agent application is optional. In case you want to analyze performance-related information about Forms applications, you must deploy Forms Diagnostics Agent manually post installation.
The agent application must be deployed to the Admin Server only. The agent application collects information about all Forms sessions that are running in the WLS domain of the Admin Server.
For the agent to be able to access the metrics data (available in DMS), the DMS application must be up and running.
The schema is designed to be functional only on one domain at any given time. You cannot use the same schema for multiple agents (running in separate domains).
Do not set the frequency of data collection to a small value. Setting the frequency of data collection to a small value slows down the production environment and causes excessive, needless data collection.
This utility only provides the database objects and the agent needed to perform the collection. It does not provide a user interface (UI) for exposing the collected data. Data can be retrieved by querying the tables outlined in the documentation above. Alternatively, a user interface can be developed using a preferred technology.