Using Logs to Monitor Components

BRM records system activity in log files. One log file is generated for each component or application. Review these files daily to monitor your system and detect and diagnose system problems. You can also:

Write scripts to look for certain conditions, such as types or numbers of errors, and to notify you when these conditions occur.
Record opcode calls in the CM log file. See "Recording Opcode Calls in the CM Log File".

BRM generates log files for system components, applications, and client applications.

For system processes (or threads) such as CMs and DMs, BRM uses two types of log files:

Those that record normal startup activity are named program.log (for example, cm.log, js.log, and dm.log).
Those that record activity, such as error conditions, while the system is running. These pinlogs are named program.pinlog (for example, cm.pinlog, js.pinlog, and dm_oracle.pinlog).

For BRM applications, log files are named program.pinlog (for example, pin_billd.pinlog). If an application is missing a configuration file (pin.conf) or if the application fails before it can read the configuration file, it records errors in the default.pinlog log file.

Note:

Calls made by opcodes to get data from objects are not recorded in log files.

BRM Java-based applications, such as Customer Center and Configuration Center, by default do not use log files. However, you can enable error logging by adding entries to the Infranet.properties file that provide configuration information when the application starts.

Log files for system components are stored in BRM_home/sys/component. For example, the CM log file is in BRM_home/sys/cm.

If there is no log file in BRM_home/var/component, the default.pinlog file is used instead. It is stored in BRM_home/sys/component. For example, the CM pinlog file is BRM_home/sys/cm/default.pinlog.

For an application or client application log file, the default location is the directory from which the program was started.

You can leave log files in their default locations or move them.

Large log files degrade system performance. Check the sizes of log files periodically and delete or archive large files. When you delete or rename a log file, a new empty file is created as soon as a new log entry is created and either a maximum of four hours have elapsed or the application is stopped and restarted. Be especially vigilant when using new custom applications, which commonly makes log files grow quickly.

Log files should be archived weekly to a safe storage area.

Changing the Name or Location of a Log File

To change the name or location of the pinlog file for a component or application:

Open the configuration file (pin.conf or Infranet.properties) for the component or application.
Change the relevant entry:
- logfile: Applications
- cm_logfile: CM
- dm_logfile: DM
Enter the desired name and directory for the log file.
Save and close the file.
Stop and restart the component or application.
Note:
- You can change the name of the default application's log file by using the PIN_ERR_SET_LOGFILE function. See BRM Developer's Reference.
- For Payment Tool, you cannot change the name of the log file. For Java-based BRM client applications, use an Infranet.properties file to specify the name and location of a log file.

Setting the Reporting Level for Logging Messages

By default, BRM components report error messages, and BRM applications report both error and warning messages. You can set BRM to report debugging messages or to not report errors. The four levels of error reporting are:

0 = no logging.
1 = (default) log error messages only.
2 = log error messages and warnings.
3 = log error, warning, and debugging messages.

Note:

To avoid performance degradation, use only level 3 logging for debugging.

A common implementation is to use 2 and use a script to detect and act on warning messages.

To change the severity level for logging:

Open the configuration file (pin.conf or .properties) for the component or application.
Edit the loglevel entry. The notes in the configuration file define the options.
Save and close the file.
Stop and restart the component or application.

Setting the Log Level for a Specific Opcode

You can record debug-level information for a specified opcode without having to reset the default system log level. This enables you to monitor the activity of a specific opcode (and any opcode it calls) without impacting system performance.

When you enable opcode logging, the logging level is increased to debug level 3 for the specified opcode only; all other opcodes are logged at the level specified in the CM pin.conf file.

You can define how many times during a CM session the debug-level reporting occurs for the specified opcode before the default reporting level is restored. This enables you to increase the logging level without having to stop and restart the CM to reset it to the default level.

Open the CM pin.conf file in BRM_home/sys/cm.
Set the pinlog_debug_opcode entry:
```
cm pinlog_debug_opcode opcode
```
where opcode is the opcode name or opcode number.

Note:

If this entry is not set, BRM uses the loglevel entry in the CM pin.conf file to determine the log level.
Set the pinlog_debug_op_count entry:
```
cm pinlog_debug_op_count number
```
where number is the number of times the opcode is recorded at the debug level before the default log level is restored.
Save and close the file.
Restart the CM.

Recording Opcode Calls in the CM Log File

You use the enable_pcm_op_call_stack and max_pcm_op_call_stack_entries CM pin.conf entries to record opcodes in the CM log file.

When enable_pcm_op_call_stack is enabled, the opcodes that are called by BRM clients are recorded in the CM log file.

See "Connection Manager (CM) pin.conf Entries".

About Formatting Log Files

You can format a log file to improve readability and traceability of errors by using the splitPinlog script. This script splits a log file into multiple files, one for each combination of process ID (PID) and thread ID (TID) based on the information in the header of the pinlog entries.

To format a log file:

Go to the BRM_home/bin directory.
Run the following Perl script:
```
splitPinlog original_pinlog_file
```

The Perl script creates a file with the name original_pinlog_file.pid.tid.pinlog.

For example, running the command:

splitPinlog cm.pinlog

results in these file names:

cm.pinlog.342353.12.pinlog
cm.pinlog.342353.13.pinlog