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

If a Job Server never reaches Running status and remains stuck at Connecting, you can log the initial connection phase between the Platform Agent and the Job 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. For more information, see Configuring Platform Agents on Windows.

Normal Logging

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 can change the LogLevel Job Server Parameter. The value of this Parameter is used as the logging level as soon as the central RunMyJobs server has established a connection with the Platform Agent. Set the LogLevel Job Server parameter to a new value and then stop/start the Job Server via the GUI.

To retrieve log files, click the dropdown list in the upper right corner of the screen (next to the name of the logged-in user) and choose Product Information > Get Support Files. If this fails, 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.

Job Server Parameters

You can add the following Job Server Parameters to a Job Server using its Parameters tab.

LogLevel

The LogLevel 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 Job Server Parameter is set to runner.opsys.env=debug

LogFile

The LogFile Parameter 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 Job 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 cam use the LogFileSize (in megabytes) and LogFileRetention (count) Job 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 Job 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 Job.

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:

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