fteSetAgentTraceLevel: modify current trace level for an agent

Use the fteSetAgentTraceLevel command to modify the current trace level for an agent dynamically.

Purpose

Use this command to switch agent trace on and off or to change the level of agent trace that is set. When we use the fteSetAgentTraceLevel command, we do not have to shut down and restart an agent to modify the trace level. The trace files produced are located in MQ_DATA_PATH/mqft/logs/coordination_qmgr_name/agents/agent_name/logs/trace%PID%/trace%PID%.txt, where %PID% is the process ID for the agent instance.

Attention:

When using IBM WebSphere MQ Version 7.5 or later on Multiplatforms, only the user that the agent process is running under can run the fteSetAgentTraceLevel command.

The fteSetAgentTraceLevel command can be run by either:

• The same userid that the agent process is running as.
• Members of the group specified by the agent property adminGroup.

For more information, see the adminGroup property in The MFT agent.properties file.

In IBM WebSphere MQ Version 7.5, and later, the fteSetAgentTraceLevel command also writes a trace for the agent process controller. The trace files produced are located in MQ_DATA_PATH/mqft/logs/coordination_qmgr_name/agents/agent_name/logs/pctrace%PID%/pctrace%PID%.txt, where %PID% is the process ID for the agent instance.

We can also use the command to cause the agent process to generate a Javacore. The agent generates a Javacore file in the following directory: MQ_DATA_PATH/mqft/logs/coordination_qmgr_name/agents/agent_name.

Because running trace can affect your performance significantly and can produce a large amount of trace data, run trace with care and only when necessary. Typically, enable trace only when asked to do so by the IBM service representative.

We can set further trace properties, for example trace file size and the number of trace files to keep, in the agent.properties file. These properties are described in Advanced agent properties.

Specify the optional -p parameter for this command only if we want to use a set of configuration options different from your default set. See The MFT agent.properties file for more information.

Syntax

fteSetAgentTraceLevel

Parameters

-traceAgent classes=level

Required. Level to set the agent trace and which classes to apply the trace to. We can specify a colon-separated list of class specifications. This option enables you to set tracing of different classes, and at different levels. For example:

fteSetAgentTraceLevel -traceAgent com.ibm.wmqfte.agent=all:com.ibm.wmqfte.cmdhandler=moderate
 AGENT1

You can still specify a comma-separated list of class specifications that we want the level of trace to apply to. If we do not specify this parameter, the trace level is applied to all agent classes. Use the following format:

classes=level

For example:

com.ibm.wmqfte=all

We can substitute classes with a Managed File Transfer package name to trace a specific package only. However, because this option captures just a subset of the agent's behavior, we are generally not recommended to use package filtering.

If (classes) start with a plus sign (+), the list of trace classes following the plus sign are added to any existing trace classes currently being traced.

The valid trace level options are as follows and are listed in ascending order of trace file size and detail:

off

Switches the agent trace off but continues to write information to the log files. This is the default option.

flow

Captures data for trace points associated with processing flow in the agent.

moderate

Captures a moderate amount of diagnostic information in the trace.

verbose

Captures a verbose amount of diagnostic information in the trace.

all

Sets agent trace to run on all agent classes.To start full tracing for the agent, run the following command:

fteSetAgentTraceLevel -traceAgent =all AGENT_NAME

To stop full tracing for the agent, run the following command:

fteSetAgentTraceLevel -traceAgent =off AGENT_NAME

-disableOnAnyFFDC

Optional. If this parameter is specified, trace is disabled on the agent when it generates a First Failure Data Capture (FFDC) file.

We can specify only one of the -disableOnAnyFFDC and -disableOnFFDC parameters.

-disableOnFFDC FFDC_specification

Optional. If this parameter is specified, trace is disabled on the agent when it generates a First Failure Data Capture (FFDC) file that matches the FFDC_specification. FFDC_specification is a comma-separated list of values. The format of the values can be either:

class_name

The name of the class where the FFDC originated. For example, com.ibm.wmqfte.classA.

class_name:probe_ID

The name of the class and the probe ID of the location in the class that the FFDC originated from. For example, com.ibm.wmqfte.classB:1.

We can specify only one of the -disableOnAnyFFDC and -disableOnFFDC parameters.

-jc

Optional. Requests that the agent generates a Javacore file. The IBM service team may request that you run the command with this parameter to assist with problem diagnosis. This parameter cannot be used with any other parameter.

-p configuration_options

Optional. This parameter determines the set of configuration options that is used to set the agent trace level. Use the name of a non-default coordination queue manager as the input for this parameter. The command then uses the set of properties files associated with this non-default coordination queue manager.

If we do not specify this parameter, the set of configuration options based on the default coordination queue manager is used.

agent_name

Required. The name of the Managed File Transfer Agent that we want to set the trace level for.

-? or -h

Optional. Displays command syntax.

Example

In this example, the trace level is set to all for all classes for AGENT1:

fteSetAgentTraceLevel -traceAgent com.ibm.wmqfte=all AGENT1  

In this example, the trace level is set to all for the classes com.ibm.wmqfte.agent.Agent and com.ibm.wmqfte.cmdhandler for AGENT1:

fteSetAgentTraceLevel -traceAgent com.ibm.wmqfte.agent.Agent,com.ibm.wmqfte.cmdhandler=moderate
AGENT1 

In this example, subclasses are excluded from the trace because the -traceLevel parameter is set to off. All classes starting with com.ibm.outer are traced at verbose level except classes starting with com.ibm.outer.inner:

fteSetAgentTraceLevel -traceAgent com.ibm.outer=verbose AGENT1
fteSetAgentTraceLevel -traceAgent +com.ibm.outer.inner=off AGENT1

Return codes

0

Command completed successfully.

1

Command ended unsuccessfully.

Parent topic: MFT commands