path: root/usr/src/man/man1m/fmdump.1m

'\" te
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2012 Joshua M. Clulow <josh@sysmgr.org>
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH FMDUMP 1M "Jan 14, 2020"
.SH NAME
fmdump \- fault management log viewer
.SH SYNOPSIS
.nf
\fBfmdump\fR [\fB-efmvV\fR] [\fB-c\fR \fIclass\fR] [\fB-R\fR \fIdir\fR] [\fB-t\fR \fItime\fR] [\fB-T\fR \fItime\fR]
     [\fB-u\fR \fIuuid\fR] [\fB-n\fR \fIname\fR[.\fIname\fR]*[=\fIvalue\fR]] [\fIfile\fR]
.fi

.SH DESCRIPTION
The \fBfmdump\fR utility can be used to display the contents of any of the log
files associated with the Fault Manager, \fBfmd\fR(1M). The Fault
Manager runs in the background on each system. It receives telemetry
information relating to problems detected by the system software, diagnoses
these problems, and initiates proactive self-healing activities such as
disabling faulty components.
.sp
.LP
The Fault Manager maintains two sets of log files for use by administrators and
service personnel:
.sp
.ne 2
.na
\fBerror log\fR
.ad
.RS 13n
A log which records error telemetry, the symptoms of problems detected by the
system.
.RE

.sp
.ne 2
.na
\fBfault log\fR
.ad
.RS 13n
A log which records fault diagnosis information, the problems believed to
explain these symptoms.
.RE

.sp
.LP
By default, \fBfmdump\fR displays the contents of the fault log, which records
the result of each diagnosis made by the fault manager or one of its component
modules.
.sp
.LP
An example of a default \fBfmdump\fR display follows:
.sp
.in +2
.nf
# fmdump
TIME                 UUID                                 SUNW-MSG-ID
Dec 28 13:01:27.3919 bf36f0ea-9e47-42b5-fc6f-c0d979c4c8f4 FMD-8000-11
Dec 28 13:01:49.3765 3a186292-3402-40ff-b5ae-810601be337d FMD-8000-11
Dec 28 13:02:59.4448 58107381-1985-48a4-b56f-91d8a617ad83 FMD-8000-OW
\&...
.fi
.in -2
.sp

.sp
.LP
Each problem recorded in the fault log is identified by:
.RS +4
.TP
.ie t \(bu
.el o
The time of its diagnosis
.RE
.RS +4
.TP
.ie t \(bu
.el o
A Universal Unique Identifier (UUID) that can be used to uniquely identify this
particular problem across any set of systems
.RE
.RS +4
.TP
.ie t \(bu
.el o
A message identifier that can be used to access a corresponding knowledge
article located on http://illumos.org/msg/
.RE
.sp
.LP
If a problem requires action by a human administrator or service technician or
affects system behavior, the Fault Manager also issues a human-readable message
to \fBsyslogd\fR(1M). This message provides a summary of the problem and a
reference to the knowledge article on http://illumos.org/msg/.
.sp
.LP
You can use the \fB-v\fR and \fB-V\fR options to expand the display from a
single-line summary to increased levels of detail for each event recorded in
the log. The \fB-c\fR, \fB-t\fR, \fB-T\fR, and \fB-u\fR options can be used to
filter the output by selecting only those events that match the specified
\fIclass\fR, range of times, or \fIuuid\fR.
.sp
.LP
If more than one filter option is present on the command-line, the options
combine to display only those events that are selected by the logical \fBAND\fR
of the options. If more than one instance of the same filter option is present
on the command-line, the like options combine to display any events selected by
the logical \fBOR\fR of the options. For example, the command:
.sp
.in +2
.nf
# fmdump -u uuid1 -u uuid2 -t 02Dec03
.fi
.in -2
.sp

.sp
.LP
selects events whose attributes are \fB(uuid1 OR uuid2\fR) \fBAND\fR (time on
or after 02Dec03).
.SH OPTIONS
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR \fIclass\fR\fR
.ad
.sp .6
.RS 4n
Select events that match the specified class. The class argument can use the
glob pattern matching syntax described in \fBsh\fR(1). The class represents a
hierarchical classification string indicating the type of telemetry event.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.sp .6
.RS 4n
Display events from the fault management error log instead of the fault log.
This option is shorthand for specifying the pathname of the error log file.
.sp
The error log file contains Private telemetry information. This information is
recorded to facilitate post-mortem analysis of problems and event replay, and
should not be parsed or relied upon for the development of scripts or other
tools.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.sp .6
.RS 4n
Follow the growth of the log file by waiting for additional data. \fBfmdump\fR
enters an infinite loop where it will sleep for a second, attempt to read and
format new data from the log file, and then go back to sleep. This loop can be
terminated at any time by sending an interrupt (\fBControl-C\fR).
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR
.ad
.sp .6
.RS 4n
Print the localized diagnosis message associated with each entry in the fault
log.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR \fIname\fR[.\fIname\fR]*[=\fIvalue\fR]\fR
.ad
.sp .6
.RS 4n
Select fault log or error log events, depending on the \fB-e\fR option, that
have properties with a matching name (and optionally a matching value). For
string properties the value can be a regular expression match. Regular
expression syntax is described in the EXTENDED REGULAR EXPRESSIONS section of
the \fBregex\fR(5) manual page. Be careful when using the characters:
.sp
.in +2
.nf
$  *  {  ^  |  (  )  \e
.fi
.in -2
.sp

\&...or a regular expression, because these are meaningful to the shell. It is
safest to enclose any of these in single quotes. For numeric properties, the
value can be octal, hex, or decimal.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR \fIdir\fR\fR
.ad
.sp .6
.RS 4n
Use the specified root directory for the log files accessed by \fBfmdump\fR,
instead of the default root (\fB/\fR).
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fItime\fR\fR
.ad
.sp .6
.RS 4n
Select events that occurred at or after the specified time. The time can be
specified using any of the following forms:
.sp
.ne 2
.na
\fB\fB\fImm\fR/\fIdd\fR/\fIyy hh\fR:\fImm\fR:\fIss\fR\fR\fR
.ad
.sp .6
.RS 4n
Month, day, year, hour in 24-hour format, minute, and second. Any amount of
whitespace can separate the date and time. The argument should be quoted so
that the shell interprets the two strings as a single argument.
.RE

.sp
.ne 2
.na
\fB\fB\fImm\fR/\fIdd\fR/\fIyy hh\fR:\fImm\fR\fR\fR
.ad
.sp .6
.RS 4n
Month, day, year, hour in 24-hour format, and minute. Any amount of whitespace
can separate the date and time. The argument should be quoted so that the shell
interprets the two strings as a single argument.
.RE

.sp
.ne 2
.na
\fB\fB\fImm\fR/\fIdd\fR/\fIyy\fR\fR\fR
.ad
.sp .6
.RS 4n
12:00:00AM on the specified month, day, and year.
.RE

.sp
.ne 2
.na
\fB\fB\fIddMonyy hh\fR:\fImm\fR:\fIss\fR\fR\fR
.ad
.sp .6
.RS 4n
Day, month name, year, hour in 24-hour format, minute, and second. Any amount
of whitespace can separate the date and time. The argument should be quoted so
that the shell interprets the two strings as a single argument.
.RE

.sp
.ne 2
.na
\fB\fB\fIddMonyy hh\fR:\fImm\fR\fR\fR
.ad
.sp .6
.RS 4n
Day, month name, year, hour in 24-hour format, and minute. Any amount of
whitespace can separate the date and time. The argument should be quoted so
that the shell interprets the two strings as a single argument.
.RE

.sp
.ne 2
.na
\fB\fB\fIMon\fR \fIdd\fR \fIhh\fR:\fImm\fR:\fIss\fR\fR\fR
.ad
.sp .6
.RS 4n
Month, day, hour in 24-hour format, minute, and second of the current year.
.RE

.sp
.ne 2
.na
\fB\fB\fIyyyy\fR-\fImm\fR-\fIdd\fR [T \fIhh\fR:\fImm\fR[:\fIss\fR]]\fR\fR
.ad
.sp .6
.RS 4n
Year, month, day, and optional hour in 24-hour format, minute, and second. The
second, or hour, minute, and second, can be optionally omitted.
.RE

.sp
.ne 2
.na
\fB\fIddMonyy\fR\fR
.ad
.sp .6
.RS 4n
12:00:00AM on the specified day, month name, and year.
.RE

.sp
.ne 2
.na
\fB\fB\fIhh\fR:\fImm\fR:\fIss\fR\fR\fR
.ad
.sp .6
.RS 4n
Hour in 24-hour format, minute, and second of the current day.
.RE

.sp
.ne 2
.na
\fB\fB\fIhh\fR:\fImm\fR\fR\fR
.ad
.sp .6
.RS 4n
Hour in 24-hour format and minute of the current day.
.RE

.sp
.ne 2
.na
\fB\fIT\fR\fBns\fR | \fIT\fR\fBnsec\fR\fR
.ad
.sp .6
.RS 4n
\fIT\fR nanoseconds ago where T is an integer value specified in base 10.
.RE

.sp
.ne 2
.na
\fB\fB\fIT\fRus |\fIT\fRusec\fR\fR
.ad
.sp .6
.RS 4n
\fIT\fR microseconds ago where T is an integer value specified in base 10.
.RE

.sp
.ne 2
.na
\fB\fIT\fR\fBms\fR | \fIT\fR\fBmsec\fR\fR
.ad
.sp .6
.RS 4n
T milliseconds ago where T is an integer value specified in base 10.
.RE

.sp
.ne 2
.na
\fB\fB\fIT\fRs | \fIT\fRsec\fR\fR
.ad
.sp .6
.RS 4n
T seconds ago where \fIT\fR is an integer value specified in base 10.
.RE

.sp
.ne 2
.na
\fB\fB\fIT\fRm |\fIT\fRmin\fR\fR
.ad
.sp .6
.RS 4n
\fIT\fR minutes ago where \fIT\fR is an integer value specified in base 10.
.RE

.sp
.ne 2
.na
\fB\fB\fIT\fRh |\fIT\fRhour\fR\fR
.ad
.sp .6
.RS 4n
\fIT\fR hours ago where \fIT\fR is an integer value specified in base 10.
.RE

.sp
.ne 2
.na
\fB\fB\fIT\fRd |\fIT\fRday\fR\fR
.ad
.sp .6
.RS 4n
\fIT\fR days ago where \fIT\fR is an integer value specified in base 10.
.RE

You can append a decimal fraction of the form \fB\&.\fR\fIn\fR to any \fB-t\fR
option argument to indicate a fractional number of seconds beyond the specified
time.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fItime\fR\fR
.ad
.sp .6
.RS 4n
Select events that occurred at or before the specified time. \fItime\fR can be
specified using any of the time formats described for the \fB-t\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR \fIuuid\fR\fR
.ad
.sp .6
.RS 4n
Select fault diagnosis events that exactly match the specified \fIuuid\fR. Each
diagnosis is associated with a Universal Unique Identifier (UUID) for
identification purposes. The \fB-u\fR option can be combined with other options
such as \fB-v\fR to show all of the details associated with a particular
diagnosis.
.sp
If the \fB-e\fR option and \fB-u\fR option are both present, the error events
that are cross-referenced by the specified diagnosis are displayed.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Display verbose event detail. The event display is enlarged to show additional
common members of the selected events.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.sp .6
.RS 4n
Display very verbose event detail. The event display is enlarged to show every
member of the name-value pair list associated with each event. In addition, for
fault logs, the event display includes a list of cross-references to the
corresponding errors that were associated with the diagnosis.
.RE

.SH OPERANDS
The following operands are supported:
.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 8n
Specifies an alternate log file to display instead of the system fault log. The
\fBfmdump\fR utility determines the type of the specified log automatically and
produces appropriate output for the selected log.
.RE

.SH EXAMPLES
\fBExample 1 \fRRetrieving Given Class from \fBfmd\fR Log
.sp
.LP
Use any of the following commands to retrieve information about a specified
class from the \fBfmd\fR log. The complete class name is
\fBereport.io.ddi.context\fR.

.sp
.in +2
.nf
# \fBfmdump -Ve -c 'ereport.io.ddi.context'\fR
# \fBfmdump -Ve -c 'ereport.*.context'\fR
# \fBfmdump -Ve -n 'class=ereport.io.ddi.context'\fR
# \fBfmdump -Ve -n 'class=ereport.*.context'\fR
.fi
.in -2
.sp

.sp
.LP
Any of the preceding commands produces the following output:

.sp
.in +2
.nf
Oct 06 2007 11:53:20.975021712 ereport.io.ddi.context
        nvlist version: 0
                class = ereport.io.ddi.context
                ena = 0x1b03a15ecf00001
                detector = (embedded nvlist)
                nvlist version: 0
                        version = 0x0
                        scheme = dev
                        device-path = /
                (end detector)

                __ttl = 0x1
                __tod = 0x470706b0 0x3a1da690
.fi
.in -2
.sp

.LP
\fBExample 2 \fRRetrieving Specific Detector Device Path from \fBfmd\fR Log
.sp
.LP
The following command retrieves a detector device path from the \fBfmd\fR log.

.sp
.in +2
.nf
# \fBfmdump -Ve -n 'detector.device-path=.*/disk@1,0$'\fR
Oct 06 2007 12:04:28.065660760 ereport.io.scsi.disk.rqs
nvlist version: 0
       class = ereport.io.scsi.disk.rqs
       ena = 0x453ff3732400401
       detector = (embedded nvlist)
                nvlist version: 0
                        version = 0x0
                        scheme = dev
                        device-path = /pci@0,0/pci1000,3060@3/disk@1,0
                (end detector)

                __ttl = 0x1
                __tod = 0x4707094c 0x3e9e758
.fi
.in -2
.sp

.SH EXIT STATUS
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Successful completion. All records in the log file were examined successfully.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
A fatal error occurred. This prevented any log file data from being examined,
such as failure to open the specified file.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 5n
Invalid command-line options were specified.
.RE

.sp
.ne 2
.na
\fB\fB3\fR\fR
.ad
.RS 5n
The log file was opened successfully, but one or more log file records were not
displayed, either due to an I/O error or because the records themselves were
malformed. \fBfmdump\fR issues a warning message for each record that could not
be displayed, and then continues on and attempts to display other records.
.RE

.SH FILES
.ne 2
.na
\fB\fB/var/fm/fmd\fR\fR
.ad
.RS 22n
Fault management log directory
.RE

.sp
.ne 2
.na
\fB\fB/var/fm/fmd/errlog\fR\fR
.ad
.RS 22n
Fault management error log
.RE

.sp
.ne 2
.na
\fB\fB/var/fm/fmd/fltlog\fR\fR
.ad
.RS 22n
Fault management fault log
.RE

.SH ATTRIBUTES
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below.
.TE

.sp
.LP
The command-line options are Evolving. The human-readable error log output is
Private. The human-readable fault log output is Evolving.
.SH SEE ALSO
\fBsh\fR(1), \fBfmadm\fR(1M), \fBfmd\fR(1M), \fBfmstat\fR(1M),
\fBsyslogd\fR(1M), \fBlibexacct\fR(3LIB), \fBattributes\fR(5), \fBregex\fR(5)
.sp
.LP
\fI\fR
.sp
.LP
http://illumos.org/msg/
.SH NOTES
Fault logs contain references to records stored in error logs that can be
displayed using \fBfmdump\fR \fB-V\fR to understand the errors that were used
in the diagnosis of a particular fault. These links are preserved if an error
log is renamed as part of log rotation. They can be broken by removing an error
log file, or by moving it to another filesystem directory. \fBfmdump\fR can not
display error information for such broken links. It continues to display any
and all information present in the fault log.