mmtracectl command

Sets up and enables GPFS tracing.

Synopsis

mmtracectl {--start | --stop | --off | --set | --status} 
           [--trace={"[io | all | def] [Class Level [Class Level ...]]"}] 
           [--trace-recycle={off | local | global | globalOnShutdown }] 
           [--aix-trace-buffer-size=BufferSize] 
           [--tracedev-buffer-size=BufferSize] 
           [--trace-file-size=FileSize] [--trace-dispatch={yes | no }] 
           [--tracedev-compression-level=Level] 
           [--tracedev-write-mode={blocking | overwrite }] 
           [--tracedev-timeformat={relative | absolute | calendar }]
           [--tracedev-overwrite-buffer-size=Size] 
           [--format | --noformat]
           [-N {Node [,Node...] | NodeFile | NodeClass }] [-Y]

Availability

Available on all IBM Storage Scale editions.

Description

Attention: Use this command only under the direction of the IBM® Support Center.
Use the mmtracectl command for the following functions:
  • Start or stop tracing.
  • Display the tracing status for the specified nodes.
  • Turn tracing on (start or set trace recycle) or off on the next session. This is a persistent setting to automatically start trace each time GPFS starts.
  • Allow for predefined trace levels: io, all, and def, along with user-specified trace levels.
  • Allow for changing the size of trace buffer sizes for AIX® and all others that use the tracedev option.
  • Trace recycle functions, which allow for never cycling traces (off option), cycling traces on all nodes when GPFS ends abnormally (global option), and cycling traces anytime GPFS goes down on all nodes (globalOnShutdown option).
  • For Linux® nodes only, this command allows you to change:
    • The trace writing mode
    • The raw data compression level
Note: Tracing on Windows requires support programs that are provided by Microsoft. For details about this prerequisite, see the section about configuring Windows and installing tracing support programs in the IBM Storage Scale: Concepts, Planning, and Installation Guide.

Results

GPFS tracing can be started, stopped, or related configuration options can be set.

Parameters

--start | --stop | --off | --set | --status
Specifies the actions that the mmtracectl command performs, where:
--start
Starts the trace.
--stop
Stops the trace.
--off
Clears all the setting variables and stops the trace.
--set
Sets the trace variables.
--status
Displays the tracing status of the specified nodes. This parameter is rejected with a usage error message unless all the nodes in the cluster are running IBM Storage Scale 5.0.0 or later.

In the following table, the letter X indicates that the specified type of information is displayed:

Table 1. Tracing status information
Environment Type of information that is displayed
Whether tracing is on or off Kernel mode Daemon mode
Linux X X X
Windows X  
AIX X  
--trace={"[io | all | def] [Class Level [Class Level ...]]"}
Allows for predefined and user-specified trace levels, where:
io
Indicates trace-level settings that are tailored for input and output (I/O).
all
Sets trace levels to their highest setting (9).
def
Indicates that the default trace settings are used.
"Class Level [Class Level ...]"
Specifies a trace class and level.
Note: Start of changeUser-specified trace levels (Class Level) can be appended to a predefined trace level. For example, to set trace levels to the defined group default and the CCR trace to level 9 on all nodes when GPFS starts, issue the following command:
mmtracectl --set --trace="def ccr 9"
End of change
--trace-recycle={off | local | global | globalOnShutdown}
Controls trace recycling during daemon termination. The following values are recognized:
off
Does not recycle traces. This is the default value until mmtracectl --start is run. If no trace-recycle value has been explicitly set when mmtracectl --start is run, see the following description for local. The mmtracectl --off command will remove any explicit value for trace-recycle, thus effectively setting trace-recycle back to the off value.
local
Recycles traces on the local node when mmfsd goes down abnormally. This setting also starts traces automatically anytime that mmstartup is run to start the GPFS daemon, which might include an autoload on a reboot. If there is no trace-recycle value that is explicitly set at the time that mmtracectl --start is run, mmchconfig is run to explicitly set the trace-recycle value to local. The starting of the actual tracing is delayed when the configuration change is being made.
global
Recycles traces on all nodes in the cluster when an abnormal daemon shutdown occurs.
globalOnShutdown
Recycles traces on all nodes in the cluster for normal and abnormal daemon shutdowns.
--aix-trace-buffer-size=BufferSize
Controls the size of the trace buffer in memory for AIX.
--tracedev-buffer-size=BufferSize
Specifies the trace buffer size for Linux trace in blocking mode. If --tracedev-write-mode is set to blocking, this parameter is used. It should be no less than 4K and no more than 64M. The default is 4M.
Note: This option applies only to Linux nodes.
--trace-file-size=FileSize
Controls the size of the trace file. The default is 128M on Linux and 64M on other platforms.
--trace-dispatch={yes | no}
Enables AIX thread dispatching trace hooks.
--tracedev-compression-level=Level
Specifies the trace raw data compression level. Valid values are 0 to 9. A value of zero indicates no compression. A value of 9 provides the highest compression ratio, but at a lower speed. The default is 6.
Note: This option applies only to Linux nodes.
--tracedev-write-mode={blocking | overwrite}
Specifies when to overwrite the old data, where:
blocking
Specifies that if the trace buffer is full, wait until the trace data is written to the local disk and the buffer becomes available again to overwrite the old data.
overwrite
Specifies that if the trace buffer is full, overwrite the old data. This is the default.
Note: This option applies only to Linux nodes.
--tracedev-timeformat={relative | absolute | calendar}
Controls time formatting in the trace records. The following values are accepted:
relative
Displays the trace timestamp in relative format, showing the number of seconds from the beginning timestamp. This is the default.
absolute
Displays the trace timestamp in absolute format, showing the number of seconds since 1/1/1970.
calendar
Displays the trace timestamp in local calendar format, showing day of the week, month, day, hours, minutes, seconds, and year.
--tracedev-overwrite-buffer-size=Size
Specifies the trace buffer size for Linux trace in overwrite mode. If --tracedev-write-mode is set to overwrite, this parameter is used. It should be no less than 16M. The default is 64M.
Note: This option applies only to Linux nodes.
--format | --noformat
Enables or disables formatting.
-N {Node[,Node...] | NodeFile | NodeClass}
Specifies the nodes that participate in the tracing of the file system. This option supports all defined node classes (with the exception of mount). The default value is all.

For general information on how to specify node names, see Specifying nodes as input to GPFS commands.

Start of change
-Y
Displays the command output in a parseable format with a colon (:) as a field delimiter. Each column is described by a header.
Note: Fields that have a colon (:) are encoded to prevent confusion. For the set of characters that might be encoded, see the command documentation of mmclidecode. Use the mmclidecode command to decode the field.
End of change

Exit status

0
Successful completion.
nonzero
A failure has occurred.

Security

You must have root authority to run the mmtracectl command.

The node on which the command is issued must be able to execute remote shell commands on any other node in the cluster without the use of a password and without producing any extraneous messages. For more information, see Requirements for administering a GPFS file system.

Examples

To set trace levels to the defined group def and start the traces on all nodes when GPFS starts, issue the following command:
mmtracectl --set --trace=def --trace-recycle=global
The system displays the following output:
mmchconfig: Command successfully completed
mmchconfig: Propagating the cluster configuration data to all
affected nodes.  This is an asynchronous process.
To confirm the change, issue the following command:
mmlsconfig trace,traceRecycle
The system displays output like the following example:
trace all 4 tm 2 thread 1 mutex 1 vnode 2 ksvfs 3 klockl 2 io 3 pgalloc 1 mb 1 lock 2 fsck 3
traceRecycle global
To manually start traces on all nodes, issue the following command:
mmtracectl --start

See also

See the mmtrace shell script.

Location

/usr/lpp/mmfs/bin