fteSetAgentLogLevel (Turn on or turn off logging to file of certain MFT agent operations)

[Long Term Support]Use the fteSetAgentLogLevel command to turn on or turn off logging for the interactions between a protocol bridge agent and file servers, and resource monitor activity. [MQ 9.2.4 Nov 2021]Use the fteSetAgentLogLevel command to turn on or turn off logging for the interactions between a protocol bridge agent and file servers, resource monitor activity, and transfer logs.

Purpose

IBM® MQ Managed File Transfer provides a logging mechanism that can be used to capture:
  • Information about the flows between a protocol bridge agent and file servers
  • Details about the polls performed by resource monitors
  • [MQ 9.2.4 Nov 2021]Progress of transfers
When you use the fteSetAgentLogLevel command to enable logging for a protocol bridge agent, the agent records details of the FTP, SFTP and FTPS commands that are sent to the file server, and the responses that are received. This information is written to a log file called agenteventN.log, where N stands for a number.
  • [UNIX, Linux, Windows, IBM i]On Multiplatforms, the agenteventN.log file is in the MQ_DATA_PATH/mqft/logs/coordination_qmgr_name/agents/agent_name directory.
  • [z/OS]On z/OS®, the agenteventN.log file is in the BFG_DATA/mqft/logs/coordination_qmgr_name/agents/agent_name directory.

The information in the log file can be useful in diagnosing issues that might occur during a file transfer involving the protocol bridge agent.

When you use the fteSetAgentLogLevel command to enable logging for resource monitors, the agent records information about the polls performed by the monitors into a log file called resmoneventN.log, where N stands for a number.
  • [UNIX, Linux, Windows, IBM i]On Multiplatforms, the resmoneventN.log file is in the MQ_DATA_PATH/mqft/logs/coordination_qmgr_name/agents/agent_name directory.
  • [z/OS]On z/OS, the resmoneventN.log file is in the BFG_DATA/mqft/logs/coordination_qmgr_name/agents/agent_name directory.
The information in the log file includes:
  • The time when the monitor started and finished a poll.
  • Details of any managed transfers submitted as a result of a poll.

For more information on resource monitor logging, see Logging MFT resource monitors.

You can turn on, turn off, and set the level of logging that you require, in two ways:
  • Use the fteSetAgentLogLevel command to enable or disable logging while the agent is running. You do not need to restart the agent for the change to the logging level to take effect.
  • Set properties in the agent.properties file to enable or disable logging from startup. The properties that need to be set depend on whether logging is being enabled for a protocol bridge agent, or for resource monitors:
    • For protocol bridge agents, logging is controlled using the agentLog property.
    • To enable or disable resource monitor logging, use the resourceMonitorLog property.
[MQ 9.2.4 Nov 2021] If you use the fteSetAgentLogLevel command to enable transfer logging, the agent records information about transfer progress into a log file called transferlog0.json.
  • [UNIX, Linux, Windows, IBM i]On Multiplatforms, the transferlog0.json file is in the MQ_DATA_PATH/mqft/logs/coordination_qmgr_name/agents/agent_name/logs directory.
  • [z/OS]On z/OS, the transferlog0.json file is in the BFG_DATA/mqft/logs/coordination_qmgr_name/agents/agent_name/logs directory.
For more information, see The agent.properties file.
Attention: When the command is run on the system where a standby instance of a highly available (HA) agent is running, the new log level is applied only to that instance. The log level on the active instance of the agent, and any other standby instances, will not be changed.

Syntax - LogAgent option

Read syntax diagramSkip visual syntax diagram fteSetAgentLogLevel -p configuration_options -logAgent ,,ftpftpssftp=on=off -logfilterhost=valuemetadata=value agent_name

Syntax - log monitor option

Read syntax diagramSkip visual syntax diagram fteSetAgentLogLevel -p configuration_options-logMonitor,,monitor_name=info=moderate=verbose=off agent_name
[MQ 9.2.4 Nov 2021]

Syntax - log transfer option

Read syntax diagramSkip visual syntax diagram fteSetAgentLogLevel -p configuration_options -logTransfer ,=info=moderate=verbose=offagent_name
Note:
[Long Term Support]You must select only one of the logAgent and logMonitor options. If you specify both options, the command fails with the following error message:
BFGCL0756E:Invalid command options. Specify either logAgent or logMonitor option but not both.
[MQ 9.2.4 Nov 2021]You must select only one of the logAgent, logMonitor or logTransfer options. If you specify more than one option, the command fails with the following error message:
BFGCL0756E:Invalid command options. Specify only one of logAgent, logMonitor, or logTransfer options.

Parameters

-logMonitor monitor_name=log_level
Required.
A comma separated list of resource monitors and logging levels, where:
monitor_name
Optional. The name of the resource monitor, or a comma-separated list of resource monitors, that the logging level is to be applied to. If you do not specify a monitor name, or a comma-separated list of resource monitors, the logging level is applied to all resource monitors running within the agent.
Attention: If you have specified non-existent resource monitor names in the command, no error is displayed on the console.
log_level
Required.
The logging level to use. This can be one of the following values:
info
Turn on information level logging. This is the default value and enables high level logging for the resource monitors of the agent..
To enable info level logging for monitor MON1 of agent AGENT1:
fteSetAgentLogLevel -logMonitor MON1=info AGENT1
moderate
Turn on moderate level logging.
To enable moderate level logging for monitors MON1 and MON2 of agent AGENT1:
fteSetAgentLogLevel -logMonitor MON1,MON2=moderate AGENT1
verbose
Turn on verbose level logging.
Enable verbose level logging for all monitors of agent AGENT1:
fteSetAgentLogLevel -logMonitor =verbose AGENT1
off
Turn off logging.
To turn off logging for monitors MON1 and MON2 of agent AGENT1:
fteSetAgentLogLevel -logMonitor MON1,MON2=off AGENT1
To turn off logging for monitor MON1 and enable info level logging for monitor MON2 of agent AGENT1:
fteSetAgentLogLevel -logMonitor MON1=off,MON2=info AGENT1
To turn off logging for all monitors of agent AGENT1:
fteSetAgentLogLevel -logMonitor=off AGENT1
If the same resource monitor name is repeated in a command, then the last occurrence of a component is considered as valid. For example:
fteSetAgentLogLevel -logMonitor MON1=info,MONZ=off,MON1=off AGENT1 turns off logging for resource monitor MON1.
For more information about the different logging levels, and the resource monitor events that are logged at each level, see Logging MFT resource monitors.

[MQ 9.2.4 Nov 2021]You cannot use the logMonitor option with the logAgent and logTransfer options.

-logAgent component=operation
Required.
Protocol bridge agent logging can be enabled or disabled for the FTP, FTPS, and SFTP protocols. Specify one of the three possible server protocols and add an operation value to turn the logging off or on for the protocol bridge agent.
component
Optional.
The valid components are:
ftp
The logging operation is applied to all communication between a protocol bridge agent and file servers that use the FTP protocol.
ftps
The logging operation is applied to the communication between a protocol bridge agent and file servers that use the FTPS protocol.
sftp
The logging operation is applied to the communication between a protocol bridge agent and file servers that use the SFTP protocol.
If a component starts with a plus sign (+), the list of components following the plus sign are added to any existing log component currently being logged.
operation
The valid log level operation options are as follows:
off
Disable all logging for a protocol bridge agent. This option is the default. 
fteSetAgentLogLevel -logAgent =off PBA1
To disable logging for a specified component that the protocol bridge agent is connecting to, use these commands: 
fteSetAgentLogLevel -logAgent ftp=off PBA1
fteSetAgentLogLevel -logAgent ftps=off PBA1
fteSetAgentLogLevel -logAgent sftp=off PBA1
on
To enable logging for all three possible file server components that the protocol bridge agent is connecting to, use this command: 
fteSetAgentLogLevel -logAgent =on PBA1
To enable logging for a specified component that a protocol bridge agent is connecting to, use these commands: 
fteSetAgentLogLevel -logAgent ftp=on PBA1
fteSetAgentLogLevel -logAgent ftps=on PBA1
fteSetAgentLogLevel -logAgent sftp=on PBA1
If any component starts with a plus sign (+), the list of components following the plus sign is added to any existing log component currently being logged.
For further configuration options, see Example 1 and Example 2.
[MQ 9.2.4 Nov 2021]You cannot use the logAgent option with the logTransfer and logMonitor options.
-logFilter filter=value
Optional.
Use the logFilter parameter to limit protocol bridge agent logging based on the specified filter criteria. You must specify a value for either one or more file server hosts, or a property within the user metadata for a managed transfer.
host
Use host to filter by:
  • The host name of the system where the file server is located.
  • A list of comma separated host names or IP addresses.
To log the FTP commands sent to, and the responses received from, the file server ftpprod.ibm.com, use this command: 
fteSetAgentLogLevel -logAgent ftp=on -logFilter host=ftpprod.ibm.com PBA1
To log the SFTP commands sent to, and the responses received from, all file servers that have IP addresses starting with 9.182.*, use this command: 
fteSetAgentLogLevel -logAgent sftp=on -logFilter host=9.182.* PBA1
metadata
Specify any text, as defined by the user during the transfer creation, in a key=value format. For example metadata="BANK=WORLD BANK".
To enable logging for all file servers that connect to the protocol bridge agent PBA1 using the FTP protocol, and filter the output to only include entries for managed transfers that contain the metadata "BANK=WORLD BANK”, use this command: 
fteSetAgentLogLevel -logAgent ftp=on metadata="BANK=WORLD BANK" PBA1
Note: In order to filter by metadata, the value you are filtering by, must be specified under the -md parameter as a part of a file transfer. For more information, see fteCreateTransfer (start a new file transfer).
[MQ 9.2.4 Nov 2021]-logTransfer log_level
Required.
Attention: If the fteSetAgentLogLevel command is run by a user other the one that started the agent, error message BFGNV0066E is output on the console:
Turn on or turn off transfer logs. Possible log levels are:
info
Turn on high level logging information of a transfer.
To enable info level transfer logging of agent AGENTQM:
fteSetAgentLogLevel -p AGENTQM -logTransfer info SRC
This is the default value which means high level transfer logs are written for every transfer, and will use file system space, up to a maximum of 100MB.
moderate
Turn on intermediate level log information of a transfer
verbose
Turn on detailed log information of a transfer.
Enable detailed level logging of agent AGENTQM:
fteSetAgentLogLevel -p AGENTQM -logTransfer verbose SRC
off
Turn off transfer logging.
To turn off transfer logging of agent AGENTQM:
fteSetAgentLogLevel -p AGENTQM -logTransfer off SRC
You cannot use the logTransfer option with the logAgent and logMonitor options.

See Output produced by the LogTransfer function for examples of the logging information produced.

-p configuration_options
Optional.
Determines the set of configuration options that is used to set the agent log level. Use the name of a set of configuration options as the value for the -p parameter.
By convention, this is the name of a coordination queue manager. If you do not specify this parameter, the default set of configuration options is used.
-? or -h
Optional. Displays the command syntax.
agent_name
Required. Name of the protocol bridge agent for which the logging is enabled or disabled.
Attention: If you have specified non-existent resource monitor names in the command, no error is displayed on the console.

Example 1

In this example, multiple components are specified in one command, by using a command delimited group. Logging is enabled for the FTP and SFTP protocol, and disabled for the FTPS protocol, on the protocol bridge agent PBA1.
fteSetAgentLogLevel -logAgent ftp=on,ftps=off,sftp=on PBA1
You can also separate the components with a comma to achieve the same result, for example;
fteSetAgentLogLevel -logAgent ftp,sftp=on,ftps=off PBA1

Example 2

In this example, the same component is repeated in a command. The last instance of a component=operation pair is considered as valid. This example disables logging for the FTP protocol on the protocol bridge agent PBA1. 
fteSetAgentLogLevel -logAgent ftp=on,ftp=off PBA1
The previous example has the same effect as this example: 
fteSetAgentLogLevel -logAgent ftp=off PBA1

Example 3

This example enables the default value of info level logging for monitor MON1 of agent AGENT1:
fteSetAgentLogLevel -logMonitor MON1=info AGENT1

Example 4

This example enables , moderate level logging for monitors MON1 and MON2 of agent AGENT1:
fteSetAgentLogLevel -logMonitor MON1,MON2=moderate AGENT1

Example 5

This example turns off logging for monitor MON1 and enable info level logging for monitor MON2 of agent AGENT1:
fteSetAgentLogLevel -logMonitor MON1=off,MON2=info AGENT1

Return codes

0
Command completed successfully.
1
Command ended unsuccessfully.