Monitoring EntireX Components

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

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

Start of instruction setTo monitor your current broker

  • Choose option 2 from the EntireX Command-line Script 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> <Password>
    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)
      <Password> is your password (no default)

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 myPassword

Sample output:

graphics/monitorObj_broker_example.png

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

Start of instruction setTo monitor the services registered your current broker

  • Choose option 3 from the EntireX Command-line Script 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> <Password>
    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)
      <Password> is your password (no default)

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 * * MyUser MyPassword

Sample output:

graphics/monitorObj_services_example.png

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

Start of instruction setTo monitor the clients calling your current broker

  • Choose option 4 from the EntireX Command-line Script 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> <Password>
    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)
      <Password> is your password (no default)

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 myPassword

Sample output (truncated):

graphics/monitorObj_clients_example.png

Default Handling

You can customize the defaults used for the monitoring scripts.

Start of instruction setTo customize the defaults

  1. Choose option 6 from the EntireX Command-line Script 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.