Skip to main content
Mitratech Success Center

Appenders

Appenders are definitions of logs. They are classified according to the type of output they generate and whether they are defined for system or audit logging.

Overview

Although many features of appenders and loggers are configured in Designer, there are some features that are controlled by the Admin tab in the main TeamConnect user interface. These Admin features include:

When the TeamConnect application starts running, all logs defined by active appenders start to log generated messages. When you define a new appender or make changes to an existing appender, the changes take effect the next time you restart TeamConnect on the application server. When you delete an appender, the log continues to be generated until you restart TeamConnect.

You can define the following types of appenders which generate logs in corresponding output formats:

  • File Appenders—Define logs that capture messages in a text file as they are generated by the system.
  • SMTP Appenders—Define logs to be sent by email when a log event and when a severity of Error or higher is logged to a buffer.
  • Socket Appenders—Define logs that transmit logger messages to a port on a remote host.

If you need a system log that only logs messages for a certain area of TeamConnect, such as custom blocks, you can associate the appender with the corresponding logger. For more details, see Loggers.

File Appenders

File appenders define logs that capture messages in a text file as they are generated by the system. The log file is stored in the location that was specified when TeamConnect was installed.

Whether you are defining a file appender for system logging or audit logging, the settings that are specific to file appenders are the same.

For general instructions on defining appenders, see one of the following sections:

image

The following table describes the file appender settings.

File Appender Information

Field or Button

Description

Application Logs Folder

Indicates the location of the log files on the application server as a hyperlink. This location is specified when TeamConnect is first installed.

Note: You can click the hyperlink to view the contents of the folder if you are using the same machine where TeamConnect is installed. Otherwise, navigate to the folder on the application server.

File Name

Type the name that you want to use as the name of the log file, including its file extension.

If you are using HTML or XML layout for the log file, use the corresponding extension.

If you want to specify a subdirectory of the logs folder on the application server, you can type the directory location in this field, relative to the logs folder indicated in the Application Logs Folder field. For example, if you want the RulesLog.log file to be stored in a subdirectory called Custom_Rule_Logging, then you would type Custom_Rule_Logging\RulesLog.log as the file name.

Important: To organize your log files, you must manually create the corresponding subdirectories directly on the application server.

Rollover Policy

Determines when you want the system to stop writing to a file, add a timestamp to the file name, and begin writing to a new file. Select one of the following:

  • Rollover on ScheduleAllows the log file to be rolled over daily, weekly, or monthly, as specified by the value of the Backup Schedule setting.

    Important: If you select Rollover on Schedule, previously rolled log files are not automatically replaced by new files. You have to periodically clean up your logs directory to delete old log files.
     
  • Rollover on SizeAllows you specify a file size at which the log file is rolled over and how many backup files to store before replacing them. This is the default rollover policy.

Max. Backup Index

The maximum number of backup files to be stored before backup files are replaced by new files. The oldest file is replaced each time a new file is rolled over. By default, the maximum backup index is 5.

Important: Specifying a larger number, such as 10, may negatively impact performance.

This field is only displayed if Rollover on Size is selected as the rollover policy.

Max. File Size (MB)

The maximum file size, in megabytes, that the log file should reach before rolling over and starting a new file. By default, the maximum file size is 10 MB.

This field is only displayed if Rollover on Size is selected as the rollover policy.

Backup Schedule

Select how often the log file should be rolled over and timestamped and a new file should be created—Daily, Weekly, or Monthly.

This field is only displayed if Rollover on Schedule is selected for the rollover policy.

Immediate Flush

Select this check-box to have each write of a logging event followed by a flush operation. This helps prevent all or part of a log message from being lost should the application exit abruptly. This check-box is selected by default.

If this check-box is not selected, logging throughput is improved by about 15%, but it is more likely that if the application exits abruptly, a logging message that was written might not be completely captured in the log.

Layout

Select whether you want to use a Pattern, HTML, or XML layout for the contents being written to the log file. Pattern Layout is selected by default.

For more details, see File Appender Layouts.

Pattern

This field becomes available when Pattern Layout is selected in the Layout field.

Type the pattern you want to use to display the logging messages in the log file. For more details, see Pattern Layout.

File Appender Layouts

When you define a file appender, you must specify how you want the contents of the file to be organized and formatted. Log4j® provides several types of layouts for file appenders, including Pattern, HTML, and XML layouts. Each of these layouts has the following advantages and disadvantages:

Comparison of File Appender Layouts

Layout

Advantages

Disadvantages

Pattern Layout

Provides easy control over content and organization of log file

  • Limited control over output
  • Difficult to parse for specific information

HTML Layout

  • Requires no configuration or formatting
  • Output is clean, organized and easy to read
  • Fixed format
  • Difficult to parse for specific information

XML Layout

Easiest output to parse for specific information using other software

  • Might require more configuration and design files to be created and implemented
  • More difficult to implement

Pattern Layout

The pattern layout is a flexible layout approach for file appenders. You specify what information you want to include in the log file by providing a string of characters in the Pattern field of a file appender. These instructions are interpreted by the system, so that the resulting log file contains the information you need.

The pattern for a file appender is constructed using conversion specifiers and static characters you might want to include, as demonstrated in the Pattern Example.

Conversion Specifiers

Conversion specifiers indicate what information to write to the log. The following table describes all possible conversion specifiers for pattern layouts.

Log4j® Pattern Layout Conversion Specifiers         

Conversion specifier 

Output in log file

%c

The name of the logger with which the logging event is associated.

If desired, you can specify the desired number of right-most components of the logger name to be printed in the log by following the %c with a precision specifier (a decimal constant within braces). By default, the logger name is printed in full.

For an example of how the Default system log uses a precision specifier with this conversion specifier, see Pattern Example.

%C

The fully qualified class name of the calling object issuing the logging request.

If desired, you can specify the desired number of right-most components of the class name to be printed in the log by following the %C with a precision specifier (a decimal constant within braces).

See Pattern Example for an example of how the Default system log uses a precision specifier with this conversion specifier.

Caution: Generating this information for a log is extremely slow.

%d

The date of the logging event.

If desired, you can follow the %d with a date format specifier within braces. For example, %d{HH:mm:ss,SSS} and %d{dd MMM yyyy HH:mm:ss} are acceptable. By default, ISO8601 format is used.

Log4j® has its own date formatters. These can be specified using one of the following:

  • ABSOLUTE
  • DATE
  • ISO8601

See the Pattern Example for an example of how the Default system log uses a date format specifier with this conversion specifier.

%F

The file name where the logging request was issued.

Caution: Generating this information for the log is extremely slow.

%l

The location information of the calling object which generated the logging event.

Location information includes the file name where the logging request was issued, the line number in the file, the class name, and the method name from which the message was logged.

Caution: Generating this information for the log is extremely slow.

%L

The line number of the file where the logging request was issued.

Caution: Generating this information for the log is extremely slow.

%m

The message associated with the logging event.

%M

The method name where the logging request was issued.

Caution: Generating this information for the log is extremely slow.

%n

The platform-dependent line separator character or characters.

%p

The level of the logging event.

%r

The number of milliseconds elapsed from the start of TeamConnect until the creation of the logging event.

%t

The name of the thread that generated the logging event.

%%

A single percent sign.

Pattern Example       

The following pattern shows the use of several conversion specifiers that write information to the log. This is the pattern used by the Default system log:

%d{ABSOLUTE} [%t] [%p] [%c{1}] %C{1}.%M - %m%n

This can be roughly translated as the following:

date [thread that generated the logging event] [level of the logging event] [logger of the logging event] class.method - message followed by a line return

For example, an entry in the Default system log might be:

11:20:44,005 [jessica] [DEBUG] [sql] TCLog$SQLLogWriter.write - UnitOfWork(2420720)
—end unit of work commit

Notice that the spaces, brackets, hyphen and period in this example are printed in the generated line of text in the log as static text.

HTML Layout

The HTML layout for file appenders writes logging events in a clean-looking table. Each logging event written to the log is added as a row in the table. The columns in this table are described as follows:

File Appender HTML Layout Columns

Time

Thread

Level

Category

Message

Milliseconds elapsed since the TeamConnect was started until

Name of the thread that generated the event

Level of the event

Logger associated with the event

Message associated with the event

Tip: In HTML layout, the time of an event is displayed relative to the start time of the application. To track events logged over long periods of time, specify frequent roll over.

The following table is an example of a log file in HTML layout:

image

XML Layout

The XML layout writes logging events in a fixed format. This layout is implemented without more configuration for TeamConnect. Therefore, it does not generate a completely well-formed XML file. It is designed to be included as an external entity in a separate file to form a correct XML file. This allows you to determine how the logging events should be displayed in the log.

The XML layout can be useful for creating output that can be parsed by other software to create a report of specific information. For example, to create an audit report containing a summary of methods accessed by users, you can more easily parse XML than pattern text or HTML.

The following is an example output of a logging event in XML layout:

<log4j:event logger="syslog.basic.sql" timestamp="1063916251658" level="DEBUG" thread="ExecuteThread: '10' for queue: 'default'">

<log4j:message><![CDATA[ServerSession(4688271)--client acquired

]]></log4j:message>

</log4j:event>

Viewing Logs Generated by File Appenders

The system and audit logs generated by file appenders are stored on the web server in a location that is specified when TeamConnect is installed. If you have access to the web server, you can directly view the logs on the server.

If you do not have access to the web server, you can view the logs directly in TeamConnect using the View Log hyperlink that is provided for each file appender.

Tip: To find out where your logs are stored, see the path displayed in the Application Logs Folder field in a file appender screen.

The log location is specified using the app.logFolder parameter in the Web Application Deployment Descriptor when TeamConnect is installed.

To view a log file

  1. On the Admin menu bar in the System Settings drop-down list, select either System Logging or Audit Logging, depending on the type of log you want to view.
    The Logging screen opens, with the corresponding tab displayed by default.
    image

  2. In the System Appenders (or Audit Appenders) section of the tab, locate the name of the log you want to view and click the corresponding View Log hyperlink.
    The current log file for the log you selected is displayed in a new browser window. The most recent log events are listed at the bottom of the log file.
  3. To view the latest log messages, press F5 or click your browser's Refresh button.

Clearing Logs Generated by File Appenders

If the Rollover Policy field of an active file appender is set to Rollover on schedule, you can manually trigger the removal of the current log entries in a log file and start logging again in an empty file.

To clear a log file

  1. On the Admin menu bar in the System Settings drop-down list, select either System Logging or Audit Logging, depending on the type of log you want to clear.
    The Logging screen opens, with the corresponding tab displayed by default.
  2. In the System Appenders (or Audit Appenders) section of the tab, click the Clear Log hyperlink next to the file appender log you want to clear.
    image
    The current log entries in the log file are removed and logging begins in the empty file.
  3. To view any new log messages, click the corresponding View Log hyperlink.

Rolling Over Logs Generated by File Appenders

If the Rollover Policy field of an active file appender is set to Rollover on size, you can manually trigger the rollover of the current log file and start logging again in new file.

To clear a log file

  1. On the Admin menu bar in the System Settings drop-down list, select either System Logging or Audit Logging, depending on the type of log you want to clear.
    The Logging screen opens, with the corresponding tab displayed by default.
    image
  2. In the System Appenders (or Audit Appenders) section of the tab, click the Rollover hyperlink corresponding to the file appender log you want to roll over. The current log file is rolled over and logging begins in an empty file.
  3. To view any new log messages, click the corresponding View Log hyperlink.

To utilize the XML layout, you need to create the necessary files to use the XML output as content that is pulled in and formatted correctly.

SMTP Appenders

TeamConnect's SMTP appender collects the logger messages in a buffer with a specified size. When the buffer receives a message with a severity of Error or higher, the SMTP appender sends an email message with the log events currently in the buffer to the specified email addresses.

To display the SMTP Appender Information

  1. On the Admin menu in the System Settings drop-down list, select System Logging or Audit Logging, depending on which type of logging you need to define.

  2. In the System Appenders section, click New.
    A new appender screen opens.
  3. Select SMTP Appender from the Appender Type drop-down list.
    The SMTP Appender Information section is displayed.

For information on how to define appenders, see Defining System Appenders or Defining Audit Appenders. Whether you are defining an SMTP appender for system or audit logging, the SMTP appender settings are the same. The following image shows a set of sample settings:

image

In addition to the fields described in the following table, you must configure the Outgoing Mail Server Settings section of the Email page under Admin Settings. For more details, see the Admin Settings, Email Page Field Descriptions table.

SMTP Appender Information

Field

Description

To

The email addresses to which the log should be sent when a triggering log event occurs. Use commas to separate each address.

Buffer Size

The maximum size, in kilobytes, of the buffer that collects logging events. When the maximum buffer size is reached, the oldest events are deleted as new events are added to the buffer.

The default buffer size is 512 kilobytes.

Evaluator Class

To specify a log level other than Error (the default) to trigger email messages, you must upload a class that modifies the triggering level. Enter the name of the class file in this field.

Include Location Information

Select this option to include the location information in the logging events placed in the buffer. For a description of the location information, see the Log4j® Pattern Layout Conversion Specifiers table.

If this option is not selected, the location information is replaced with a question mark (?) in the log. However, it can help reduce the generation time of the logging events.

Layout

Select whether you want to use a Pattern, HTML, or XML layout for the contents being written to the buffer. Pattern Layout is selected by default.

The layout functionality is identical to that of the file appender. For more details, see File Appender Layouts.

Pattern

This field becomes available when Pattern Layout is selected in the Layout field.

Type the pattern you want to use to display the logging messages in the log file. For more details, see Pattern Layout.

Socket Appenders

A socket appender transmits logger messages to a port on a remote host. On the remote host, the messages can then be logged as if generated locally. Using a socket appender allows you to send logs from various systems to a single server where all logs for your organization are monitored or stored.

To use a socket appender, you must define a socket server to receive the log messages. Log4j® includes socket server examples as part of its distribution.

Whether you are defining a socket appender for system logging or audit logging, the settings shown in the following image are the same.

image

The following table describes the fields in the Socket Appender Information section of the Appender screen.

Socket Appender Information

Field

Description

Remote Host

The name or IP address of the server to which the logging events should be sent.

Port

The port number on the remote host to which the logging events should be sent.

Reconnection Delay

The number of milliseconds to wait between each failed attempt to connect to the server using the specified port. The default is 30000 milliseconds (30 seconds).

If you set this field to zero (0), the socket appender attempts to connect to the server only once. If the connection fails, TeamConnect does not try to reconnect.

Include Location Information

Select this option to include the location information in the logging events placed in the buffer.

Location information includes the file name where the logging request was issued, the line number in the file, the class name, and the method name from which the message was logged.

If this option is not selected, then the location information is replaced with a question mark (?) in the log. However, it can help reduce the generation time of the logging events.

For general instructions on defining all types of appenders, see one of the following:

System and Audit Appenders

Default System and Audit Appenders

By default, TeamConnect has several active file appenders--that is, the logs that they generate are written as text files. These files are stored in the location specified for log folders at the time when TeamConnect was installed. There are three default logging appenders:

  • Default (for system logging) — Logs all of the messages that are generated by all of the system loggers and writes them to the system.log file. You can deactivate the Default appender, but it cannot be deleted.
    If you want a log that isolates messages for a specific area of TeamConnect, you must define an appender for the corresponding logger.
  • XML Appender — Logs messages regarding XML requests, according to the level selected for the XML logger, and writes them to the xml.log file.
  • Default (for audit logging) — Logs messages from all active audit loggers and writes them to the audit.log file. You can deactivate the Default appender, but it cannot be deleted.

Note: If Collaborati Spend Management is installed on your system, the Collaborati Appender is installed by default.

Defining System Appenders

Although several default system appenders are provided, you can define new system appenders as needed. When you define a system appender, you are defining a log that you want generated for either one specific system logger or for all of the system loggers.

For example, you might want to define a log that only captures messages regarding custom rules that are defined for your implementation of TeamConnect. You can do this by defining an appender for the Rule logger.

Note: For descriptions of the system loggers, see System Loggers.

To define a system appender

  1. On the Admin menu in the System Settings drop-down list, select System Logging.
  2. If the Audit tab is displayed in the Logging screen, select the System tab.
  3. In the System Appenders section, click New. A new appender screen opens.
    image
  4. In the General Appender Information section, enter the desired information as described in the General Appender Information for System Logging table.
  5. Depending on which type of appender you selected in the Appender Type field, enter the desired information in the specific fields for file, SMTP, or socket appenders as described in the corresponding tables:
  6. Click Save.
  7. Restart the TeamConnect application on the application server.

The general information that must be filled out for all system appenders, regardless of their type, is shown in the General Appender Information for System Logging image.

The following table describes the fields in the General Appender Information section:

General Appender Information for System Logging

Field

Description

Name

The name of the system appender as you want it to be identified in the list of system appenders in the System Logging screen.

Active

Select this check-box to activate the appender. Clear to deactivate the appender. Your change takes effect the next time the TeamConnect application is restarted.

Logger

Select whether you want the system appender to be defined for all loggers or one specific logger. The appender logs all messages associated with the logger you select. If you want the appender to be defined for all loggers, select Root.

For more details about the system loggers, see System Loggers.

Threshold

Select the threshold for the system appender.

Allows you to limit the severity of messages to be captured in a particular log. The threshold is appender-specific, whereas the logger levels themselves are system-wide.

For example, if you want a certain log to capture only Error and Fatal messages, but you want another log to capture all levels of messages, you can define an appender with the threshold set to Error, even though the logger level itself is set to Debug.

Appender Type

Select the type of appender you want to define. For details about each appender type, see the following:

Defining Audit Appenders

Appenders for audit logging differ from system appenders in the following ways:

  • Because you do not have to set the levels of the audit loggers, your audit log appender does not need a threshold for which levels to log.
  • You cannot define an appender for a single audit logger. Messages from all audit loggers that are turned on are logged in an audit appender.

For descriptions of the audit loggers, see Audit Loggers.

To define an audit appender

  1. On the Admin menu in the System Settings drop-down list, select Audit Logging.
  2. If the System tab is displayed in the Logging screen, select the Audit tab.
  3. In the Audit Appenders section, click New. A new appender screen is displayed.
    image
  4. In the General Appender Information section, enter the desired information as described in the General Appender Information for Audit Logging table.
  5. Depending on which type of appender you selected in the Appender Type field, enter the desired information in the specific fields for file, SMTP, or socket appenders as described in the corresponding table:
  6. Click Save.
  7. Restart the TeamConnect application on the application server.

After you restart TeamConnect, messages are written to the log that you defined.

The following table describes the general appender information that must be filled out for all audit appenders, regardless of their type.

General Appender Information for Audit Logging

Field

Description

Name

The name of the audit appender as you want it to be identified in the list of audit appenders in the Audit Logging screen.

Active

Select this check-box to activate the appender. Clear to deactivate the appender.

Your change takes effect the next time the TeamConnect application is restarted.

Appender Type

Select the type of appender you want to define. For details about each appender type, see the following:

Loggers

Loggers categorize the messages that can be captured in a log according to the area of TeamConnect where that message is generated. Loggers are predefined according to area. You cannot create new loggers.

When you need to log messages from a certain area of TeamConnect, you define an appender for the logger that is associated with that area. For example, you can create a log for the portal panes area by defining an appender for the Portal logger. You can define a log for the user interface components by defining an appender for the UI Components logger.

This section includes the following topics:

System Loggers

System loggers categorize messages in the code according to the area of TeamConnect that generates them, so that you can specify which area's messages you want to capture in a particular log. You can define multiple logs that capture messages from different TeamConnect components or all TeamConnect components.

For each log that you have defined, you can specify an overall threshold for what severity of messages you want written to it, so that the logs contain only the most pertinent information. For more details about the threshold for a log (or appender), see the General Appender Information for System Loggers table.

For each available TeamConnect component, you can specify what severity (level) of messages you want written to the logs regarding this component, so that the logs contain only the most pertinent information about the component.

The loggers that are available for system logging are listed on the System tab of the Logging screen, as shown in the System Loggers and Detailed System Loggers images.

All of the system loggers have Root as their parent logger. This hierarchy allows appenders defined for the Root logger to be available to descendant loggers. For example, this means that the Default appender, which has been defined for the Root logger, receives logging statements from all of the loggers in the hierarchy.

Tip: Because the Default appender captures messages from all loggers in the system, you do not need to define another appender for the Root logger.

You can define an appender to be the target of a single logger in the hierarchy. This appender only receives logging statements from the logger for which it is defined. For example, if you need a text file that logs events for the batch display component, you define an appender for the Batch Display Component logger.

The following image shows the System Loggers section of the Logging screen:

image

The following table describes the System Loggers section of the Logging screen:

Logger

Description

Request

Logs HTTP request information including headers, cookies, and parameters.

This logger can automatically be set to the Debug level each time TeamConnect application is restarted. This depends on the value of the syslog.basic.request parameter in the Web Application Deployment Descriptor.

Response

Logs HTTP response header information.

Rule

Logs messages generated by rules that have been defined for your implementation of TeamConnect.

SQL

Logs TopLink-generated SQL statements.

This logger can automatically be set to the Debug level each time TeamConnect application is restarted. This depends on the value of the syslog.basic.sql parameter in the Web Application Deployment Descriptor.

XML

Logs messages regarding XML requests.

The following image shows the Detailed System Loggers section of the Logging screen:

image

The following table describes the Detailed System Loggers section of the Logging screen:

Logger

Description

Authentication

Logs all messages regarding user authentication.

Batch Display Component

Logs all messages regarding the batch display component.

Custom Blocks

Logs all messages regarding custom blocks.

Deletion

Logs all messages regarding record deletion.

IMAP

Logs events related to the TeamConnect IMAP Server and Email Viewer.

Portal

Logs all messages regarding portal panes, including custom content.

Reflection

Logs all messages generated by TeamConnect's reflection factory.

Search

Logs all messages regarding search views and searching for records.

Stores

Logs all messages regarding TeamConnect stores.

Sync Server

Logs all messages regarding cache synchronization.

Tools

Logs all messages regarding both system and custom tools.

UI Components

Logs all messages regarding rendering of TeamConnect screens.

WebDAV

Logs all messages related to WebDAV document management.

Audit Loggers

Audit loggers send their messages to logs defined by audit appenders. Unlike system loggers, audit loggers have the following characteristics:

  • Audit loggers are turned on or off system-wide. You do not have to set levels for audit loggers.
  • When you define an appender for audit logging, all audit loggers that are turned on send their messages to the log. You cannot define separate logs for the various audit loggers.
  • When you define an appender for audit logging, you do not have to specify a threshold. For details about defining audit appenders, see Defining Audit Appenders.

The following image shows the available audit loggers.

image

The following table describes the Audit Loggers section:

Audit Loggers Table

Logger

Description

API Read

Turn on this logger to log read calls to the API.

API Update

Turn on this logger to log update calls to the API.

Page Open

Turn on this logger to log the opening of a page by a user.

Tab Open

Turn on this logger to log the clicking of a tab by a user.

Login/Sign Off

Turn on this logger to log user sign on/off events.

  • Was this article helpful?