Log Connector

Directory Integrator, Version 7.1.1

Log Connector

The Log Connector is very different from other connectors as it does not have any idea of source/target system. This connector was written exclusively to give you an alternative access to the Tivoli® Directory Integrator logging features; see "Logging and debugging" in the IBM Tivoli Directory Integrator V7.1.1 Installation and Administrator Guide.

Introduction

The Log Connector enables you to use logging utilities in a simpler way, requiring less scripting. The connector can be inserted at any point in the AssemblyLine and enabled/disabled dynamically. Prior to the introduction of this connector you would have to add script code that invoked the AssemblyLine's log object. Using this log object would add log messages to all loggers associated with the AssemblyLine's log object. Similarly, adding a logger to the AssemblyLine (using the AssemblyLine logging configuration screen) would also merge Tivoli Directory Integrator's internal logging to the log output channel causing the log to fill up with possibly unwanted log messages. The Log Connector gives you explicit control of all messages written to the log channel.

This Connector supports AddOnly mode only.

Schema

The schema for the Log Connector is flat with the following predefined attributes:

Attribute	Description
message	The message to be logged.
level	Optional level of the logged message.
exception	Optional `java.lang.Exception`

When exception is present, the level parameter is ignored and LogInterface.error(msg, exception) is called.

When both exception and level is absent then LogInterface.info(msg) is called.

Configuration

The connector configuration for the Log Connector will display the form associated with the selected logger component.

Select Logger

The "Select Logger" function in the configuration screen lets you choose a predefined configuration from the installed log components folder. This configuration is copied into the connector configuration for use with the actual logger instantiation. Available categories and choices are:

Apache Log4J loggers

This is the traditional and most feature-rich category.

Available Apache Log4J loggers are:

ConsoleAppender
CustomAppender
DailyRollingFileAppender
FileAppender
NTEventLog
FileRollerAppender
SystemLogAppender
SyslogAppender

Java Util loggers

Category based configuration
FileHandler (java.util.logging)

JLOG loggers

Category based configuration
FileHandler (com.ibm.log.FileHandler)

An alternative to define loggers is to use the built-in logging feature and a LogConfigItem configuration object. This method bypasses Log4J's lookup in the log4j.properties file; see Creating additional Loggers for more information.

Logger configuration screen

Apache Log4J Loggers

The Apache Log4j logging utility is bundled with Tivoli Directory Integrator. Log4j uses a properties file to configure loggers that are used by Tivoli Directory Integrator. Obtaining a logger via the Log4J API requires a category name, which matches a logger definition in the log4j.properties file. By default, Tivoli Directory Integrator configures Log4J to use solution dir/etc/log4j.properties; see IBM Tivoli Directory Integrator V7.1.1 Installation and Administrator Guide for example configurations.

Layouts

With most loggers you can specify the layout of the output log. You have a choice of the following layouts:

Pattern Layout - Uses a pattern to format the output message (see Patterns below)
Simple Layout - Prints out the log level followed by " - " and the actual log message
HTML Layout - Prints out the log in an HTML table
XML Layout - Prints out log events according to log4j.dtd (http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/xml/doc-files/log4j.dtd)

Patterns

Many loggers use a pattern to format the output string that goes to the log (Pattern.ConversionPattern). The format of this pattern is documented in the respective logging utility's documentation. Below is an incomplete listing of some of the more useful conversion characters that can be used in those patterns.

A pattern is a string that contains special constructs that are substituted by a computed value. Use a percentage sign (%) followed by one of the following characters to insert computed values:

Character	Effect
m	Used to output the log message from the caller.
c	Used to output the category of the logging event. The category conversion specifier can be optionally followed by precision specifier, this is a decimal constant in brackets.
d	Used to output the date of the logging event. The date conversion specifier may be followed by a date format specifier enclosed between braces. For example, %d{HH:mm:ss,SSS} or %d{dd MMM yyyy HH:mm:ss,SSS}. If no date format specifier is given then ISO8601 format is assumed.
F	Used to output the file name where the logging request was issued.
n	The platform specific end-of-line character(s)
p	The priority of the logged event
t	The name of the Thread that generated the log event (for example, AssemblyLine name etc)
%	Outputs a single percent sign

Category based configuration

The category based configuration logger will delegate creating the logger to Log4J. Log4j will use the log4j.properties file to find a match for the category and return a logger as defined in the properties file.

Category: Enter the category to use. The default is empty.

ConsoleAppender

The console appender writes to the standard output/error streams. Parameters are:

Layout

Select a Layout for the Appender. Available values are:

Pattern (the default)
Simple
HTML
XML

Pattern

Specifies the substitution mask that defines log formatting. Only used when Layout is Pattern. You can select from the following pre-defined patterns, or specify your own:

%d{ISO8601} %-5p [%c] - %m%n (the default)
%d{HH:mm:ss} %p [%t] - %m%n
%p [%t] %c %d{HH:mm:ss,SSS} - %m%n

CustomAppender

The custom appender is available when custom appenders have been defined in one or more java properties. Properties that start with custom.appender. are expected to have a value that specify an appender class that implements com.ibm.di.log.CustomAppenderInterface. Parameters are:

Appender Parameters: The parameter's format is not defined and it is up to Appender implementation to parse this text field. By default, this field is empty.

DailyRollingFileAppender

The daily rolling file appender rotates the log file every day. When the output file is rolled it is given a name consisting of the base name plus a date pattern string (for example, filename.yyyy-mm-dd.) Parameters are:

File Path

Specify the path name for the base log file. The default value is empty.

Append to file

Check this box to append to the file when the log is initialized, unchecked to overwrite. The default value is unchecked.

Date Pattern

Specifies the Date pattern that logfile names are suffixed with, and which controls when rollover occurs (i.e. when the filename changes.) You can select from the following pre-defined values or specify your own:

.'yyyy-MM
'.'yyyy-MM-dd
'.'yyyy-MM-dd-HH
'.'yyyy-MM-dd-HH-mm
'.'dd-MM-yyyy

The default value is: '.'yyyy-MM-dd

Layout

Select a Layout for the Appender. Available values are:

Pattern (the default)
Simple
HTML
XML

Pattern

Specifies the substitution mask that defines log formatting. Only used when Layout is Pattern. You can select from the following pre-defined patterns, or specify your own:

%d{ISO8601} %-5p [%c] - %m%n (the default)
%d{HH:mm:ss} %p [%t] - %m%n
%p [%t] %c %d{HH:mm:ss,SSS} - %m%n

Character Encoding

Specifies the output character encoding (for example, UTF-8); the default value is empty.

FileAppender

The file appender writes messages to an output file. Parameters are:

File Path

Specifies the file path for the log file. The default value is empty.

Append to file

Check this box to append to the file when the log is initialized, unchecked to overwrite. The default value is unchecked.

Layout

Select a Layout for the Appender. Available values are:

Pattern (the default)
Simple
HTML
XML

Pattern

Specifies the substitution mask that defines log formatting. Only used when Layout is Pattern. You can select from the following pre-defined patterns, or specify your own:

%d{ISO8601} %-5p [%c] - %m%n (the default)
%d{HH:mm:ss} %p [%t] - %m%n
%p [%t] %c %d{HH:mm:ss,SSS} - %m%n

Character Encoding

Specifies the output character encoding (for example, UTF-8); the default value is empty.

NTEventLog

The NT event logger writes messages to the Windows NT event log. Parameters are:

Source

Usually the title of the application doing the logging. The default value is "itdi".

Layout

Select a Layout for the Appender. Available values are:

Pattern (the default)
Simple
HTML
XML

Pattern

Specifies the substitution mask that defines log formatting. Only used when Layout is Pattern. You can select from the following pre-defined patterns, or specify your own:

%d{ISO8601} %-5p [%c] - %m%n (the default)
%d{HH:mm:ss} %p [%t] - %m%n
%p [%t] %c %d{HH:mm:ss,SSS} - %m%n

FileRollerAppender

The file roller will rotate its logs every day using a sequence number of 1 through Number of backup files. Parameters are:

File Path

This logger will write to <File Path>.1 and increment the extension of existing logfiles up to the specified number of backup files. The default value is empty.

Number of backup files

Specify the number of files to keep before removing the oldest log file. The default value is 5.

Layout

Select a Layout for the Appender. Available values are:

Pattern (the default)
Simple
HTML
XML

Pattern

Specifies the substitution mask that defines log formatting. Only used when Layout is Pattern. You can select from the following pre-defined patterns, or specify your own:

%d{ISO8601} %-5p [%c] - %m%n (the default)
%d{HH:mm:ss} %p [%t] - %m%n
%p [%t] %c %d{HH:mm:ss,SSS} - %m%n

Character Encoding

Specifies the output character encoding (for example, UTF-8); the default value is empty.

SystemLogAppender

The system log appender writes to log files found under system_logs/{ConfigId}/{AL,EH}_X (where X is the name of the AL/EH being run). Parameters are:

Pattern

Specifies the substitution mask that defines log formatting. Only used when Layout is Pattern. You can select from the following pre-defined patterns, or specify your own:

%d{ISO8601} %-5p [%c] - %m%n (the default)
%d{HH:mm:ss} %p [%t] - %m%n
%p [%t] %c %d{HH:mm:ss,SSS} - %m%n

Character Encoding

Specifies the output character encoding (for example, UTF-8); the default value is empty.

SyslogAppender

The syslog appender writes to a syslogd deamon. The syslogd deamon is the standard logging utility on most UNIX systems. Parameters are:

Host name IP Address

Specifies the hostname or IP address of the syslog daemon. The default value is 127.0.0.1

Syslog Facility

Specify the facility name to use for logged messages. Available values are:

kern
user
mail
daemon
auth
syslog
lpr
news
cron
authpriv
ftp
local0
local1
local2
local3
local4
local5
local6
local7

The default value is local7.

Print Facility String

Check if the facility should be printed. By default, this is checked.

Layout

Select a Layout for the Appender. Available values are:

Pattern (the default)
Simple
HTML
XML

Pattern

Specifies the substitution mask that defines log formatting. Only used when Layout is Pattern. You can select from the following pre-defined patterns, or specify your own:

%d{ISO8601} %-5p [%c] - %m%n (the default)
%d{HH:mm:ss} %p [%t] - %m%n
%p [%t] %c %d{HH:mm:ss,SSS} - %m%n

Java Util Loggers

These loggers are part of the standard Java VM. The layouts in java util loggers are termed formatters. Tivoli Directory Integrator includes support for the following formatters:

Simple - Prints a brief summary of the log event in a human readable format. The summary will typically be 1 or 2 lines.
XML - Prints the log file in the format specified by the Java Logging API (see appendix A for a complete description of the DTD).

Category based configuration

The category based configuration logger will delegate creating the logger to Java Util Logging. JUL will use its lib/logging.properties file to find a match for the category and return a logger as defined in the properties file.

Category: Enter the category to use. The default is empty.

FileHandler

The file appender writes messages to an output file. If the "limit" parameter sets an upper limit of the file's size, the log file is rotated when it reaches the maximum size and a new file is created to continue logging. Parameters are:

File Name

Specify the pattern for the log file name (see java.util.logging.FileHandler.)

Append

Check this box to let the logger append to the file when the log is initialized. The default is unchecked, which will cause an existing file to be overwritten.

Formatter

Select the formatter to use. Available values are:

Simple
XML

Limit

Specifies the maximum size of the file before logging is rotated. The default is empty, which signifies infinite size.

Count

Specifies the number of files to keep after a rotation of the log has occurred. The default is empty, which actually means only 1 file is used, with no rotations.

JLOG Loggers

JLOG loggers are bundled with Tivoli Directory Integrator. The layouts in JLOG are termed formatters. Tivoli Directory Integrator includes support for the following formatters:

Simple
CBE101Formatter - Formats log events as Common Base Event v1.0.1 XML entries.
EnhancedFormatter - Formats log events by printing each field in the log event on a separate line, for example:
```
Date:    1999.07.16  11:20:56.842
Class:   com.ibm.log.samples.LogSample
Method:  messageSample
```

Category based configuration

The category based configuration logger will delegate creating the logger to JLOG. JLOG will use its jlog.properties file to find a match for the category and return a logger as defined in the properties file.

Category: Enter the category to use. The default is empty.

FileHandler

The file appender writes messages to an output file. Parameters are:

File Path

Specify the file path for the log file. The default is empty.

Append to file

Check this box to let the logger append to the file when the log is initialized. The default is unchecked, which will cause an existing file to be overwritten.

Formatter

Select the formatter to use for this logger. Available values are:

CBE101
Enhanced
Simple

IBM Tivoli Directory Integrator 7.1.1