AMT JCL Logging

The AMT JCL Python library uses Python's built-in logging module. The logging module is part of the Python standard library and provides a way to configure different loggers, handlers, and formatters. This means that every module in the JCL library can have its own logger, based on the module's name. This way it is easy to identify where log messages are coming from.

The Python logging module is configured using a configuration file, which describes the default behavior of the logging system. The location of the JSON configuration file can be set using the AMT_JCL_LOG_CONFIG environment variable.

Setting the Environment Variable

The file path pointing to the location of the JCL logging file can be set using the AMT_JCL_LOG_CONFIG environment variable. Follow the instructions below for Windows or Linux.

Windows

Open the Settings of Windows and navigate to System.
Click on Advanced system settings A new dialog appears.
Click on the Environment Variables button.
Under System variables, click on the New button.
Fill out the Variable name and Variable value as follows:
1. Set the Variable name to AMT_JCL_LOG_CONFIG.
2. Set the Variable value to point to the location of the JCL logging file.
Click the OK button.

Linux

Open a terminal.
Open the environment file in a text editor: sudo <text editor> /etc/environment.

Text editor: specify a text editor, such as nano, vim, gedit, and kate.

Enter the super user password to authenticate.
Add the following line at the end of the file: AMT_JCL_LOG_CONFIG="<value>".

The value should point to the location of the JCL logging file.

Save the file.
Open a new terminal and run echo $AMT_JCL_LOG_CONFIG to verify the variable has been set successfully.

Enabling Support For OpenTelemetry

Usage of OpenTelemetry is optional and it is disabled by default. To enable OpenTelemetry, the following settings need to be configured in the jcl-config.json file.

Example:

"otel_collector_host": "localhost",
"otel_collector_port": "4317"

Available Logging Settings

The following settings are available in the jcl-logging.conf file:

Setting

Values

Description

level

DEBUG
INFO
WARNING (default)
ERROR
CRITICAL

Sets the level of logging.

'DEBUG' exposes detailed information to diagnose bugs.
'INFO' exposes general information.
'WARNING' exposes potential issues.
'ERROR' exposes serious issues.
'CRITICAL' exposes severe issues that may prevent the job from running.

class

<class>

Indicates the handler's class

formatter

Indicates the key name of the formatter for this handler. Formats can be customized in the [formatter_<format_name>] section, for example:

[formatter_jcl_log_formatter]       
format=[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s

Log messages do not include batchId and jobId by default. These IDs can be added by changing the above format to the following:

[formatter_jcl_log_formatter]       
format=[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s - extra { batchId = %(batchId)s, jobId = %(jobId)s }

args


This list is not exhaustive and only contains some commonly used handlers and their arguments (args). See the description section for examples and the official Python documentation for more information.

Handler	Arguments
StreamHandler	() info () is the same as none or leaving the value empty. This defaults to sys.stderr
StreamHandler	(sys.stdout,)
FileHandler	('<path to log file>', '<mode>')
RotatingFileHandler	('<path to log file>', <maxBytes>, <backupCount>)
TimedRotatingFileHandler	('<path to log file>', <when>, <interval>)
SMTPHandler	(<mailhost>, <fromaddr>, <to_address>, <subject>)
HTTPHandler	(<host>, <url>, <method>)
QueueHandler	(<queue>)

The list of arguments to the constructor for the handler class. This is evaluated in the context of the logging package's namespace. If a log directory location was specified but does not exist, the directory is automatically created. Example usage of arguments:

[handler_console]
  level=WARNING
  class=StreamHandler
  formatter=jcl_log_formatter
  args=(sys.stdout,)

[handler_file]
  class=amt_jcl.amt.jcl.log.handlers.JclRotatingFileHandler
  formatter=jcl_log_formatter
  args=('C:/AmtJava/JCL/logs/job_summary.log', 'a', 1048576, 10)

[handler_simple]
  format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
  datefmt=%Y-%m-%d %H:%M:%S
  args=

Sample File

jcl_logging.conf

[loggers]
keys=root

[handlers]
keys=console,file

[formatters]
keys=jcl_log_formatter

[logger_root]
level=DEBUG
handlers=console,file

[handler_console]
level=WARNING
class=StreamHandler
formatter=jcl_log_formatter
args=(sys.stdout,)

[handler_file]
class=amt_jcl.amt.jcl.log.handlers.JclRotatingFileHandler
formatter=jcl_log_formatter
args=('./logs/job_summary.log', 'a', 1048576, 10)

[formatter_jcl_log_formatter]
format=[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s