Scenario: "I want to monitor an EntireX component (broker, service, client) over time."

EntireX provides multiple scripts to monitor - at a specified interval - your standard broker, registered services, and clients that call your broker. Output is written to a CSV file. This document covers the following topics:

• Monitoring Broker

• Monitoring Services

• Monitoring Clients

• Default Handling

---

Monitoring Broker

Scenario: "I want to monitor my standard broker over time."

Script monitor_broker_to_csv.bat writes key broker usage information to a CSV file. The report includes information such as active workers, clients, servers, allocated storage etc. The report is appended at a specified interval until the script is stopped.

• Calling the Script

• Example

Calling the Script

To monitor your current broker

• Choose option 2 from the EntireX Monitoring Scripts menu, "Monitor Broker".

  Or:
  Enter one of the following commands:

  monitor_broker_to_csv.bat

  monitor_broker_to_csv.bat <BrokerId>

  monitor_broker_to_csv.bat <BrokerId> <Time> <UserId> FILE <EncryptedPasswordFile>

  where	<BrokerId>	is the ID of the broker to be monitored (default localhost:1971), and
  	<Time>	is the interval between reports in seconds (default 60)
  	<UserId>	is your user ID for broker calls if your broker is running with EntireX Security (no default)
  	<EncryptedPasswordFile>	is a file containing your encrypted password. See Using an Encrypted Password.

  The parameter FILE indicates that the encrypted password will be read from the specified file.

  Notes:

  1. The file containing the encrypted password must be located at %HOMEDRIVE%%HOMEPATH%\documents\Software AG\EntireX, or specify the complete file path. Enclose the file name in quotes (" ") if the file path or file name contains blanks.
  2. The cleartext <Password> option of earlier versions is deprecated but still supported in this version.

The first time you execute this script in a session, the results are displayed on screen so you can verify that the correct data is returned. You can override this behavior using environment variable MONITOR_VERIFY. Example:

set MONITOR_VERIFY=NO

The results of subsequent executions are written to a CSV file, with a new line created for each call. Default is <drive>:\Users\user_id\documents\SoftwareAG\EntireX\out_monitor_broker.csv. See also Default Handling. Use environment variable MONITOR_BROKER_OUTFILE to specify a different output file. Example:

set MONITOR_BROKER_OUTFILE=c:\my_monitor_broker_outfile.csv

The content is based on broker information object BROKER-OBJECT (Struct INFO_BKR).

CSV Column	Field Name of BROKER-OBJECT
Uptime (seconds)	RUNTIME
Active Workers	NUM-WORKER-ACT
Servers	SERVER-ACT
Server HWM	SERVER-HIGH
Clients	CLIENT-ACT
Client HWM	CLIENT-HIGH
Services	SERVICE-ACT
Conversation HWM	CONV-HIGH
Allocated Storage (bytes)	TOTAL-STORAGE-ALLOCATED
Storage HWM (bytes)	TOTAL-STORAGE-ALLOCATED-HIGH

where HWM=high watermark

The script will run until it is cancelled, for example with ctrl+C or by closing the command window.

Example

Sample command:

monitor_broker_to_csv.bat localhost:1971 10 myUserId FILE myEncryptedPasswordFile.txt

Sample output:

Monitoring Services

Scenario: "I want to monitor the services registered to my standard broker over time."

Script monitor_service_to_csv.bat writes key service usage information on external services registered to the current broker to a CSV file. The report includes information such as Class/Server/Service, active servers, number of requests, number of times the server was busy, pending conversations etc. The report is appended at a specified interval until the script is stopped.

By default, services with CLASS=RPC and SERVICE=CALLNAT are monitored.

• Calling the Script

• Example

Calling the Script

To monitor the services registered your current broker

• Choose option 3 from the EntireX Monitoring Scripts menu, "Monitor Services".

  Or:
  Enter one of the following commands:

  monitor_service_to_csv_file.bat

  monitor_service_to_csv_file.bat <BrokerID>

  monitor_service_to_csv_file.bat <BrokerID> <Time> <Class> <Server> <Service> <UserId> FILE <EncryptedPasswordFile>

  where	<BrokerId>	is the ID of the broker to be monitored (default localhost:1971), and
  	<Time>	is the interval between reports in seconds (default 60)
  	<Class>	is the class to be monitored (default RPC)
  	<Server>	is the server to be monitored (default *)
  	<Service>	is the service to be monitored (default CALLNAT)
  	<UserId>	is your user ID for broker calls if your broker is running with EntireX Security (no default)
  	<EncryptedPasswordFile>	is a file containing your encrypted password. See Using an Encrypted Password.

  The parameter FILE indicates that the encrypted password will be read from the specified file.

  Notes:

  1. The file containing the encrypted password must be located at %HOMEDRIVE%%HOMEPATH%\documents\Software AG\EntireX, or specify the complete file path. Enclose the file name in quotes (" ") if the file path or file name contains blanks.
  2. The cleartext <Password> option of earlier versions is deprecated but still supported in this version.

The first time you execute this script in a session, the results are displayed on screen so you can verify that the correct data is returned. You can override this behavior using environment variable MONITOR_VERIFY. Example:

set MONITOR_VERIFY=NO

The results of subsequent executions are written to a CSV file, with a new line created for each (active) Service. Default is <drive>:\Users\user_id\documents\SoftwareAG\EntireX\out_monitor_service.csv. Specify a different output file with environment variable MONITOR_SERVICE_OUTFILE. Example:

set MONITOR_SERVICE_OUTFILE=c:\my_monitor_service_outfile.csv

The content is based on broker information object SERVICE-OBJECT (Struct INFO_SV).

CSV Column	Field Name of SERVICE-OBJECT
Class	SERVER-CLASS
Server	SERVER-NAME
Service	SERVICE
Active Servers	SERVER-ACT
Server Busy (count)	NUM-SERV-OCC
Requests	REQ-SUM
Pending Conversations	NUM-PEND
Pending Conversations HWM	PEND-HIGH
Active Conversations	CONV-ACT
Conversation HWM	CONV-HIGH
Server Wait (count)	NUM-WAIT-SERVER

where HWM=high watermark

The script will run until it is cancelled, for example with ctrl+C or by closing the command window.

Example

Sample command:

monitor_service_to_csv_file.bat localhost:1971 10 RPC * * myUserId FILE myEncryptedPasswordFile.txt

Sample output:

Monitoring Clients

Scenario: "I want to monitor the clients calling my standard broker over time."

Script monitor_client_to_csv.bat writes key usage information on clients calling the current broker at a defined interval to a CSV file. The report includes information such as user ID, token, wait time, Class/Server/Service, hostname, environment information, start time and IP address etc. The report is appended at a specified interval until the script is stopped.

• Calling the Script

• Example

Calling the Script

To monitor the clients calling your current broker

• Choose option 4 from the EntireX Monitoring Scripts menu, "Monitor Clients".

  Or:
  Enter one of the following commands:

  monitor_client_to_csv.bat

  monitor_client_to_csv.bat <BrokerId>

  monitor_client_to_csv.bat <BrokerId> <Time> <UserId> FILE <EncryptedPasswordFile>

  where	<BrokerId>	is the ID of the broker to be monitored (default localhost:1971), and
  	<Time>	is the interval between reports in seconds (default 60)
  	<UserId>	is your user ID for broker calls if your broker is running with EntireX Security (no default)
  	<EncryptedPasswordFile>	is a file containing your encrypted password. See Using an Encrypted Password.

  The parameter FILE indicates that the encrypted password will be read from the specified file.

  Notes:

  1. The file containing the encrypted password must be located at %HOMEDRIVE%%HOMEPATH%\documents\Software AG\EntireX, or specify the complete file path. Enclose the file name in quotes (" ") if the file path or file name contains blanks.
  2. The cleartext <Password> option of earlier versions is deprecated but still supported in this version.

The first time you execute this script in a session, the results are displayed on screen so you can verify that the correct data is returned. You can override this behavior using environment variable MONITOR_VERIFY. Example:

set MONITOR_VERIFY=NO

The results of subsequent executions are written to a CSV file, with a new line created for each (active) client. Default is <drive>:\Users\user_id\documents\SoftwareAG\EntireX\out_monitor_service.csv. See also Default Handling. Use environment variable MONITOR_CLIENT_OUTFILE to specify a different output file. Example:

set MONITOR_CLIENT_OUTFILE=c:\my_monitor_client_outfile.csv

The content is based on broker information object CLIENT-SERVER-PARTICIPANT-OBJECT (Struct INFO_CS).

CSV Column	Field Name of BROKER-OBJECT
UserID	USER-ID
Token	TOKEN
Unique User ID	P-USER-ID
Status	STATUS
Wait Conversation Type	WAIT-CONV-TYPE
Wait Class	WAIT-SERVER-CLASS
Wait Server	WAIT-SERVER-NAME
Wait Service	WAIT-SERVICE
Last Active (seconds)	LAST-ACTIVE
Sum Conversations	SUM-CONV
HostName	HOST-NAME
Application	APPLICATION-NAME
Application Type	APPLICATION-TYPE
Application Version	APPLICATION-VERSION
Start Time	CREATE-TIME
IPV4	IP-ADDRESS
IPV6	IPV6-ADDRESS

The script will run until it is cancelled, for example with ctrl+C or by closing the command window.

Example

Sample command:

example monitor_client_to_csv.bat localhost:1971 10 myUserId FILE myEncryptedPasswordFile.txt

Sample output (truncated):

Default Handling

You can customize the defaults used for the monitoring scripts.

To customize the defaults

1. Choose option 6 from the EntireX Monitoring Scripts menu, "Edit Broker and other defaults (persistent)".

   Or:
   Enter command edit_user_specific_monitor_defaults.

   This copies file default_values_for_monitor_to_csv_file.bat to directory <drive>:\Users\user_id\documents\SoftwareAG\EntireX (if it does not already exist) and opens a text editor, for example Notepad.

2. Edit the file to match your environment settings. You can change defaults such as:

   • broker ID

   • default timeouts for the monitoring scripts

   • output files for the monitoring scripts

   The changes you make here are persistent: they apply to all subsequent sessions.

If your broker is running with EntireX Security you can specify a file containing an encrypted password instead of a cleartext password.