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 you use the fteSetAgentTraceLevel command, you 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.
When using IBM® MQ on Multiplatforms, only the user that the agent process is running under can run the fteSetAgentTraceLevel command.
- 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.
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.
You 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.
- You must run this command on the system where the agent is running.
- The traces and logging do not persist across an agent restart.
If the agent terminates and is restarted by the Process Controller process, the dynamic traces and logs are not in effect until the agent.properties file has been updated to include the required trace and log properties.
- When the command is run on the system where a standby instance of a highly available (HA) agent is running, the trace level is only applied to that instance. The trace level on the active instance of the agent, and any other standby instances, will not be changed.
You 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 you want to use a set of configuration options different from your default set. See The MFT agent.properties file for more information.
Syntax
Parameters
- -traceAgent classes=level
- Required. Level to set the agent trace and which classes to apply the trace to.
- -disableOnAnyFFDC
- Optional. If this parameter is specified, trace is disabled on the agent when it generates a First Failure Data Capture (FFDC) file.
- -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
.
- -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 except -p.
- -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 you 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 you want to set the trace level for.
- -? or -h
- Optional. Displays command syntax.
Example
In this example, the trace level is set toall
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
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.