Content Engine trace logging is performed by the Apache log4j 1.2.x package. Trace logging is typically implemented to collect and record information about application failures in test or production environments. When you enable logging, log statements inserted into the FileNet® P8 software cause log entries to be written to an output location. As the application (client) makes requests to the server, the logging mechanism captures information about the request and writes it to some output medium, such as a file or a console. Customer support and development personnel use the information provided by trace logging to diagnose and solve problems.
You can configure the logging environment to capture general information and differing levels of detail, as required to solve the problem. Note that logging is not particularly useful in measuring method durations. The act of logging itself has some performance drag on the system and might skew such measurements. If you need to collect these types of measurements, use other available profiling tools or performance analysis tools that are more suited to the purpose.
In the FileNet P8 software, server-side trace logging is accomplished through the use of the TraceLoggingConfiguration object and the TraceFlag constant class. Each subsystem is represented as a property on the TraceLoggingConfiguration class. When trace logging is configured for a particular subsystem, the trace log settings are applied to all classes in that subsystem. The TraceFlag class contains the available trace log settings that are used to specify the amount and type of trace data to collect. These settings can be ORed together to apply multiple settings to a particular subsystem. While it is possible to implement tracing by modifying the TraceLoggingConfiguration object in your own application, customers are recommended to limit their configuration of server-side trace logging by modifying the settings available in the Enterprise Manager. For more information about these settings, see Concepts: Trace Logging in the Help for Content Engine Administration.
In contrast to server-side logging, the Apache log4j.properties configuration file may be used to configure trace logging from the client-side. This file provides a means for logging behavior, priority levels, and output formats with no need to change or recompile application code. However, use of this file is discouraged on the server, except for the purpose of troubleshooting specific server startup issues, such as when the GCD is not able to load. For more information about using this configuration file, see Working with the Apache log4j.properties Configuration File.
NOTE For more comprehensive information about the log4j package and some of its features that are not described in this section, refer to the Apache web site (http://apache.org) under the Logging Project, and on the Apache logging web site (http://logging.apache.org/log4j/).
Apache log4j is installed and functional when the Content Engine object store service is installed. The components for trace logging are located in the Enterprise Manager tree under Servers > ServerName > Trace Logging. For more information, see Concepts: Trace Logging in the Help for Content Engine Administration.
Trace logging is supported for a variety of FileNet P8 operations which are organized into logical subsystems, such as operations pertaining to the Content Engine Java™ API, the Global Configuration Database, or application authentication. Each supported subsystem is represented by a TraceLoggingConfiguration property, such as APITraceFlags, GCDTraceFlags, SecurityTraceFlags, and so on. Each property has an associated get() and set() method that can be used to manage the value of the property. For example, get_GCDTraceFlags() and set _GCDTraceFlags().
The table below identifies the FileNet P8 subsystems for which trace logging may be enabled. In addition, the abbreviation used to identify a particular subsystem in the output trace log file is also provided.
Property | Abbreviation |
Description |
---|---|---|
APITraceFlags | API |
Logs information relative to Content Engine Java API operations. |
AsynchronousProcessingTraceFlags | ASYN |
Logs information relative to the processing portion of an asynchronous event, including document classification and security propagation. |
CBRTraceFlags | CBR |
Logs information relative to content-based retrieval, including indexing, searching, and so on. |
CFSDaemonTraceFlags | CFSD |
Logs information relative to the Content Federation System filesystem daemon. |
CodeModuleTraceFlags | CMOD |
Logs information relative to code module functionality. |
ContentCacheTraceFlags | CCHE |
Logs information relative to content caching operations, which cache document content in the file system on the local server. |
ContentStorageTraceFlags | CSTG |
Logs information relative to the storage of content. |
DatabaseTraceFlags | DB |
Logs information relative to database operations. |
EJBTraceFlags | EJB |
Logs information relative to the Enterprise Java Beans (EJB) transport layer, which is a component architecture for the development and deployment of object-oriented, distributed, enterprise-level applications. |
EngineTraceFlags | ENG |
Logs information relative to the Content Engine server core. |
ErrorTraceFlags | ERR |
Logs information relative to error handling operations. |
EventsTraceFlags | EVNT |
Logs information relative to general event processing. |
FixedContentProviderTraceFlags | FCPV |
Logs information relative to various fixed content providers. |
GCDTraceFlags | GCD |
Logs information relative to the Global Configuration Database (GCD) and its operations. |
MetadataTraceFlags | MCHE |
Logs information relative to metadata cache operations. |
PublishTraceFlags | PUBL |
Logs information relative to publishing operations. |
SearchTraceFlags | SRCH |
Logs information relative to search and query operations. |
SecurityTraceFlags | SEC |
Logs information relative to client and server components used to authenticate (layered over the authentication provider) and authorize user access to Content Engine objects. |
SSITraceFlags | SSI |
Logs information relative to integration with the Single-document Storage Interface (SSI), which is an interface between the Content Engine and FileNet Image Services. |
WSITraceFlags | WSI |
Logs information relative to the Web Services Interface transport layer to Content Engine. |
The server configures trace logging for a particular subsystem by setting the value of the corresponding TraceLoggingConfiguration property. The value of the property is set using trace logging constants defined in the TraceFlag class. These constants represent the available trace log settings that are used to specify the amount and type of trace data to collect for the subsystem.
The following TraceFlag constants are provided:
Constant | Value |
Description |
---|---|---|
SUMMARY |
2 |
Enables minimal high level logging by providing summary information for all
operations. This setting should not significantly impact system performance. |
MODERATE |
4 |
Enables more detailed high level logging than the |
DETAIL |
8 |
Enables the most detailed logging by providing detailed information for all operations primarily used to aid in debugging (includes all |
TIMER |
1 |
Provides the length of time (in milliseconds) that Content Engine takes to complete an operation, such as uploading a file. This setting should not significantly impact system performance. |
NOTE The EngineRuntimeException class contains instructions in its constructor to log information about occurring exceptions, including the error message and the stack trace, using the Error (ERR
) subsystem and the SUMMARY
trace level. Therefore, when the ERR
subsystem is being traced at the SUMMARY
level, you may encounter EngineRuntimeException trace statements in the output log.
TraceFlag constants can be ORed together to apply multiple trace logging settings to a particular subsystem. For example, to enable DETAIL
level logging and to gather the elapsed time to complete operations, the TraceFlag constants would be defined as follows:
// Enable Timer and Detail tracing for GCD subsystem
Integer traceFlags = new Integer(TraceFlag.TIMER_AS_INT|TraceFlag.DETAIL_AS_INT);
TLC_object.set_GCDTraceFlags(traceFlags);
The TraceFlag constants are enforced in a hierarchical inheritance manner by Enterprise Manager. For example, if you configure a subsystem for DETAIL
level logging, then the MODERATE
and SUMMARY
levels are automatically considered to also be in effect.
The trace logging configuration settings for a particular subsystem apply to all classes contained in that subsystem. This allows trace logging to be fully configured for each subsystem, yet independent of other subsystems.
The server uses the TraceLoggingConfiguration.AppenderNames property to specify the output destination(s) for the trace logging data. The property consists of one or more log4j class names separated by commas. Although multiple appenders may be identified for a single logger, only one file appender class name may be specified. When multiple appenders are specified, it is expected that a console appender is being identified, as well as a file appender:
// Specify a Console Appender and a FileAppender
TLC_object.set_AppenderNames("org.apache.log4j.ConsoleAppender, FileAppender");
If the appender names are specified using package prefixes, the class names are interpreted absolutely; otherwise, the class names are prefixed with "org.apache.log4j" during processing. The appender names are validated when they are persisted, rather than when logging is configured.
The following appender names are supported as output destinations:
Appender Name | Description |
---|---|
ConsoleAppender |
The |
FileAppender |
The |
DailyRollingFileAppender |
The |
RollingFileAppender |
The |
NOTE When no appender name is specified, RollingFileAppender
is used by
default. In this manner, only the
TraceLoggingEnabled property needs to be set and the appropriate
TraceFlag settings configured in order to initiate useful trace logging.
The server uses the TraceLoggingConfiguration.set_OutputLocation property to specify the fully qualified path to use as the output location for trace logs, which is used only when the AppenderNames property value is the FileAppender
class or a subclass. When the OutputLocation property is unspecified or null, the value defaults to the application server instance’s working directory path appended with "/FileNet". The filename for the trace log is always p8_server_trace.log:
// Specify the output location for the trace log
TLC_object.set_OutputLocation("C:/temp/logs/trace/p8_server_trace.log");
NOTE Because log4j creates directories on the fly, the only validation against a non-null value for this property is that the location resides within a valid directory.
The server uses the TraceLoggingConfiguration.set_TraceLoggingEnabled() method to enable or disable logging for all configured subsystems. When the property is set to true
, trace logging is enabled for all configured subsystems, according to the TraceFlag values previously defined for each subsystem:
// Determine if trace logging is currently enabled
if ( TLC_object.TraceLoggingEnabled == Boolean.FALSE )
{
// Enable trace logging
TLC_object.set_TraceLoggingEnabled(Boolean.TRUE);
}
NOTE When tracing is enabled, all error log entries are written to the trace log file.
CAUTION In general, all trace logging components should be disabled. Enabling trace logging creates a performance drain on the system, so should only be used when required by technical support personnel to assist in troubleshooting system problems. For more information, see Performance Considerations.
When Content Engine starts up, if no error logger has been configured for the system (in other words, no log4j configuration), a default error logger "filenet_error
" is configured to gather logging at the INFO
level. The default error logger writes entries to the p8_server_error.log file in the application server instance’s working directory path appended with "/FileNet". Note that this is the same directory to which the trace log is written when the TraceLoggingConfiguration.OutputLocation property has not been set. (By default, on a BEA WebLogic® application server, the error log file is <domain directory>/FileNet/<app server name>/p8_server_error.log.)
NOTE Only the default error logger "filenet_error
" is updated to reference any configured trace appenders. As a result, if the base error logger is not "filenet_error
", then INFO
, WARN
, and ERROR
level log messages are not written to the trace loggers.