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, see logMerger Configuration File.
-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

  1. 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"

  2. 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

  3. 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"

  4. 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.