Enabling custom logging with custom adapters

To enable custom logging for an adapter

1. Edit the adapter's configDescriptor.xml file. 

2. Add the following lines to the file and save the file.
   Add the lines before the last line in the file </a:ConfigDescriptor>.

   <a:StringInput name="log-file-name">
   	<a:Explanation>Optional - log file name. This file will be stored in AO_HOME/tomcat/logs folder.</a:Explanation>
   <a:StringInput>
    
   <a:StringInput name="log-file-size">
   	<a:Explanation>Optional - log file size.  Valid file size units are KB, MB and GB. For example: 10KB, 10M and 10GB. Default value is 10MB. This field is used only if Log File Name field has a value.</a:Explanation>
   	<a:Value>4M</a:Value>
   <a:StringInput>
    
   <a:StringInput name="log-file-max-backup-index">
   	<a:Explanation>Optional - maximum number of backup log files. Default value is 1. This field is used only if Log File Name field has a value.</a:Explanation>
   	<a:Value>10</a:Value>
   <a:StringInput>
   
   <a:BooleanInput name="log-file-append">
   	<a:Explanation>Optional - append to existing log file or overwrite it. Possible values are true or false. Default value is false. This field is used only if Log File Name field has a value.</a:Explanation>
   	<a:Value>true</a:Value>
   <a:BooleanInput>
   
   <a:StringInput name="log-level">
   	<a:Explanation>Log level. Possible values are debug, info, warn and error.  This field is used only if Log File Name field has a value.</a:Explanation>
   	<a:Value>info</a:Value>
   <a:StringInput>
    

3. Using your preferred IDE, edit the adapter implementation to enable custom logging and tagging. Instructions are different for actor and monitor adapters as follows:

   • Actor adapters: modify the adapter's initialize() method to invoke super.initialize(). The code should look like the following example, with the addition highlighted in red.
     

   • Monitor adapters: set and unset MDC values in the adapter logic by adding several lines. The code should look like the following example, with additions highlighted in red.
     

4. Re-package the adapter into an AROAR file. 

5. Install the AROAR file by uploading the file into BMC Atrium Orchestrator repository or using the BMC Atrium Orchestrator content installer. See Uploading a prepackaged adapter to the repository.

6. Add the adapter to the grid in the Grid Manager. See Adding adapters to a grid.

7. Configure the adapter. See Configuring adapters.

Adapter log files

BMC Atrium Orchestrator uses Apache's Log4J tool to support its logging function. The Log4J tool uses two components: a logger component and an appender component. The logger component uses a "logging-level" parameter and uses one or more appenders. There can be many types of appenders, including SocketAppender (write to a socket), JDBCAppender (write to a database), SYSLOG appender, and RollingFileAppender. By default, BMC Atrium Orchestrator uses a RollingFileAppender to create and manage the grid.log and processes.log files. This is statically defined in the log4j.xml that is available in the application WAR file. The RollingFileAppender writes the log entries to the files. When a log file reaches the size limit specified in the Log File Size parameter, the RollingFileAppender rolls the contents of the file into a back-up file and creates a new file. By default, the RollingFileAppender puts adapter log entries in the grid.log file.

When you enable custom logging, a new RollingFileAppender is created. It uses the adapter configuration parameters log-file-name, log-file-size, log-file-max-backup-index and log-file-append. The adapter will log entries in the grid.log and the new custom log file. Since a logger component is required to enable custom logging, each adapter has the logger component, which includes the default RollingFileAppender for the grid.log file and the custom adapter log file. The adapter's logger component's logging level is set to the value specified in the adapter configuration.

Log Entry Tagging

There can be more than one adapter of the same type activated on the same peer. For example, there might be two command line adapters, named CLI1 and CLI2, activated on a peer named CDP1. To distinguish log entries in the grid.log for these adapters, each adapter's log entry is tagged with the peer name, job ID and the adapter name. The default log4j.xml file includes tags using the following syntax: 

%X{PeerName}%X{RootJobID}%X{AdapterName} 

It will look like the following example:

<appender class="org.apache.log4j.RollingFileAppender" name="RollingFile">
	<param name="File" value="${catalina.home}/logs/grid.log"/>
	<param name="Append" value="true"/>
	<param name="MaxFileSize" value="4096KB"/>
		<param name="MaxBackupIndex" value="9"/>
		<layout class="org.apache.log4j.PatternLayout">
			<param name="ConversionPattern" value="%d{DATE} [Thread=%t] %-5p %-15c{1} %X{PeerName} %X{RootJobID} %X{AdapterName} : %m%n"/>
		</layout>
	</appender>

When the log4j.xml file includes the tag, adapter logs also have tags, which look like the following line:

[PeerName=CDP1] [JobID=3cc42d079ead5446:20811181:14b7a83cb1b:-7f211-1423754313944] [AdapterName=SampleActor]

The next example shows the tags in a log.

12 Feb 2015 09:18:34,056 [Thread=AMP - Activity Processor - Parallel Adapter Invocation Worker - 2] DEBUG SampleActorAdapter [PeerName=CDP1] [JobID=3cc42d079ead5446:20811181:14b7a83cb1b:-7f211-1423754313944] [AdapterName=SampleActor]  Recieved adapter request: <adapter-request><target-adapter>AdapterConfiguration1423260788086-1635404496</target-adapter><peer-location><location>any</location></peer-location><request-action>ADD</request-action><ttl>4611686018427387902</ttl><job-id>3cc42d079ead5446:20811181:14b7a83cb1b:-7f211-1423754313944</job-id><request-data><request-data><arguments><argument>10</argument><argument>20</argument></arguments></request-data></request-data></adapter-request>
12 Feb 2015 09:18:34,065 [Thread=AMP - Activity Processor - Parallel Adapter Invocation Worker - 2] DEBUG SampleActorAdapter [PeerName=CDP1] [JobID=3cc42d079ead5446:20811181:14b7a83cb1b:-7f211-1423754313944] [AdapterName=SampleActor]  Performing addition...
12 Feb 2015 09:18:34,065 [Thread=AMP - Activity Processor - Parallel Adapter Invocation Worker - 2] DEBUG Adder           [PeerName=CDP1] [JobID=3cc42d079ead5446:20811181:14b7a83cb1b:-7f211-1423754313944] [AdapterName=SampleActor]  args: [J@d6efdb5
12 Feb 2015 09:18:34,065 [Thread=AMP - Activity Processor - Parallel Adapter Invocation Worker - 2] DEBUG SampleActorAdapter [PeerName=CDP1] [JobID=3cc42d079ead5446:20811181:14b7a83cb1b:-7f211-1423754313944] [AdapterName=SampleActor]  Returning response: <response-data><result>30</result><metadata><status>success</status></metadata></response-data>