Server logging

The server treats system logging differently from trace logging.

For both the Content Engine and Process Engine, system logging is always enabled and the log messages are written to files whose location and names are determined by the server. For more information, see Viewing Content Platform Engine logs in traditional deployments or Viewing Content Cortex logs in containerized deployments.

The location of the trace log files can be controlled by specifying the trace file location on the Trace Subsystem dialog. The number of log files to keep and the log file rollover size (in MB) can also be specified. The number of log files and rollover size settings are used for both system logs and trace logs for the Content Engine and the Process Engine. By default, the number of log files is 5 and the rollover size is 100MB. For more information, see topic Enabling trace logging.

Content Engine trace logging

Content Engine logging categorizes the messages by the logical subsystem which produces them, for example, by the component that interfaces with a GCD or object store database or that interacts with an LDAP directory. Trace logging is controlled through the Trace Logging Configuration object, which has a set of properties through which the amount of logging produced by each subsystem can be tailored. This can be achieved through the Administration Console for Content Platform Engine or programmatically by using the API.

The following table identifies the Content Engine subsystems for which trace logging can be enabled and the Trace Logging Configuration property by which that is done. 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 within the Content Platform Engine process, for example, by the Administration Console for Content Platform Engine or Process Engine.
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	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.
DirectoryTraceFlags	LDAP	Logs information relative to the Lightweight Directory Access Protocol (LDAP) directory status.
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 Engine objects.
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.

For each of the properties that are described in the previous table, the value is set to a bit-mask defining the types of trace messages that should be logged. If using ACCE to configure tracing these are presented as a set of checkboxes. If using the API, the value should be set by ORing together the integer values associated with members of the TraceFlags class, as described in the following table:

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.

In addition to the subsystem settings, two further properties of Trace Logging Configuration have broad effect. These can also be set through the Administration Console for Content Platform Engine or by using the API:

TraceLoggingEnabled: This property acts as a “master switch” for Content Engine trace logging. When set to true, logging is enabled as determined by the subsystem properties. When set to false, all trace logging is suppressed regardless of the subsystem settings.
OutputLocation: This property specifies the path where the trace log file should be written. If not set, the trace log is written to the same location as the system log. Otherwise, the property value should specify a path which is valid (exists) for all the server instances to which the Trace Logging Configuration applies. To specify the OutputLocation in ACCE using the Trace File Location field, see Enabling trace logging.

Thread-based trace enablement

A mechanism allows finer-grained thread-based control over trace enablement.

To understand the reason behind the mechanism, consider a scenario where you are investigating an issue with a sweep which requires enabling not only Sweep subsystem tracing but also Search and Database.

Previously, enabling Search and Database would enable that tracing for all server threads, resulting in an explosion of log file size, compromised performance, and pollution of the trace entries of interest by non-relevant traces from other threads. Until this improved enablement, the only way to extract the required traces was to identity the threads running sweep activities and manually filter the large trace logs by those thread IDs.

The new mechanism applies that filtering automatically and at source, so that traces by threads that are not running sweep activities, for example, are suppressed. This suppression ensures that log files contain only entries that are produced by sweep threads.

First, each running thread is associated with a trace subsystem. For foreground threads that are serving client requests, that subsystem is EJB. For background threads, it is the subsystem of the background task that is currently executing in that thread, as shown in the table.

Then, to restrict tracing to only certain of those thread subsystems, a JVM argument or configuration parameter com.filenet.engine.trace.ThreadSubsystemsEnabled is used, with the value giving a comma-separated list of the subsystem identifiers for the threads in which tracing should be enabled, for example:

-Dcom.filenet.engine.trace.ThreadSubsystemsEnabled=SWP

In the threads for which tracing is enabled by this mechanism, the normal trace flag settings apply, so in this example you enable detail tracing for Sweep, Search, and Database as usual through the Administration Console for Content Platform Engine.

The subsystem identifiers given in the ThreadSubsystemsEnabled setting are the abbreviations from the table given earlier and are interpreted case-insensitively.

Bypassing the trace logging configuration

In some circumstances a server problem may prevent loading of the trace logging configuration or may prevent access to the Administration Console for Content Platform Engine or the API to enable tracing logging. To obtain diagnostic information to repair such problems it may therefore be necessary to enable tracing without reference to the trace logging configuration. This is accomplished in two parts:

For Content Engine tracing in these circumstances, set the configuration parameter skipTLC to true, for example by adding -DskipTLC=true to the startup command for the application server JVM hosting the Content Platform Engine.
For Process Engine tracing in these circumstances, set the configuration parameter skipPETLC to true, for example by adding -DskipPETLC=true to the startup command for the application server JVM hosting the Content Platform Engine.

Process Engine trace logging

Similar to the Content Engine, the property TraceLoggingEnabled exists for the Workflow subsystem. This property acts as a “master switch” for Process Engine trace logging. When set to true, logging is enabled as determined by the subsystem properties. When set to false, all trace logging is suppressed regardless of the subsystem settings. To enable this property in ACCE, see Enabling trace logging.

The following table identifies the Process Engine subsystems for which trace options can be enabled. In addition, the abbreviation that is used to identify a particular subsystem in the output trace log file is also provided.

Table 1. Trace options
Trace option	Abbreviation	Description
Application space	APP_SPACE	Trace application space changes such as configuration changes or API calls from client applications.
Archiver	ARCHIVER	Trace archiving.
Asynchronous RPC	ASYNC_RPC	Trace asynchronous RPCs. Used for long-running RPCs, such as configuration transfer, peverify, and pelog.
Asynchronous tools	ASYNC_TOOLS	Trace the tools that use asynchronous communication to the workflow system such as pelog.
Case Synchronization	CASE_SYNC	Trace synchronization of case data. Used with IBM® Case Manager.
Case Analyzer publishing	CA_PUBLISHING	Trace the Case Analyzer event publishing process.
Case Analyzer collection	CA_COLLECTION	Trace the event collection process that queries the event logs.
Case Analyzer database	CA_DATABASE	Trace the database query statements that are run by Case Analyzer.
Case Analyzer RPC	CA_RPC	Trace the remote procedure calls from the Administration Console for Content Platform Engine.
Case Analyzer upgrade	CA_UPGRADE	Trace the Case Analyzer upgrade operation.
Case Analyzer OLAP	CA_OLAP	Trace the interaction with the OLAP database that is conducted through the OLAP connector.
Case History Publishing	CH_PUBLISHING	Trace the Case History event publishing process.
Case History Collect	CH_COLLECTION	Trace the event collection process that queries the event logs for Case History.
Case History Database	CH_DATABASE	Trace the database query statements that are run by Case History.
Case History RPC	CH_RPC	Trace the remote procedure calls from the Case History client.
Case History Performance	CH_PERFORMANCE	Trace the Case History event processing performance.
Case History Upgrade	CH_UPGRADE	Trace the Case History upgrade.
Component Manager	CM	Trace Component Manager. Returns detailed logging information about Component Manager.
RDB Objects	RDB	Trace RDB database access, which is related to isolated region tablespaces.
Database access	DBI_MSGS	Trace database access. This option outputs the SQL statements that are used by workflow system, along with the values of the substitution variables. Setting this option automatically sets the database time option.
Database outputs	DBI_OUT	Trace the field values and outputs of database statements, such as SELECT, UPDATE, and so on.
Database time	RDB_TIME	Trace database timings. This prompt appears only if you answer `no` to the database access prompt.
Database transaction	DBI_TRAN	Trace an entire database transaction from beginning to end.
Environment cache	ENV	Trace workflow system interactions with its environment record cache where it keeps track of workflow system user and group membership information.
Event exporter	EVENT_EXPORTER	Trace the core framework for Case Analyzer and Case History, which drives the publishing and collection processes.
Exceptions	EXCEPTION	Trace exceptions occurring within the server.
Expression Parsing	EXPR	Trace expression parsing.
External RPCs	EXTERNAL	Trace external remote procedure calls (RPCs). Traces calls within the Content Platform Engine server.
Farming	FARMING	Trace activities that are related to a farmed system.
Heartbeat	VWSVRTIME	Trace the heartbeat task activities.
Instruction Sheet Interpreter	ISI	Trace Instruction Sheet Interpreter (ISI) process.
J2EE	J2EE	Trace calls that are related to Java Platform, Enterprise Edition.
Log Manager	LOG	Trace log manager process.
Email Notification	NOTIFY	Trace email notifications.
Object Service RPCs	OBJSVC	Trace Object Service usage.
API RPC	RPC	Trace communication RPCs between the API client and workflow server.
API RPC input	RPC_IN_PARAMS	Trace API input parameters to workflow system RPCs.
API RPC output	RPC_OUT_PARAMS	Trace API output parameters to workflow system RPCs.
Rules	RULES	Trace workflow system interactions with the Rules Engine and rules processing.
Security calls	SEC	Trace security calls.
Stored Procedure Calls	STORED_PROC	Trace the execution of database instruction stored procedure calls.
Workflow Termination	WFTERM	Trace calls made to the workflow termination process (vwdone).
Transfer	TRANSFER	Trace transfer processes.
Vwtime	VWTIME	Trace the processing of the timer task.
Web Services	WEBSERVICES	Trace workflow system interactions with applications that use the Web Services protocol.
XML Parser	XMLPARSER	Trace parsing of XML.
Dynamic Task	DYN_TASK	Trace dynamic tasks. (Dynamic tasks are synonymous with IBM Case Manager ad hoc tasks.)

Additionally, in cases such as tracing system startup where configuration via ACCE may not be possible, Process Engine trace logging is configured either by a configuration file in the server deployment directory or interactively through vwtool. See trace logging for more information.