logMerger utility

Use the logMerger utility to merge Business Transaction Management system service log files (logdir) for analysis or archiving. You can use the -config flag to load the utility options from a named log merger configuration file. Command line options will override options defined in a configuration file.

The log merger configuration file is described after the discussion of the logMerger utility.

Command Syntax

logMerger -config config_file_name |-dir directory|-url url 
          [-username username -password password]  
          [-output output_file_name] [-overwrite true|false] 
          [-format format_pattern] 
          [[-from start_time -to end_time]|[-last number_of_hours]] 
          [-loggerName logger_name] [-loggerLevel level|level+] 
          [-className class_name] [-methodName method_name] 
          [-userName user_name] [-V]

Name	Description
-config	Load options from the named configuration file. Command line options override options defined in the configuration file. For an example of a `logMerger` configuration file, click here.
-dir	Directory that contains Business Transaction Management logdir directory you want to merge. The `logMerger` utility searches all subdirectories of the specified directory for logdir directories. You can provide multiple -dir directory options. Each directory must be a separate entry.
-url	URL of the running Business Transaction Management service whose logdir you want to merge, with the inclusion of the user credentials required to access the service. The `logMerger` utility will communicate with the service on this URL using the Business Transaction Management user credentials specified by the `-username` and `-password` options. You can provide multiple -url service URL options, but all services must have the same username and password credentials. Each URL must be a separate entry. Note: If you want to merge logging from multiple service URLs that require different username and password credentials for access to each service, you must use a logMerger configuration file.
-username	The username credential for access to the Business Transaction Management service associated with the url option. Note: The -username flag is different from the -userName flag described below; the two flag names are case-sensitive.
-password	The password credential for access to the Business Transaction Management service associated with the url option.
-output	Specifies where to save the merged result. The logMerger utility will exit without overwriting if the output file already exists, unless the -overwrite option has a value of "true". If no output option is specified, the resulting output file with be written to the directory from which the logMerger utility was called, with a default value of "logmerger_<date>_<time>.log".
-overwrite	Specify `true` to overwrite existing output file. Default is `false`.
-format	Specify the output format of each log entry in the merged result. Possible format tokens include log entry properties: `time` `methodName` `loggerName` `loggerLevel` `className` `userName` and four more special tokens: `message` - the actual log message `logName` - log identifier which is the 'logName' attribute found in the 'logHeader' element of each log file `eol` - end of line character to separate text `tab` - tab character to separate text Each format token is separated by a plus sign '+'. There is always an End of Line character after each log entry is output. Default format pattern is: `time+logName+eol+loggerLevel+message`.
-from	Merge log entries with timestamp later than start_time. Absence of this option means no start time limit unless -last option is specified. Use time format of "MM/dd/yy HH:mm:ss". For example: "10/05/06 00:00:01"
-to	Merge log entries with timestamp earlier than end_time. Absence of this option means no end time limit. Use time format of "MM/dd/yy HH:mm:ss". For example: "10/05/06 17:21:57"
-last	Merge log entries from last number of hours. This option is ignored if -from or -to is specified.
-loggerName	Merge only log entries generated by the logger with logger_name.
-loggerLevel	If only level is specified, then merge log entries with the specified logger level. If the level+ is specified, then merge log entries with any level equal to or higher than the specified level. The following `loggerLevel` attribute values are listed in order from highest to lowest: SEVERE WARNING INFO CONFIG FINE FINER FINEST
-className	Merge only log entries generated by the class with class_name.
-methodName	Merge only log entries generated by the method with method_name.
-userName	Merge only log entries generated by the user with user_name. Note: The `-userName` flag is different from the `-username` flag described as a sub -flag of the -url flag above; the two flag names are case-sensitive.
-V	Display version information for the utility and exit.

Examples

The following example collects log entries under the server \BTM_INSTALL_DIR\btmstorage directory (and all sub-directories below it), sends them to an output file named BTMLoggingOutputTo10_05_06, the overwrite option is set to true, all entries with a loggerLevel of INFO or higher (WARNING, SEVERE) will be collected, with multiple format options, and a date and time range over two-and-one-half days:
```
logMerger -dir "C:\BTM_INSTALL_DIR\btmstorage" 
          -output BTMloggingOutputTo10_05_06 -overwrite true 
          -loggerLevel INFO+ -format time+loggerName+userName+message+eol 
          -from "10/03/06 00:00:01" -to "10/05/06 12:00:00"
```
The following example collects log entries under the local machine's directories \BTM_INSTALL_DIR\btmstorage\btmui and BTM_INSTALL_DIR\btmstorage\btmtransaction, sends the entries to an output file named BTMuiNtransactionLoggingOutLast24, the overwrite option is set to true, all entries with a loggerLevel of INFO will be collected, with multiple format options, the utility collects all logging entries generated by the action of a user with the name SalesOpsManager that have occurred over the last 24 hours.
```
logMerger -dir "C:\BTM_INSTALL_DIR\btmstorage\btmui" 
          -dir "C:\BTM_INSTALL_DIR\btmstorage\btmtransaction" 
          -output BTMuiNtransactionLoggingOutLast24 -overwrite true 
          -loggerLevel INFO -format time+userName+messgae 
         -userName SalesOpsManager -last 24
```
The following example collects log entries from three URLs:

http://remoteServer1:8080/btmcentral/sphere http://remoteServer1:8080/btmcentral/sphere http://remoteServer1:8080/btmcentral/sphere

The user and password credentials to access these service URLs is the same (otherwise, you must use a configuration file). The log entries are sent to an output file named remoteServiceOutputFrom10_13_06, all entries with a loggerLevel of INFO or higher (WARNING,SEVERE) are collected, with multiple format options, and a date range from one second after midnight on 10/13/06.
```
logMerger -url "http://remoteServer1:8080/btmcentral/sphere" 
          -url "http://remoteServer2:8080/btmcentral/container" 
          -url "http://remoteServer1:8080/btmcentral/agent" 
          -username BTMAdminUser -password BTMAdminUserPwd 
          -output remoteServiceOutputFrom10_13_06 
          -loggerLevel INFO+ -format time+message+eol -from "00:00:01 10/13/06"
```
The following example uses settings from within a user-defined LogMerger configuration file named myLogMergerConfigFile.xml. Use this option when you frequently use logMerger to collect the same type of information. You can add options to the command line to overwrite the options defined in the configuration file.
```
logMerger -config myLogMergerConfigFile.xml
```

logMerger Configuration File

The following text contains the formatting and content for a sample log merger configuration file. Options specified in the file will be overridden by command line options.

If you want to encrypt the passwords for accessing remote service URLs via the configuration file, you can use the encryptPassword command.

The attributes defined in the configuration file, which are described in the following subsections, are enclosed in the following:

<ap:logmerger xmlns:ap="http://namespace.amberpoint.com/amf" debug="false">
.
.
.
</ap:logmerger>

Sources Attribute Example and Discussion

<ap:sources>
   <ap:source dir="C:/Program Files/AmberPoint/SOAManagementSystem/
                                                      server/amberpoint"/>
   <ap:source url="http://remoteServerHost1:7001/apcentral/sphere"
                              username="SMSUser1" password="SMSUserPwd1"/>
   <ap:source url="http://remoteServerHost2:7001/apcontainer/container"
                              username="SMSUser2" password="SMSUserPwd2"/>
   <ap:source url="http://remoteServerHost3:7001/eProxy/agent/agent"
                              username="SMSUser3" password="SMSUserPwd3"/>
   <ap:source url="http://remoteServerHost1:8080/apcentral/sphere"
                            username="ALSMUser1" password="ALSMUserPwd1"/>
  </ap:sources>

You can provide multiple source dir entries. Each source directory must be a separate entry.

dir: Directory that contains the Business Transaction Management logdir directory you want to merge. The logMerger utility searches all subdirectories of the specified directory for logdir directories.

You can provide multiple source URL entries. Each source URL must be a separate entry.

url: URL of running Business Transaction Management service. This utility will communicate with the service on this URL using the user credentials specified by the -username and -password options.

username: username to access the Business Transaction Management service

password: password to access the Business Transaction Management service

Filter Attribute Example and Discussion

<ap:filter
   from="10/02/06 09:00:00"
   to="10/02/06 11:59:00"
   last="24"
   loggerName="com.amberpoint.services.lifecycle.initialize"
   loggerLevel="INFO+"
   className="com.amberpoint.util.soa.services.urservice.UrServiceImpl"
   methodName="createServices"
   userName="BTMdministrator"

The filter attributes are used to query the log history for messages that contain an exact match of all attributes.

For example, filter attributes of last="24" loggerLevel="INFO" will merge INFO messages logged within the last 24 hours.

If no filter options are specified, then all log messages will be included.

from: log entries with a timestamp later than "from" will be included. Absence of this attribute means no start time limit unless "last" attribute is specified.

Use time format of "MM/dd/yy HH:mm:ss". E.g. from="12/25/05 10:34:25"

to: log entries with a timestamp earlier than "to" will be included. Absence of this attribute means no end time limit.

Use time format of "MM/dd/yy HH:mm:ss". E.g. to="12/25/05 10:34:25"

last: last number of hours of log entries will be included. this attribute is ignored if "from" or "to" is specified.

loggerName: only log entries generated by the named logger attribute will be included.

loggerLevel: this attribute accepts values in two formats: level or level+.

If level is specified, only log entries with the specified logger level will be included.

If level+ is specified, log entries with a level equal to or higher than the specified level will be included.

The following loggerLevel attribute values are listed in order from highest to lowest:

SEVERE

WARNING

INFO

CONFIG

FINE

FINER

FINEST

className: only log entries generated by the specified class will be included.

methodName: only log entries generated by the specified method will be included.

userName: only log entries generated by the specified user will be included.

-->

Output File Example and Discussion

<
<ap:output file="c:\temp\testmerger.log" overwrite="true"
                        format="time+logName+loggerName+eol+loggerLevel+message"/>

file: where the merged log file will be saved.

The LogMerger utility will stop processing if the output file already exists, unless the overwrite attribute has a value of "true".

Absence of the file attribute will save the merged log file to a new file named logmerger_<date>_<time>.log.

overwrite: allows the utility to overwrite the file specified by the "file" attribute if it already exists. The default value of overwrite is "false".

format: defines the output format of each log entry in the merged result.

Possible format tokens include all log entry properties (attributes on logEntry node in log file).

Examples of log entry properties with values are below:

<logEntry
      entryId="1127753975442:0"
      time="Mon Sep 26 09:59:35 PDT 2005"
      entryType="1"
      dataSize="102"
      loggerName="com.amberpoint.agent.backplane.servlet.ServletDriver"
      loggerLevel="INFO"
      methodName="findOldStorageDirectory"
      className="com.amberpoint.agent.backplane.servlet.ServletDriver">

There are four additional special tokens:

message: the actual log message
logName: name of the log file that is stored in <logHeader>. The logHeader is used to identify the service that generates the log message.
eol: end of line character to separate text
tab: tab character to separate text

Each format token must be separated by a plus sign.

The LogMerger utility inserts an End of Line character after each log entry that is written to the output file.