Platform Agent and System Tools logging

on-site-related topic

The Platform Agent running OS jobs on hosts has extensive logging capabilities. You may be asked to enable extra logging by customer support or you may want to reduce logging by overriding the default values.

Logging in the Platform Agent boot phase

When the Process Server never becomes Running at all and remains stuck at Connecting you can log the initial connection phase between the Platform Agent (on the OS) and the Process Server (in the central Redwood Server) as follows:

  • UNIX: Add/change the loglevel in file ${InstallDir}/etc/startup/${Instance}/loglevel . The Platform Agent script logs to ${InstallDir}/etc/log/<instance>/<instance>.log. The network-processor logs to the same location until it is configured.
  • Microsoft Windows: Change the settings for the instance using the Scheduler Service Manager; see the Configuring Platform Agents on Windows section for more information.

Logging of the Platform Agent under normal circumstances

If there is a problem with the Platform Agent that needs analysis or if you want to reduce the logging output for the entire lifecycle you need to change the Process Server parameters parameter LogLevel. The value of this parameter is used as the logging level as soon as the central Redwood Server has established a connection with the Platform Agent.

This means that the normal procedure for changing the logging level of a Platform Agent is to set the LogLevel Process Server parameter to a new value and then stop/start the Process Server via the GUI.

The logfiles that are created can be retrieved by clicking the blue "i" button in the right hand top corner of the GUI and then selecting the Get Support Files... option. If this fails then you can find them on the host where the Platform Agent is running. The default value for the location is ${TraceDirectory}${FileSeparator}${ProcessServer}-${ProcessName}-${TimeStamp}-${ProcessId}.log.

Process Server parameters

Loglevel

The log level parameter is defined as:

Copy 
<element> :== [[<process>.]<category>=]<level>
<process> :== { network-processor | job-processor | jtool | jrfc | proxy-processor | runner | jlog.<name> }
<level>   :== { none | fatal | error | warn | info | debug | net | trace }
  • <category> can contain '*' to match any following characters
  • <category> is one of a list of internal categories. To get an up-to-date explanation of all available variations of <category> you can type jtool -l help.
  • jlog.<name>jlog has custom categories that you define with the -n parameter of jlog.

Example:

LogLevel Process Server parameter is set to runner.opsys.env=debug

Logfile

The log-file can contain a filename pattern, stderr.log, or - (for stderr). It may contain any of the following substitution parameters:

  • ${ProcessId} - Process ID of the process
  • ${ProcessType} - Process type (standalone, service, ...)
  • ${ProcessName} - Process name (network-processor, ...)
  • ${InstallDirectory} - install directory.
  • ${TraceDirectory} - ${DataRootDirectory}/trc.
  • ${DataRootDirectory} - Base directory for Platform Agent files.
  • ${ProcessServer} - Name of the Process Server that the Platform Agent is configured for.
  • ${FileSeparator} - Character(s) between directory and file (for example / on UNIX and \ on Windows).
  • ${TimeStamp} - Ordered form of timestamp when the file was created.

Agent Log File Retention

You use the LogFileSize (in megabytes) and LogFileRetention (count) Process Server parameters to specify the number and size of log files, respectively. Note that a new log file is created each time you restart and that the size limitation is only checked at regular intervals; this file can grow slightly larger than the limit.

The defaults are 100 and 10, meaning 10 files of 100 MB each.

If the LogFile parameter contains a format that changes over time the filename is exactly according to the format set by LogFile. If it does not older files are moved over and renamed to -1, -2... -<n>.

Logging in the system tools

The system tools start out at the default loglevel info or the Process Server LogLevel parameter when used within an OS job.

To overrule the logging level either set LogLevel to a more precise value that sets a value for the tool, or set a command line argument:

Copy 
 [-f <file>] [-l <loglevel>]

Argument Description
-f <file> Filename where to log to. The default for tools is stderr.
-l <loglevel> A single string that sets the log level. The default for the log-level is "info". The string is case-insensitive.

If the executable is called without the -f or -l switches the environment variables JCS_LOGFILE and JCS_LOGLEVEL are used. If these are not set then the default values are used.

The tools log to stderr, unless -l <logfile> is used or JCS_LOGFILE is set. The stderr output will end up in stderr.log when the tool is run as part of a scheduled process.

Example

To set a single environment variable that tells the network-processor to be very verbose, the job agent not at all, the jftp agent somewhat and the rest normal, you could use:

Copy 
JCS_LOGLEVEL=info,jftp.*=warn,job-processor.*=error,network-processor.*=debug

Some more valid element examples:

Copy 
trace
*=DEBUG
http.*=info,job.*=debug
network-processor.*=warn
job-processor.*=debug