Run monitor scripts on UNIX
The SharePlex monitoring scripts notify you of events and conditions that can adversely affect replication on Unix or Linux systems. These scripts provide a monitoring mechanism without the need for frequent status checks through sp_ctrl. They can be run independently or through scheduled jobs.
SharePlex provides the following scripts:
- sp_eventmon monitors the SharePlex Event Log and reports errors that you specify in a special file.
- sp_logmon monitors how well Capture is keeping pace with the changes entering the redo logs. If Capture loses pace by a specified number of logs, sp_logmon alerts you before the logs wrap so that you can take corrective action.
- sp_ps monitors the SharePlex processes and notifies you if one or more are stopped so that you can correct the problem before the logs wrap or the queues exceed available disk space.
- sp_qstatmon monitors the status of the SharePlex queues and sends a warning if the backlog exceeds a threshold (limit) that you define. This enables you to take corrective action before the queues exceed available disk space and replication is adversely affected.
Important!
- These scripts run on Unix or Linux systems only.
- The monitoring scripts are overwritten with new scripts during patches and upgrades of SharePlex. Before you install the patch or upgrade, rename your existing scripts so that your customizing is retained. After applying the patches, update the new scripts with your customizing. Do not rename the existing scripts to replace the updated scripts, or you could lose important improvements or fixes.
Requirements for using the monitoring scripts
- These scripts must be run in the ksh shell.
-
All monitoring scripts must remain in the directory where they were installed. All but sp_ps are in the .app-modules directory of the SharePlex installation directory. The sp_ps script is in the util directory of the installation directory.
- The scripts must be customized to reflect your environment, such as the type of e-mail or the paging available.
-
To use the monitoring scripts, start sp_cop with the -uname name option, where name can be an identifier of your choice. Suggestions are:
- SharePlex must be running prior to executing a monitoring script.
-
Verify the ORACLE_HOME (the path to the ORACLE_HOME directory) for each Oracle instance being monitored.
- The monitoring scripts make use of sp_ctrl commands. Before you use the scripts, make a link in the util sub-directory to the sp_ctrl binary in the bin sub-directory of the SharePlex product directory. Do not copy the binary itself, because that makes it difficult to maintain patches to sp_ctrl.
-
Users of the monitoring utilities must have the following rights:
- Local access to sp_ctrl and permission to run the script on the system on which the sp_cop to be monitored is running.
- Korn (ksh) shell access and ps permission from the Unix or Linux command line.
- Read, write and execute permissions to the directory where the scripts reside.
- The permission on the iwgrep utility must be 755.
- The monitoring utilities use the mailx program to send e-mail notifications. Before using a script, make sure mailx is configured to send e-mail on all systems where the monitoring scripts will be deployed.
- Paging requires that your service provider supports receiving e-mails on your paging device.
- To kill any of the processes generated by these scripts, use the kill -9 command. The kill command alone does not kill all of the processes.
Monitor Oracle capture with sp_logmon
The sp_logmon monitoring script helps prevent situations where you must resynchronize your data because the Oracle redo logs wrapped before Capture was finished reading them. It monitors the redo log group to which Oracle currently is writing and determines which log SharePlex is reading.
If Capture loses pace by a specified number of logs, sp_logmon generates a warning in the logmon.log file and in an e-mail message, if that option is enabled. This gives you time to correct the cause of the delay and restore the archive logs, if necessary.
Prepare to run sp_logmon
Before running the script, perform the following tasks.
Satisfy requirements
See Requirements for using the monitoring scripts before you use this script. Note: The script must be run in the ksh shell.
Define email addresses
To use the e-mail notification feature, define the e-mail address(es) in the script before running it.
- Open the script in the app-modules directory of the SharePlex product directory.
-
Add any number of address strings after the MailUserName= variable. Use the full e-mail and/or pager address. Separate multiple entries with a comma, as shown in the following example:
MailUserName=scott@company.com,12345678910@pageservice.com
Important! If the person modifying the script is someone other than a SharePlex user, he or she needs to have these Oracle privileges:
- CONNECT privileges
- SELECT privileges for the V$LOG table
- SELECT privileges for the SharePlex internal tables
Run sp_logmon
Run the script from the util sub-directory of the SharePlex product directory, not from app-modules. When you run it from the util directory, you actually make a soft link that runs a utility which first sets up the correct environment before running the script itself.
Syntax
nohup sp_logmon -p port -t interval -l integer [-m ] [/dev/null] &
Table 4: Required arguments
| nohup sp_logmon |
Directs the script to continue running in the background if the user logs out. This ensures continuous monitoring. The sp_logmon component runs the script. |
| -p port |
Sets the port number for the instance of sp_cop that you are monitoring. You can monitor different SharePlex instances by running sp_logmon for each one, using different values for this argument. |
| -t interval |
Sets the time interval between scans in seconds. The value can be any positive integer. |
| -l integer |
Sets the maximum permissible number of redo logs between where Oracle is writing and where Capture is reading. This value triggers the warning generated by sp_logmon. Valid values are positive integers from 1 to the number of redo logs in the group. |
| & |
Runs the script in the background. |
Table 5: Optional arguments
| /dev/null |
Redirects the notification output to the /dev/null device on the local system so that the monitoring process continues to run in the background and generate output. To have the output appear on screen, omit this argument. |
| -m |
Enables the e-mail/paging option. Without this parameter, sp_logmon only logs errors to the log file. |
Monitor events with sp_eventmon
The sp_eventmon monitoring script monitors the SharePlex Event Log (event_log) at set intervals for entries relating to key replication events. You can define the scan interval and the error messages you want the script to detect. Each scan starts where the previous one stopped to keep the impact on the system minimal and prevent duplicate warnings.
The sp_eventmon script takes the following actions after each scan of the Event Log:
- When sp_eventmon detects an error that you defined, it prints a notification to the error.splex log file and an e-mail message, if that option is enabled.
- It logs each error, the error Event Log line number of the error, the sp_cop instance name (typically the port number), and the time and date of the error.
The script relies on the iwgrep program, the error_list file (described later), and a marker file named username.mrk (where username is derived from the string that you enter with the -s argument when you run sp_eventmon). These three components must be kept in the same directory as the script, or it will not function.
Note: The username.mrk file prevents duplicate warning messages from being sent to the log and to your e-mail or pager. Without this file, the script starts scanning the Event Log from the beginning every time it starts. Warnings that were previously generated are sent again.
Prepare to run sp_eventmon
Before running the script, perform the following tasks.
Satisfy requirements
See Requirements for using the monitoring scripts before using this script. Note: The script must be run in the ksh shell.
Define error messages
The sp_eventmon script scans for events listed in the error_list file, located in the util sub-directory of the SharePlex product directory. View that file for more information about the supported errors. You can add custom error strings to the error_list file by editing it in any ASCII text editor. Open the file and place each error string on a separate line.
Set IW_HOME
The IW_HOME variable in the script must be set to the correct value on each machine. This variable must point to the directory in which the monitoring scripts and iwgrep reside.
If the path is not correct:
- Open the script in the app-modules directory of the SharePlex product directory.
-
Set the path as shown in the following example:
IW_HOME=/export/home/splex/monscripts
Define e-mail addresses
To use the e-mail notification feature, define the e-mail address(es) in the script before running it.
- Open the script in the app-modules directory of the SharePlex product directory.
-
Add any number of address strings after the MailUserName= variable. Use the full e-mail and/or pager address. Separate multiple entries with a comma, as shown in the following example:
MailUserName=scott@company.com,12345678910@pageservice.com
Run sp_eventmon
NoteS:
- If you are running multiple instances of sp_eventmon, each instance must be run under the name of a different operating system user. Each username.mrk file will have a different username.
-
Use the truncate log command in sp_ctrl to truncate the Event Log frequently when you are running the sp_eventmon script. If the log grows too large, the iwgrep program cannot grep from it properly. When you issue the truncate log command, remove the username.mrk file. The next time you run sp_eventmon it will create a new file. See the SharePlex Reference Guide for more information about the truncate log command.
-
When there is an existing Event Log with errors in it and the script is running, issue the truncate log command and then delete the sp_cop_name.mrk file, where sp_cop_name is the value used in the -s argument when the script was run. This file is in the util sub-directory of the SharePlex product directory.
To run sp_eventmon
Run the script from the util sub-directory of the SharePlex product directory, not from app-modules. When you run it from the util directory, you actually make a soft link that runs a utility which first sets up the correct environment before running the script itself.
Syntax
nohup sp_eventmon -s 'sp_copname' -t interval -p path [-n name ] [-m] /dev/null &
Table 6: Required arguments
| nohup sp_eventmon |
Directs the script to continue running in the background if the user logs out. This ensures continuous monitoring. The sp_eventmon component runs the script. |
|
-s 'sp_copname' |
Sets the name of sp_cop that was used when sp_cop was started with the -u option. The name of sp_cop must be enclosed within single quote marks. You can use this parameter more than once to monitor multiple sp_cop instances on a system. Without this parameter, sp_eventmon will not start. |
| & |
Runs the script in the background. |
| -t interval |
Sets the time interval between scans in seconds. The value can be any positive integer. |
Table 7: Optional Components
| -p path |
Sets the path to the SharePlex variable-data directory. Without this variable, sp_eventmon assumes the default path. |
| /dev/null |
Redirects the notification output to the /dev/null device on the local system so that the monitoring process continues to run in the background and generate output. To have the output appear on screen, omit this argument. |
| -n name |
Sets the name of the Event Log if it is something other than the default name “event_log.” |
| -m |
Enables the e-mail/paging option. Without this option, sp_eventmon only logs errors to the log file. |
Monitor processes with sp_ps
The sp_ps monitoring utility monitors all SharePlex processes, including child processes, associated with a specified sp_cop instance. It scans the processes at regular intervals and reports abnormal conditions to one or more log files. It can monitor multiple installations of SharePlex on one or more systems, and it supports uni-directional and bi-directional (peer-to-peer) configurations.
Prepare to run sp_ps
Before running the script, perform the following tasks.
Satisfy requirements
See Requirements for using the monitoring scripts before using this script. Note: The script must be run in the ksh shell.
Set the scan interval
The scan interval specifies how long the sp_ps program waits between checks. The default is 2,000 seconds. To specify a different scan interval, follow these steps.
- Open the sp_ps file in the app-modules directory of the SharePlex product directory.
-
Set the interval= parameter to the required scan interval. Use any positive integer, for example:
interval=1500
Define email addresses
To use the e-mail notification feature, define the e-mail address(es) in the script before running it.
- Open the script in the util directory of the SharePlex product directory.
-
Add any number of address strings after the MailUserName= variable. Use the full e-mail and/or pager address. Separate multiple entries with a comma, as shown in the following example:
MailUserName=scott@company.com,12345678910@pageservice.com
Note: The e-mail/paging option is enabled by default for sp_ps, but confirm that it was not changed. In the script, MAILOPTION=TRUE enables e-mail notifications and MAILOPTION=FALSE disables them.
Run sp_ps
Run the script from the util sub-directory of the SharePlex product directory.
Syntax
nohup sp_ps ['sp_cop -u name'] CONFIGURATION [> /dev/null] [ &]
Table 8: Required arguments
| nohup sp_ps |
Directs the script to continue running in the background if the user logs out. This ensures continuous monitoring. The sp_ps component runs the script. |
| 'sp_cop -u name' |
Use this parameter if you are running more than one sp_cop process. Use it to specify each one of those processes that you want to monitor. This argument must reflect exactly the same name that was used when sp_cop was started with the -u option. It must be enclosed within single quote marks.Without the -uname option, sp_ps assumes you want to monitor the sp_cop that uses the default SharePlex port of 2100. |
| CONFIGURATION |
Specifies the type of configuration of the SharePlex instance being monitored. This value must be entered in CAPITAL letters. Valid values:
SOURCE — Use for uni-directional replication to monitor the Capture, Read and Export processes on the source system.
TARGET — Use for uni-directional replication to monitor the Import and Post processes on the target system.
MULTI-SOURCE — Use for peer-to-peer replication. It directs the script to monitor the Capture, Read, Export, Import and Post processes on each system.
Note: If replicating between source and target tables on the same system, there are no Export or Import processes. |
| > /dev/null |
Redirects the notification output to the /dev/null device on the local system so that the monitoring process can continue to run in the background and generate output. To have the output appear on screen, omit this argument |
| & |
(Ampersand) Runs the script in the background. |
