Content Engine trace logging is supported for the Content Engine Java™ API, on the server side and on the client side. The Content Engine .NET API does not support client-side trace logging. Content Engine .NET API clients must use server-side trace logging.
Content Engine trace logging is performed by the Apache log4j 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 that are 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 that is 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 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 by using 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, you are instead encouraged to use an Administration Console for Content Platform Engine to modify the settings. For more information about these settings, see Creating a trace log.
In contrast to server-side logging, the Apache log4j.properties configuration file can be used to configure trace logging from the Java 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 troubleshooting specific server start 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.
Apache log4j is installed and functional when the Content Engine object store service is installed.
Trace logging is supported for various FileNet P8 operations that are organized into logical subsystems, such as operations that use the Content Engine Java API, the Global Configuration Database, or application authentication. Each supported subsystem is represented by a property, such as APITraceFlags, GCDTraceFlags, and SecurityTraceFlags, on the TraceLoggingConfiguration object. You can use the associated get and set methods on the TraceLoggingConfiguration interface to manage the value of each property. For example, get_GCDTraceFlags and set_GCDTraceFlags.
The following table identifies the FileNet P8 subsystems for which trace logging can be enabled. In addition, the abbreviation that is 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. Note: Logging is supported only for the Content Engine Java API, not the Content Engine .NET API.
|
| AsynchronousProcessingTraceFlags | ASYN | Logs information relative to the processing portion of an asynchronous event, including document classification and security propagation. |
| AuditDispositionTraceFlags | AUDT | Logs information relative to audit disposition. |
| 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. |
| CFSImportAgentTraceFlags | CFSI | Logs information relative to the CFS Import Agent subsystem. |
| CodeModuleTraceFlags | Content Manager OnDemand | 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. |
| HandlerTraceFlags | HDLR | Logs information relative to custom server handler code. |
| MetadataTraceFlags | MCHE | Logs information relative to metadata cache operations. |
| PublishTraceFlags | PUBL | Logs information relative to publishing operations. |
| ReplicationTraceFlags | REPL | Logs information relative to the Replication subsystem. |
| SearchTraceFlags | SRCH | Logs information relative to search and query operations. |
| SecurityTraceFlags | SEC | Logs information relative to client and server components that are used to authenticate (layered over the authentication provider) and authorize user access to Content Engineobjects. |
| ServerCommunicationTraceFlags | COMM | Logs information relative to the server communication subsystem. |
| 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. |
| SweepTraceFlags | SWP | Logs information relative to the Sweep subsystem |
| ThumbnailGenerationTraceFlags | THMG | Logs information relative to the ThumbnailGeneration subsystem |
| 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 trace logging configuration property. The value of the property is set by using trace logging constants that are 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 does not significantly affect system performance. |
| MODERATE | 4 | Enables more detailed high level logging than the SUMMARY option for all operations (includes all SUMMARY level information). This setting will have some impact on system performance. |
| DETAIL | 8 | Enables the most detailed logging by providing detailed information for all operations that are primarily used to aid in debugging (includes all SUMMARY and MODERATE level information). This setting significantly affects system performance, and in some cases, can have a severe impact. |
| TIMER | 1 | Provides the length of time (in milliseconds) that Content Engine takes to complete an operation, such as uploading a file. This setting does not significantly impact system performance. |
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); Hierarchical Inheritance Structure of TraceFlag Constants
The TraceFlag constants are enforced in a hierarchical inheritance manner by IBM® Administration Console for Content Platform Engine. 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, which 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 destinations for the trace logging data. The property consists of one or more log4j class names that are separated by commas. Although multiple appenders can be identified for a single logger, only one file appender class name can 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 by 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 ConsoleAppender sends trace logging data to the default console (such as System.out). |
| FileAppender | The FileAppender sends trace logging data to the location specified in the TraceLoggingConfiguration.OutputLocation property. For more information, see Trace Log Output Locations. |
| DailyRollingFileAppender | The DailyRollingFileAppender is a subclass of FileAppender that backs up (rolls over) the trace logs in the directory that is referenced by the OutputLocation property on a scheduled basis. The DatePattern is yyyy-MM-dd, which initiates the backup operation daily at midnight. |
| RollingFileAppender | The RollingFileAppender is a subclass of FileAppender and
is used by default when no class name is directly specified. RollingFileAppender backs
up the trace logs in the directory that is referenced by the OutputLocation
property when the files exceed the maximum size. The default maximum trace log file size is 100 MB, and the default number of backup files is five. You can override these default values by using the Content Platform Engine JVM parameters MaxRollingFileSize and MaxRollingFileBackups. For example, to set the file size to 200 MB and the number of backup files to 10, specify -DMaxRollingFileSize=200MB -DMaxRollingFileBackups=10 . |
The server uses the TraceLoggingConfiguration.set_OutputLocation method 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 that is appended with /FileNet. The file name 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");
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); } When Content Engine starts up, if no error logger is 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 that is appended with /FileNet. Note that this is the same directory to which the trace log is written when the TraceLoggingConfiguration.OutputLocation property is not set. (By default, on a Oracle WebLogic application server, the error log file is <domain directory>/FileNet/<app server name>/p8_server_error.log.)