Read SATA PHY Error Counters Safely with sg_sat_phy_event

A drive keeps dropping off the bus for no obvious reason, and sg_sat_phy_event reads the SATA PHY error counters that explain why. It goes through a SCSI to ATA Translation (SAT) layer, checks the returned data, and leaves the counters unchanged unless you deliberately reset them. Allow about fifteen minutes, plus time to identify the correct device.

1. Check the installed command

Confirm which executable will run and record its version. These checks do not contact a disk:

$ command -v sg_sat_phy_event
/usr/bin/sg_sat_phy_event
$ sg_sat_phy_event --version
version: 1.13 20180628
$ dpkg-query -W -f='${Package} ${Version}\n' sg3-utils
sg3-utils 1.46-3ubuntu4

Package version and utility version are separate pieces of information. Keep both in an incident record, because a distribution can package a utility with a version string that does not resemble the package revision.

Checkpoint: the command accepts exactly one device argument. Its normal operation sends ATA READ LOG EXT for log page 11h, the SATA PHY event counter page, and it does not scan for a suitable disk or select one for you.

2. Identify the device without guessing

Use the device name already established by your storage inventory. A block device such as /dev/sdX can be used on modern Linux, while a SCSI generic node such as /dev/sgN may be required by a particular transport. Never substitute a partition, a mounted filesystem path or a device chosen only because its letter looks familiar.

$ ls -l /dev/sgN
$ lsblk -o NAME,TYPE,SIZE,MODEL,SERIAL
$ sg_inq /dev/sgN

Replace /dev/sgN with the device you have verified. sg_inq is a read-only identification check; if it cannot open the node, fix the device path or permission first. Do not run the PHY command against a device you cannot identify.

Some SAT layers expose the disk as a block device and some expose a generic SCSI path. The command depends on the path containing a functioning SAT layer; a SATA disk directly behind a transport that does not translate ATA pass-through commands will fail even when the disk itself is healthy.

3. Read and decode the counters

Run the command with no state-changing option:

$ sg_sat_phy_event /dev/sgN
<decoded SATA PHY event counters for the selected device>

The installed utility normally decodes the PHY counter identifiers. The exact names, values and diagnostic wording depend on the drive and SAT layer, so do not build an alert around a sample line copied from another machine. A successful run returns status 0; capture the command line and its output alongside your device inventory details.

$ sg_sat_phy_event /dev/sgN > phy-events.txt
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ sed -n '1,24p' phy-events.txt

Redirecting decoded text to a file is safe for the device, but shell redirection can truncate an existing file before the utility runs. Choose a new filename, or write to a temporary name and move it into place only after a successful run:

$ sg_sat_phy_event /dev/sgN > phy-events.txt.new
$ status=$?
$ if [ "$status" -eq 0 ]; then mv phy-events.txt.new phy-events.txt; else rm -f phy-events.txt.new; fi
$ exit "$status"

Recovery: the final exit preserves the utility status for a script. The rm here removes only the incomplete temporary report, never the device data or the previous report.

4. Select the pass-through length when the transport needs it

The default is a 16-byte ATA PASS-THROUGH CDB. That is the preferred choice when the transport supports it and is the form needed for 48-bit LBA commands. The utility also accepts a 12-byte CDB for transports that cannot carry commands longer than 12 bytes:

$ sg_sat_phy_event --len=12 /dev/sgN
$ sg_sat_phy_event --len=16 /dev/sgN

Try the default first. Use --len=12 only when the controller, enclosure or its documentation requires it; the command's help text confirms the only allowed values are 12 and 16. It is not a general compatibility switch, and it does not make an unrelated non-SAT path work.

For normal diagnosis, leave --extend unset. It sets the ATA PASS-THROUGH EXTEND bit and has no effect with --len=12; it is not needed for the documented PHY log read in the ordinary case.

5. Change the display format only when you need to

The default output is hexadecimal grouped in 16-bit words, matching the ATA preference. Add --hex once for byte-oriented hexadecimal, or add it twice for word-grouped hexadecimal without the usual header:

$ sg_sat_phy_event --hex /dev/sgN
$ sg_sat_phy_event --hex --hex /dev/sgN

Use --ignore for numeric identifiers instead of decoded counter names. This can help compare vendor-specific entries, but it makes a report less readable:

$ sg_sat_phy_event --ignore /dev/sgN

Use --raw only when another program needs the binary response. It writes binary data to standard output and diagnostics to standard error. Do not send it to a terminal:

$ sg_sat_phy_event --raw /dev/sgN > phy-events.bin
$ test -s phy-events.bin && echo 'binary response saved'

The file is a protocol response, not a text report. Keep it with the command, package version and device identity if another engineer will decode it later.

6. Treat reset as a deliberate maintenance action

Warning: --reset requests that the counters be reset after the current values are returned, decoded and displayed. This changes diagnostic state and can remove the baseline needed for later comparison. Do not include it in a monitoring script or a first investigation.

$ sg_sat_phy_event --reset /dev/sgN

Recovery: before using it, save an ordinary read and record why the baseline is being cleared. There is no undo option in this utility. Recovery means keeping the saved pre-reset report and starting a new observation interval; it cannot restore the old counter values inside the drive.

7. Diagnose a failed read

If the command fails, rerun without --reset and increase verbosity with --verbose:

$ sg_sat_phy_event --verbose /dev/sgN
$ printf 'exit status: %s\n' "$?"

Check the device path, permissions and the SAT path before changing options. A permission error may justify sudo sg_sat_phy_event /dev/sgN, but elevated privileges cannot add SAT support to an enclosure or repair a failing link. A transport error, unsupported ATA PASS-THROUGH command or malformed response should be reported with the verbose output and the hardware path.

A zero error count is not proof that the whole storage path is healthy. These counters describe only the SATA PHY log exposed by the device; they do not replace SMART data, filesystem checks, controller logs or a backup. A non-zero counter, on the other hand, is a useful signal to correlate with link resets, cable changes, power events and system logs before replacing hardware.

Done means