fteSetAgentLogLevel: set MFT protocol bridge agent log level

Use the fteSetAgentLogLevel command to enable or disable diagnostic information logging for file transfers between a Managed File Transfer protocol bridge agent and FTP/SFTP/FTPS file servers.


Purpose

Use this command to enable or disable logging for collection of diagnostic information about the transfer of files between a Managed File Transfer protocol bridge agent and FTP/SFTP/FTPS file servers. Managed File Transfer protocol bridge agent logging is more lightweight, separate from, but can be run in parallel with trace.

Commands that are sent by the protocol bridge agent to FTP/SFTP/FTPS file servers, and the responses that are received, are written to a log file for simple diagnosing of problems that might occur during file transfers.

We can enable, disable, and set the level of logging that you require, in two ways:

  • Use the fteSetAgentLogLevel command to enable or disable logging while the protocol bridge agent is running. You do not need to restart the protocol bridge agent for the logging to begin.
  • Use the agent.properties file to enable or disable logging at agent start. If we use this method to enable or disable logging, and the agent is running, you must restart the agent for the logging to begin. For more information, see The agent.properties file.

An interaction between a protocol bridge agent and a file server is treated as an event and each event is written to an agentevent?.log file. The '?' in the log name represents a numeric value. The file that contains 0 (zero) in its name, contains the newest set of captured messages. The log file is stored in MQ_DATA_PATH/mqft/logs/coordination_qmgr_name/agents/agent_name/ folder.

We can set further logging properties, for example, to limit the log file size and the number of log files kept, in the The agent.properties file.


Syntax

fteSetAgentLogLevel

fteSetAgentLogLevel -p configurationOptions -logAgent ,,ftpftpssftp=on=off -logfilterhost=valuemetadata=value -logMonitor ,-monitor name ,=info=moderate=verbose=off agentName


Parameters

    -logAgent component=operation
    Required. Important: You must select only one of logAgent and logMonitor. If you attempt to select both options you receive an error message.

    Name of the protocol bridge agent for which the logging is enabled or disabled. Protocol bridge agent logging can be enabled or disabled for three components: ftp, ftps, and sftp servers. Specify one of the three possible server types and add an operation value to turn the logging off or on, for the protocol bridge agent they are connecting to.

    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.

    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

    For further configuration options, see Example 1 and Example 2.

    -agentName
    Required. Name of the protocol bridge agent for which the logging is enabled or disabled.
    -logFilter filter=value
    Optional. Use to limit logging to the specified filter criteria. You must specify a value for either host or the user specified file transfer metadata.

      host
      Specify one of three values to filter by: host name, a list of comma separated host names or IP addresses. To log commands for, and responses from FTP server ftpprod.ibm.com, use this command: 
      fteSetAgentLogLevel -logAgent ftp=on -logFilter host=ftpprod.ibm.com PBA1
      To log commands and responses from all SFTP servers with 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 any FTP server that connects to the protocol bridge agent PBA1 and filter the file transfers to include them only if they contain the metadata as key and "BANK=WORLD BANK" as value, 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.

    -logMonitor monitor name=log level
    Required. Important: You must select only one of logAgent and logMonitor. If you attempt to select both options you receive an error message. A comma separated list of resource monitors to enable or disable logging, where:

      monitor name
      Optional. Resource monitor name, or list of names, to enable or disable logging. If we do not specify a name, logging is enabled for all resource monitors of the agent.

      log level
      Required. One of:

        info
        Turn on info level logging. This is the default value.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
        To 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

    -p configurationOptions
    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 we do not specify this parameter, the default set of configuration options is used.

    -? or -h
    Optional. Displays the command syntax.

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. Attention: If we 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 FTP and SFTP servers but disabled for FTPS servers that the PBA1 protocol bridge agent is connecting to. 
fteSetAgentLogLevel -logAgent ftp=on,ftps=off,sftp=on PBA1
We 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 FTP servers that the PBA1 protocol bridge agent is connecting to. 
fteSetAgentLogLevel -logAgent ftp=on,ftp=off PBA1
The previous example has the same effect as this example: 
fteSetAgentLogLevel -logAgent ftp=off PBA1


Return codes

    0
    Command completed successfully.

    1
    Command ended unsuccessfully.