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: User-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"
- --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.
- -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.
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