From ccebcd49ded64459c0d80774e085a93bfe290597 Mon Sep 17 00:00:00 2001 From: Andrea Mazzoleni Date: Fri, 12 Dec 2025 12:01:12 +0100 Subject: [PATCH] Auto update --- manual.html | 2601 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2601 insertions(+) diff --git a/manual.html b/manual.html index ce915c6d..08be7b65 100644 --- a/manual.html +++ b/manual.html @@ -1962,6 +1962,2607 @@ redirect the console output to a file, the resulting file is always in UTF-8 format. +

+Log manual for SnapRAID. +

+ +

1 +Description +

+This document describes the structured log tags output by SnapRAID, +which are designed to be used by tools monitoring the SnapRAID +processing state. The tags provide information in an easy-to-parse +format, ideal for automation and integration. +

+To capture these structured log tags, you must use the `--log` option +with SnapRAID. +

+You can direct the output to a specific file, or force the output to +the standard output or standard error using the special arguments +`>&1` or `>&2`. Note that these arguments often need to be quoted on +the command line to prevent the shell from interpreting them. +

+Example: +

+
+
+snapraid status --log ">&2"
+
+
+

+The output tags strictly adhere to the following format: +

+

+NAME:VALUE:VALUE:VALUE...<EOL>
+
+ + + + +
+NAME +
+This is the primary tag identifier, always a lowercase string +without spaces (e.g., `summary`, `block`, `info_time`). +
+VALUE +
+Following the `NAME`, these can be additional sub-identifiers, +descriptive names (like a disk name), or numeric/string data +values. They are separated by a colon `:`. +
+<EOL> +
+Each tag is terminated by an end-of-line character. +
+

+This document provides a summary of the tags generated by SnapRAID. +For the most detailed and up-to-date information regarding the meaning +and context of the values, it is recommended to check the source +code's `log_tag()` statements. +

+When a path is output, it is always escaped using a backslash (\) as +the escape character. +

+The following characters are escaped into sequences: + + + + + +
+The colon + +is escaped to \d. +
+The newline + +is escaped to \n. +
+The carriage return + +is escaped to \r. +
+The backslash + +is escaped to \\. +
+

+Some tags are output only when the `--gui` option is used. They provide +extra verbose state and runtime progress only useful for a GUI +interface. +

2 +Configuration Tags +

+These tags report the memory usage and global configuration after +scanning the disk and reading the list of files. + + +
+conf:file:<path> +
+Configuration file loaded (escaped). +
+ + +
+conf:missing: +
+Operating without a configuration file. +
+ + +
+blocksize:<bytes> +
+The configured block size in bytes (uint). +
+ + +
+data:<disk_name>:<dir> +
+The data disks as defined in the configuration file. +
+ + + +
+<disk_name> + +The assigned name of the disk. +
+<dir> + +The directory entry point of the disk. +
+ + +
+mode:<raidname> +
+The RAID mode used. One of `par1`, `par2`, `par3`, `par4`, +`par5`, `par6` or `parz`. The number indicates the maximum +number of simultaneous disk failures the array can withstand. +
+ + +
+<parity_level>:<split_index>:<path> +
+The parity files as defined in the configuration file. +
+ + + + +
+<parity_level> + +One of `parity`, `2-parity`, ..., `6-parity`. +This corresponds to the level of redundancy. +
+<split_index> + +The split index (uint). If no +multiple split parity is configured, there is only the +index 0. A split parity configuration distributes parity +blocks across multiple files. +
+<path> + +The path (escaped). +
+ + +
+pool:<dir> +
+The configured dir to the pool mount point (escaped). +This is the optional mount point for the 'pool' feature. +
+ + +
+share:<dir> +
+The configured dir to the pool mount point (escaped). +This is the optional mount point for the 'share' feature. +
+ + +
+autosave:<bytes> +
+If the autosave feature is enabled, and after how many bytes +(uint64). This specifies the interval for content file saving. +
+ + +
+filter:<pattern> +
+All the active filters with their patterns. These patterns +exclude specific files or directories from the SnapRAID array. +
+ + +
+filter:nohidden: +
+If the no-hidden filter is enabled, meaning hidden files/directories +(starting with '.') are excluded from the array. +
+ + +
+content:<path> +
+The absolute path to a content file being used (escaped). +Content files store the metadata (like file hashes and timestamps) +for the array. +
+ + +
+content:<parity_level>:<split_index>:<path>:<uuid>:<size> +
+The parity files as stored in the content file. +
+ + + + + + +
+<parity_level> + +One of `parity`, `2-parity`, ..., `6-parity`. +
+<split_index> + +The split index (uint). If no +multiple split parity is configured, there is only the +index 0. +
+<path> + +The path (escaped). +
+<uuid> + +The UUID of the partition containing the path. +
+<size> + +The size of the parity file. Size is -1 if not yet +fixed, meaning it can grow. This happens for the +latest split. +
+

3 +Diagnostics Tags +

+ + +
+version:<version> +
+The version of SnapRAID run. +
+ + +
+unixtime:<time> +
+The current time in the unix format (uint64), representing +seconds since the epoch. +
+ + +
+time:<YYYY-MM-DD HH:MM:SS> +
+The current time in human format. +
+ + +
+command:<command> +
+The command run. One of `sync`, `scrub`, `check`, `fix`, `status`, ... +
+ + +
+argv:<number>:<argument> +
+All the arguments of the executable command. The 0 one is the +executable run. +
+ + +
+memory:used:<bytes> +
+The total memory currently used by the application in bytes (uint64). +
+ + +
+memory:block:<bytes> +
+Size of the internal `snapraid_block` structure in bytes (uint64). +
+ + +
+memory:extent:<bytes> +
+Size of the internal `snapraid_extent` structure in bytes (uint64). +
+ + +
+memory:file:<bytes> +
+Size of the internal `snapraid_file` structure in bytes (uint64). +
+ + +
+memory:link:<bytes> +
+Size of the internal `snapraid_link` structure in bytes (uint64). +
+ + +
+memory:dir:<bytes> +
+Size of the internal `snapraid_dir` structure in bytes (uint64). +
+

4 +Scan Tags +

+These tags report detected differences between the filesystem and the +content file. They are output for every discovered change, and +`scan:equal` is only output when the `--gui` option is used. + + +
+scan:equal:<disk_name>:<path> +
+A file, link, or directory is equal (unchanged) (GUI only). +No action is required for this item. +
+ + + +
+<disk_name> + +Name of the data disk. +
+<path> + +Path to the file/link/dir relative to the disk mount +(escaped). +
+ + +
+scan:add:<disk_name>:<path> +
+A new file, link, or directory was found that is not in the +content file. This item will be added to the array in a `sync`. +
+ + +
+scan:remove:<disk_name>:<path> +
+A file, link, or directory has been removed from the filesystem +since the last sync. This item will be removed from the +content file in a `sync`. +
+ + +
+scan:update:<disk_name>:<path> +
+A file or link has been updated (size, timestamp, or link target changed). +This item will have its content data blocks re-hashed in a `sync`. +
+ + +
+scan:move:<disk_name>:<old_path>:<new_path> +
+A file was moved on the same disk. This is an efficient operation +that only updates the path metadata without re-hashing blocks. +
+ + + +
+<old_path> + +The old path to the file (escaped). +
+<new_path> + +The new path to the file (escaped). +
+ + +
+scan:copy:<disk_name>:<path>:<source_disk>:<source_path> +
+A new file was found to be a copy of a file from another disk. +This is detected by matching file size and timestamp, and is an +efficient operation that avoids re-hashing all blocks. +
+ + + +
+<source_disk> + +The original file's disk. +
+<source_path> + +The original file's location (escaped). +
+ + +
+scan:restore:<disk_name>:<path> +
+A file's inode has changed but not its date-time and size, +which suggests the file may be restored from backup. +The file won't be re-hashed in `sync` as its precomputed hash +is assumed to be correct. +
+

+These tags provide a final count of all detected changes. + + +
+summary:equal:<count> +
+Total number of equal (unchanged) files/links/firs found (uint). +
+ + +
+summary:added:<count> +
+Total number of new files/links/dirs found (uint). +
+ + +
+summary:removed:<count> +
+Total number of removed files/links/dirs found (uint). +
+ + +
+summary:updated:<count> +
+Total number of updated files/links found (uint). +
+ + +
+summary:moved:<count> +
+Total number of moved files found (uint). +
+ + +
+summary:copied:<count> +
+Total number of copied files found (uint). +
+ + +
+summary:restored:<count> +
+Total number of restored files found (uint). +
+ + +
+summary:exit:equal +
+A zero-argument tag indicating that no differences were found. +The array is already synchronized. +
+ + +
+summary:exit:diff +
+A zero-argument tag indicating that differences were found. +The array needs a `sync` operation. +
+

5 +General Progress and Execution Tags +

+These tags are used to report the runtime processing of the commands. +Only produced when `--gui` option is used. + + +
+run:begin:<blockstart>:<blockend>:<countmax> +
+A tag indicating the start of the command execution. +
+ + + + +
+<blockstart> + +Starting block index (uint). +
+<blockend> + +Ending block index + 1 (uint). +
+<countmax> + +Number of blocks to process. It may be less +than <blockend> - <blockstart> + 1 if some blocks +are going to be skipped (uint). +
+ + +
+run:end +
+A zero-argument tag indicating the end of the command execution. +
+ + +
+run:pos:<blockpos>:<countpos>:<countsize>:<perc>:<eta>:<size_speed>:<cpu>:<elapsed> +
+Detailed progress information during command execution. +
+ + + + + + + + + +
+<blockpos> + +Current block index position (uint). +
+<countpos> + +Current item count position (uint). +
+<countsize> + +Current size processed (uint64). +
+<perc> + +Percentage complete (uint). +
+<eta> + +Estimated time of arrival in minutes (uint). +
+<size_speed> + +Data processing speed in MiB/s (uint). +
+<cpu> + +CPU usage percentage (uint). +
+<elapsed> + +Elapsed time in seconds (uint64). +
+ + +
+sigint:<blockpos>:<msg> +
+A user interruption (e.g., Ctrl+C) was signaled. The process +is gracefully aborting. +
+ + + +
+<blockpos> + +Current block index position (uint). +
+<msg> + +Text message exactly as it's printed on screen. +
+ + +
+msg:<level>:<msg> +
+Messages printed to the screen. +
+ + + + + + + + + +
+<level> + +One of `fatal`, `error`, `expected`, `status`, +`progress` or `verbose`. +
+fatal + +A fatal error occurred. Program will abort after this +message. +
+error + +A generic error condition that doesn't prevent the +program to continue. +
+expected + +An expected error condition. At present it +happens only when using the `-m` option with files +expected missing. +
+status + +A status message, usually providing context or a summary. +
+progress + +A progress message, often part of an ongoing operation. +
+verbose + +A verbose informative message, only shown in verbose mode. +
+<msg> + +Text message exactly as it's printed on screen. +
+

6 +Thermal Tags +

+The following tags are produced by the thermal monitoring functions +when SnapRAID is processing, typically during operations that involve +disk access. + + +
+thermal:ambient:device:<hwmon_dir>:<name>:<temp_file>:<label>:<temp> +
+Logs a temperature reading found in the system using the Linux +/sys/class/hwmon interface. Only present in Linux. +
+ + + + + + +
+<hwmon_dir> + +The hwmon directory name (e.g., hwmon0). +
+<name> + +The name of the hwmon device (e.g., k10temp). +
+<temp_file> + +The temperature file name (e.g., temp1_input). +
+<label> + +The label associated with the temperature sensor (e.g., Tdie). +
+<temp> + +The temperature reading in degrees Celsius. +
+ + +
+thermal:ambient:candidate:<temp> +
+Reports a temperature reading that is a candidate for the +ambient temperature, used in the heating model calculation. +
+ + +
+<temp> + +The candidate temperature in degrees Celsius. +
+ + +
+thermal:system:candidate:<temp> +
+Logs a temperature reading from a connected disk that is being +considered as a candidate for determining the ambient system +temperature. +
+ + +
+<temp> + +The current temperature read from the disk +(uint, degrees Celsius). +
+ + +
+thermal:system:final:<temp> +
+Logs the final ambient system temperature calculated. This +value is the lowest valid temperature observed among all +candidates, representing the room temperature. +
+ + +
+<temp> + +The calculated ambient temperature in degrees Celsius. +
+ + +
+thermal:current:<disk_name>:<device>:<temp> +
+Logs the most recent temperature reading for a specific disk +device. +
+ + + + +
+<disk_name> + +The configured name of the disk. +
+<device> + +The unique device ID (uint64). +
+<temp> + +The current temperature read from the disk in degrees +Celsius. +
+ + +
+thermal:highest:<temp> +
+Logs the highest temperature observed among all monitored disks +in the current measurement cycle. This is used for thermal +throttling. +
+ + +
+<temp> + +The highest temperature observed in degrees Celsius. +
+ + +
+thermal:heat:<disk_name>:<device>:<count>:<data_points> +
+Logs the entire history of temperature data points collected +so far for a specific disk, used for fitting the heating model. +Only monotone increasing temperatures are included in the history. +
+ + + + + + + +
+<disk_name> + +The configured name of the disk. +
+<device> + +The unique device ID (uint64). +
+<count> + +The total number of collected data points (uint). +
+<data_points> + +A comma-separated list of temperature/time pairs. +Each pair is formatted as <temp>/<time_offset>. +
+<temp> + +Temperature reading in degrees Celsius. +
+<time_offset> + +Time offset from the start of the thermal +monitoring (uint, seconds). +
+ + +
+thermal:params:<disk_name>:<device>:<k_heat>:<t_ambient>:<t_steady>:<rmse>:<r_squared>:<max_error> +
+Logs the estimated parameters for the exponential heating model +(fit using least squares) and associated quality metrics for a +specific disk. +The model is: T(t) = T_steady - (T_steady - T_0) e^(-kt), +where T_0 is the initial temperature. +
+ + + + + + + + + +
+<disk_name> + +The configured name of the disk. +
+<device> + +The unique device ID (uint64). +
+<k_heat> + +The heating rate constant, k (double). +
+<t_ambient> + +The ambient temperature, T_ambient (double). +
+<t_steady> + +The estimated steady-state temperature, T_steady (double), +which is the maximum expected temperature of the disk. +
+<rmse> + +Root Mean Square Error of the fit (double). +
+<r_squared> + +Coefficient of determination (R^2) of the fit (double). +
+<max_error> + +Maximum absolute error of the fit (double). +
+ + +
+thermal:spindown +
+Indicates that the thermal alarm limit has been reached, and +the process is initiating a disk spindown to begin the +cooldown procedure, preventing overheating. +
+ + +
+thermal:cooldown:<sleep_time> +
+Indicates the duration of the cooldown waiting period after +spindown. +
+ + +
+<sleep_time> + +The total time the system will wait for +cooldown (uint, seconds). +
+ + +
+thermal:spinup +
+Indicates that the cooldown period is complete, and the disks +are being spun back up to resume the operation. +
+

7 +Command Status Tags +

+This section describes the tags output with the `status` command. +

+Summary Tags +

+These tags provide general information about the array configuration +and overall state. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+summary:block_size:<uint> +
+The size of a block in bytes. This is the unit of parity +protection. +
+summary:parity_block_count:<uint> +
+The total number of blocks allocated for all parity levels +combined. +
+summary:parity_block_total:<name>:<uint> +
+Total blocks available for a specific parity level (e.g., +`parity`, `2-parity`). +
+summary:parity_block_free:<name>:<uint> +
+Free blocks available for a specific parity level. +
+summary:parity_block_free_min:<uint> +
+The minimum number of free blocks across all parity levels. +This determines the maximum size of data that can be added. +
+summary:file_count:<uint> +
+Total number of files in the array. +
+summary:file_block_count:<uint64> +
+Total number of data blocks used by files. +
+summary:fragmented_file_count:<uint> +
+Total number of fragmented files, meaning files whose blocks +are not contiguous. +
+summary:excess_fragment_count:<uint> +
+Total number of excess fragments (one less than the total fragments). +This is a measure of data fragmentation overhead. +
+summary:zerosubsecond_file_count:<uint> +
+Total number of files with a zero sub-second timestamp. This +can occur on certain filesystems and may affect change detection. +
+summary:file_size:<uint64> +
+Total size of all files in bytes. +
+summary:parity_size:<uint64> +
+Total size of allocated parity blocks in bytes. +
+summary:parity_size_max:<uint64> +
+Maximum possible parity size (allocated + min free) in bytes. +This is the effective maximum protection size. +
+summary:hash:<name> +
+The current hash algorithm in use (e.g., `sha256`). +
+summary:prev_hash:<name> +
+The previous hash algorithm used, if a rehash is in progress. +
+summary:best_hash:<name> +
+The best hash algorithm for optimal performance based on +system capabilities. +
+summary:total_wasted:<uint64> +
+Total wasted space (space on data disks exceeding parity +capacity) in bytes. +
+summary:total_used:<uint64> +
+Total used space by data files in bytes. +
+summary:total_free:<uint64> +
+Total free space (usable by data) in bytes, limited by parity +capacity. +
+summary:total_use_percent:<uint> +
+Overall array use percentage. +
+summary:has_unsynced:<uint> +
+Count of blocks that are unsynced (need a sync), meaning their +parity data is out of date. +
+summary:has_unscrubbed:<uint> +
+Count of blocks that are unscrubbed (just synced), meaning they +have never been verified since the last sync. +
+summary:has_rehash:<uint> +
+Count of blocks needing a rehash, usually due to a content file +update or hash algorithm change. +
+summary:has_bad:<count>:<first>:<last> +
+Count of bad blocks, along with the first and last bad block index. +Bad blocks indicate data or parity corruption. +
+summary:scrub_oldest_days:<uint> +
+Days ago the oldest block was last scrubbed. +
+summary:scrub_median_days:<uint> +
+Days ago the median block was last scrubbed. +
+summary:scrub_newest_days:<uint> +
+Days ago the newest block was last scrubbed. +
+

+Per-Disk Tags +

+These tags provide statistics for individual data disks. <name> +is the disk name. + + + + + + + + + + + + + + + + + +
+summary:disk_file_count:<name>:<uint> +
+Number of files on the disk. +
+summary:disk_block_count:<name>:<uint> +
+Number of blocks used by files on the disk. +
+summary:disk_fragmented_file_count:<name>:<uint> +
+Number of fragmented files on the disk. +
+summary:disk_excess_fragment_count:<name>:<uint> +
+Number of excess fragments on the disk. +
+summary:disk_zerosubsecond_file_count:<name>:<uint> +
+Number of files with zero sub-second timestamp on the disk. +
+summary:disk_file_size:<name>:<uint64> +
+Total size of files on the disk in bytes. +
+summary:disk_block_allocated:<name>:<uint> +
+Highest block index used on the disk + 1. +
+summary:disk_block_total:<name>:<uint> +
+Total blocks on the disk (physical size). +
+summary:disk_block_free:<name>:<uint> +
+Free blocks on the disk. +
+summary:disk_block_max_by_space:<name>:<uint> +
+Total blocks by disk space (used + free blocks), representing +the physical limit of the disk. +
+summary:disk_block_max_by_parity:<name>:<uint> +
+Total blocks limited by parity space (parity size + min parity +free blocks). +This is the logical limit imposed by the parity files. +
+summary:disk_block_max:<name>:<uint> +
+Maximum usable blocks (minimum of `..._by_space` and `..._by_parity`). +
+summary:disk_space_wasted:<name>:<int64> +
+Wasted space on the disk in bytes (positive if disk is larger +than usable parity space). +
+summary:disk_used:<name>:<uint64> +
+Used space on the disk in bytes. +
+summary:disk_free:<name>:<uint64> +
+Free usable space on the disk in bytes, limited by `disk_block_max`. +
+summary:disk_use_percent:<name>:<uint> +
+Disk use percentage relative to `disk_block_max`. +
+

+File Timestamp Tags +

+These tags list files with zero sub-second timestamps. + + +
+zerosubsecond:<disk_name>:<file_path> +
+Lists files that have a zero sub-second timestamp. +Up to 50 are logged per disk. +
+

+Block Information Tags +

+These tags are generated when the GUI option is enabled (`state->opt.gui`). + + +
+block_count:<uint> +
+The total number of blocks in the array. +
+ + +
+block:<index>:<time>:<used>:<unsynced>:<bad>:<rehash> +
+Status of a specific block. +
+ + + + + + + +
+<index> + +Block index. +
+<time> + +Last scrub time (Unix timestamp). A value of 0 means +the block has never been scrubbed. +
+<used> + +`used` if the block contains data, otherwise empty. +
+<unsynced> + +`unsynced` if the block needs a sync, otherwise empty. +
+<bad> + +`bad` if the block has errors, otherwise empty. +
+<rehash> + +`rehash` if the block needs a rehash, otherwise empty. +
+ + +
+block_noinfo:<index>:<used>:<unsynced> +
+Status of an unused block (no info recorded) in the content file. +
+ + + + +
+<index> + +Block index. +
+<used> + +`used` if the block contains data, otherwise empty. +
+<unsynced> + +`unsynced` if the block needs a sync, otherwise empty. +
+

+Scrub History Tags +

+These tags provide details on the scrub/sync time distribution. + + +
+info_count:<uint> +
+Total number of info records about past scrub and sync +operations stored in the content file. +
+ + +
+info_time:<time>:<count>:<status> +
+All the info records. +
+ + + + +
+<time> + +Unix timestamp of the scrub/sync. +
+<count> + +Number of blocks processed at this timestamp. +
+<status> + +"scrubbed" (for blocks verified to be correct) or +"new" (for synced blocks that haven't been scrubbed yet). +
+ + +
+scrub_graph_range:<max_columns>:<max_height> +
+Dimensions of the scrub history graph obtained from the +`info_time` records. This provides the boundary for the +precomputed graph data available in the `scrub_graph_bar` tags. +
+ + + +
+<max_columns> + +The number of columns in the graph (constant +GRAPH_COLUMN). +
+<max_height> + +The maximum height (peak count) of blocks found +in any column (the highest sum of scrubbed and new blocks). +
+ + +
+scrub_graph_bar:<index>:<days_ago>:<scrubbed>:<new> +
+Data for a column of the scrub history graph. Each column +represents a time period. +
+ + + + + +
+<index> + +Column index. From 0 to max_columns - 1. +
+<days_ago> + +Days ago for this column's time range. +
+<scrubbed> + +Count of scrubbed blocks in that day range. +
+<new> + +Count of newly synced (unscrubbed) blocks in that day range. +
+

8 +Command Sync/Scrub Tags +

+Tags specific for the `sync` and `scrub` commands. +Also the error tags are possible. +

+Summary Tags +

+These tags provide summary statistics at the end of the command. + + +
+hash_summary:error_file:<count> +
+Logs the total count of file-related errors that caused a +block to be skipped during the hashing phase. These are often +due to file changes (missing, size/time change) during the +sync operation. This happens only in `sync`. +
+ + +
+<count> + +Total number of file errors (uint). +
+ + +
+summary:error_file:<count> +
+Logs the total count of file-related errors encountered during +the process (e.g., missing files, file attribute changes). +
+ + +
+<count> + +The total number of file errors encountered (uint). +
+ + +
+summary:error_io:<count> +
+Logs the total count of input/output errors encountered on +data or parity disks. +
+ + +
+<count> + +The total number of I/O errors encountered (uint). +
+ + +
+summary:error_data:<count> +
+Logs the total count of "silent data errors" (data blocks +not matching their expected hash) encountered during the sync +process. +
+ + +
+<count> + +The total number of silent data errors encountered (uint). +
+ + +
+summary:exit:<status> +
+Logs the overall exit status of the command. The `status` is +one of the following: +
+ + + +
+ok + +No errors were found. +
+error + +If any errors were found (file, I/O, or data errors). +
+

9 +Command Check/Fix Tags +

+Tags specific for the `check` and `fix` commands. +Also the error tags are possible. +

+Fixed/Recovered Tags +

+These tags log successful repairs during fix operations. + + +
+fixed:<block_pos>:<disk_name>:<file_path>:<msg> +
+Indicates that a file was successfully fixed using parity data. +
+ + + + + +
+<block_pos> + +The block position being processed (uint). +
+<disk_name> + +The name of the disk. +
+<file_path> + +The file path relative to disk root (escaped). +
+<msg> + +A descriptive message indicating the nature of the fix +(e.g., `Fixed size`, `Fixed data error at position...`). +
+ + +
+parity_fixed:<block_pos>:<parity>:<msg> +
+Indicates that corrupted parity data was successfully +recomputed and written. +
+ + + + +
+<block_pos> + +The block position being processed (uint). +
+<parity> + +The name of the parity level (e.g., "parity", "2-parity"). +
+<msg> + +A descriptive message indicating the nature of the fix +(e.g., `Fixed data error`). +
+ + +
+empty_fixed:<disk_name>:<file_path>:<msg> +
+Logs successful recreation of a missing or corrupted empty file. +
+ + + + +
+<disk_name> + +The name of the disk. +
+<file_path> + +The file path relative to disk root (escaped). +
+<msg> + +A descriptive message indicating the nature of the fix +(e.g., `Fixed empty file`). +
+ + +
+hardlink_fixed:<disk_name>:<link_path>:<msg> +
+Logs successful recreation of a hard link during fix operation. +
+ + + + +
+<disk_name> + +The name of the disk. +
+<link_path> + +The hard link path relative to disk root (escaped). +
+<msg> + +A descriptive message indicating the nature of the fix +(e.g., `Fixed hardlink error`). +
+ + +
+symlink_fixed:<disk_name>:<link_path>:<msg> +
+Logs successful recreation of a symbolic link during fix operation. +
+ + + + +
+<disk_name> + +The name of the disk. +
+<link_path> + +The symlink path relative to disk root (escaped). +
+<msg> + +A descriptive message indicating the nature of the fix +(e.g., `Fixed symlink error`). +
+ + +
+dir_fixed:<disk_name>:<dir_path>:<msg> +
+Logs successful recreation of a missing directory during fix +operation. +
+ + + + +
+<disk_name> + +The name of the disk. +
+<dir_path> + +The directory path relative to disk root (escaped). +
+<msg> + +A descriptive message indicating the nature of the fix +(e.g., `Fixed dir error`). +
+

+Unrecoverable Error Tags +

+These tags log errors that could not be recovered. + + +
+unrecoverable:<block_pos>:<disk_name>:<file_path>:<msg> +
+Indicates that a block error could not be fixed due to +insufficient parity or other recovery limitations. +
+ + + + + +
+<block_pos> + +The block position being processed (uint). +
+<disk_name> + +The name of the disk. +
+<file_path> + +The file path relative to disk root (escaped). +
+<msg> + +A descriptive message indicating the nature of the problem +(e.g., `Unrecoverable error at position <file_pos>`, +`Unrecoverable unsynced error at position <file_pos>`). +
+ + +
+collision:<disk_name>:<file_path>:<collision_path>:<msg> +
+Logs that the modification time was not set on a recovered file to +avoid inode collision with another file. +
+ + + + + +
+<disk_name> + +The name of the disk. +
+<file_path> + +The file path relative to disk root (escaped). +
+<collision_path> + +The path of the colliding file (escaped). +
+<msg> + +A descriptive message indicating the nature of the problem +(e.g., `Not setting modification time to avoid inode collision`). +
+

+File Status Tags +

+These tags log the final status of files after processing. + + +
+status:unrecoverable:<disk_name>:<file_path> +
+Indicates that a file has unrecoverable errors and was renamed to +`.unrecoverable` (in fix mode) or cannot be recovered (in check mode). +
+ + + +
+<disk_name> + +The name of the disk. +
+<file_path> + +The file path relative to disk root (escaped). +
+ + +
+status:recovered:<disk_name>:<file_path> +
+Logs that a file was successfully recovered during fix operation. +
+ + + +
+<disk_name> + +The name of the disk. +
+<file_path> + +The file path relative to disk root (escaped). +
+ + +
+status:damaged:<disk_name>:<file_path> +
+Indicates that a file is damaged (in audit-only mode, e.g., using `check`). +
+ + + +
+<disk_name> + +The name of the disk. +
+<file_path> + +The file path relative to disk root (escaped). +
+ + +
+status:recoverable:<disk_name>:<file_path> +
+Logs that a file has errors but could be recovered in fix mode. +
+ + + +
+<disk_name> + +The name of the disk. +
+<file_path> + +The file path relative to disk root (escaped). +
+ + +
+status:correct:<disk_name>:<file_path> +
+Indicates that a file passed all checks successfully (verbose mode only). +
+ + + +
+<disk_name> + +The name of the disk. +
+<file_path> + +The file path relative to disk root (escaped). +
+

+Summary Tags +

+These tags provide summary statistics at the end of the command. + + +
+summary:error:<error_count> +
+Logs the total number of errors encountered. +
+ + +
+<error_count> + +Total number of errors (uint). +
+ + +
+summary:error_recovered:<recovered_count> +
+Logs the total number of errors successfully recovered (fix mode only). +
+ + +
+<recovered_count> + +Number of recovered errors (uint). +
+ + +
+summary:error_unrecoverable:<unrecoverable_count> +
+Logs the total number of unrecoverable errors (not in audit-only mode). +
+ + +
+<unrecoverable_count> + +Number of unrecoverable errors (uint). +
+ + +
+summary:exit:<status> +
+Logs the overall exit status of the command. The `status` is one of +the following: +
+ + + + + + +
+`ok` + +Indicates that the operation completed with no errors. +
+`recovered` + +Indicates that the operation completed with all +errors successfully recovered (fix mode only). +
+`recoverable` + +Indicates that errors were found but are all +recoverable (check mode only). +
+`unrecoverable` + +Indicates that unrecoverable errors were +found. +
+`error` + +Indicates that errors were found (audit-only mode). +
+

10 +Command List Tags +

+This section describes the tags output with the `list` command. +

+List Tags +

+These tags log details about individual files and links processed during +the listing operation. + + +
+file:<disk_name>:<subpath>:<size>:<mtime_sec>:<mtime_nsec>:<inode> +
+Logs details for a regular file found on a disk. +
+ + + + + + + +
+<disk_name> + +The configured name of the disk. +
+<subpath> + +The path of the file relative to the disk's root +(escaped). +
+<size> + +The size of the file in bytes (uint64). +
+<mtime_sec> + +The file's modification time in seconds since the +Epoch (int64). +
+<mtime_nsec> + +The file's modification time nanosecond component +(uint). +
+<inode> + +The file's inode number (int64). +
+ + +
+link_<type>:<disk_name>:<subpath>:<linkto> +
+Logs details for a link found on a disk. The `<type>` component +varies based on the kind of link. +
+ + + + + +
+<type> + +The type of link, one of: `hardlink`, `symlink`, +`symdir` (symlink to a directory), `junction` +(Windows-specific reparse point). +
+<disk_name> + +The configured name of the disk (string). +
+<subpath> + +The path of the link relative to the disk's root +(escaped). +
+<linkto> + +The target path of the link (escaped). +
+

+Summary Tags +

+These tags log final statistics about the entire listing operation. + + +
+summary:file_count:<count> +
+Logs the total number of regular files processed. +
+ + +
+<count> + +The total number of files (uint). +
+ + +
+summary:file_size:<size> +
+Logs the total size of all regular files processed. +
+ + +
+<size> + +The cumulative size of all files (uint64, bytes). +
+ + +
+summary:link_count:<count> +
+Logs the total number of links processed (hardlinks, symlinks, +symdirs, junctions). +
+ + +
+<count> + +The total number of links (uint). +
+ + +
+summary:exit:ok +
+Indicates a successful completion of the listing operation. +Note that if a fatal error happens, the program will abort, +and you won't get this tag. +
+

11 +Command Dup Tags +

+This section describes the tags output with the `dup` command. +

+Duplicate Tags +

+These tags log information about detected duplicate files and provide +a summary of the duplicate finding process. The content hash of the +whole file is used to determine duplicates. + + +
+dup:<diskname1>:<file_path1>:<diskname2>:<file_path2>:<size>: dup +
+Logs the information about a pair of duplicate files found. +The first file listed is the one just processed, and the second +file is the previously processed file that has the same content hash. +
+ + + + + + +
+<diskname1> + +The configured name of the disk containing the +newly processed duplicate file. +
+<file_path1> + +The path of the newly processed duplicate file +relative to its disk's mount point (escaped). +
+<diskname2> + +The configured name of the disk containing the +previously processed file that is the duplicate +of `<file_path1>`. +
+<file_path2> + +The path of the previously processed duplicate file +relative to its disk's mount point (escaped). +
+<size> + +The size of the duplicate file in bytes (uint64). This +size corresponds to the file `<file_path2>`. +
+

+Summary Tags +

+These tags provide a final summary of the duplicate finding process. + + +
+summary:dup_count:<count> +
+Logs the total number of duplicate files found. A file is counted +as a duplicate if its hash matches a hash already seen. +
+ + +
+<count> + +The total count of duplicate files (uint). +
+ + +
+summary:dup_size:<size> +
+Logs the total size of all duplicate files found. This size is +the sum of the sizes of all files considered duplicates. +
+ + +
+<size> + +The total size of duplicate files in gigabytes (uint64). +
+ + +
+summary:exit:unique +
+Logs the final exit status indicating that no duplicate files were +found. This tag is logged if `<count>` is zero. +
+ + +
+summary:exit:dup +
+Logs the final exit status indicating that at least one duplicate +file was found. This tag is logged if `<count>` is greater than +zero. +
+

12 +Command Pool Tags +

+This section describes the tags output with the `pool` command. + + +
+summary:link_count:<count> +
+Logs the total number of links created (symlinks, junctions). +
+ + +
+<count> + +The total number of links (uint). +
+ + +
+summary:exit:ok +
+Indicates a successful completion of the pool operation. +Note that if a fatal error happens, the program will abort, +and you won't get this tag. +
+

13 +Command Rehash Tags +

+This section describes the tags output with the `rehash` command. +

+Summary Tags +

+These tags provide a final summary of the rehash scheduling process. + + +
+summary:exit:scheduled +
+Logs the final exit status indicating that a rehash operation has +been successfully scheduled. The rehash will be performed +incrementally in future `sync` or `scrub` commands. +
+ + +
+summary:exit:already_in_progress +
+Logs the final exit status indicating that a rehash is already +in progress and cannot be scheduled again. This causes the +program to exit with a fatal error. +
+ + +
+summary:exit:not_required +
+Logs the final exit status indicating that the current hash +algorithm is already the `best hash` for the platform, and thus +a rehash is not required. This causes the program to exit with +a fatal error. +
+

14 +Command Smart Tags +

+This section describes the tags output with the `smart` command. +

+Note that a `<disk_name>` may be associated with more `<device_file>`, +in case the logical disk uses more physical disks. In such a case, +you'll see multiple tags for the same `<disk_name>` but with different +`<device_file>`. +

+SMART Attributes +

+Tags logging specific disk identification and raw SMART attribute +values. + + +
+smart:<device_file>:<disk_name> +
+Logs the start of the SMART report for a device. +
+ + + +
+<device_file> + +The file path of the device (e.g., /dev/sdb). +
+<disk_name> + +The configured name of the disk. +
+ + +
+attr:<device_file>:<disk_name>:serial:<serial_number> +
+Logs the disk's serial number. +
+ + +
+<serial_number> + +The disk's serial number (escaped). +
+ + +
+attr:<device_file>:<disk_name>:vendor:<vendor> +
+Logs the disk's vendor string. +
+ + +
+<vendor> + +The disk's vendor identifier (escaped). +
+ + +
+attr:<device_file>:<disk_name>:model:<model> +
+Logs the disk's model string. +
+ + +
+<model> + +The disk's model identifier (escaped). +
+ + +
+attr:<device_file>:<disk_name>:afr:<afr_value>:<afr_prob> +
+Logs the estimated Annual Failure Rate (AFR) and the +probability of one failure in the next year based on SMART +attributes. The AFR is calculated using the maximum rate +reported by specific SMART attributes (5, 187, 188, 197, 198). +
+ + + +
+<afr_value> + +The computed Annual Failure Rate (double). +
+<afr_prob> + +The probability of one or more failures in the +next year (double). +
+ + +
+attr:<device_file>:<disk_name>:size:<size_bytes> +
+Logs the size of the disk. +
+ + +
+<size_bytes> + +The disk size in bytes (uint64). +
+ + +
+attr:<device_file>:<disk_name>:error:<error_count> +
+Logs the raw value of the total error count (e.g., from SMART +attribute 199, if used for the report). +
+ + +
+<error_count> + +The total error count (uint64). +
+ + +
+attr:<device_file>:<disk_name>:rotationrate:<rate> +
+Logs the disk's rotation rate. A value of 0 indicates an SSD. +
+ + +
+<rate> + +The rotation rate (uint64, RPM). +
+ + +
+attr:<device_file>:<disk_name>:flags:<flags_decimal>:<flags_hex> +
+Logs the SMART status flags from the utility (e.g., smartctl). +
+ + + +
+<flags_decimal> + +The raw flags value (uint64, decimal). +
+<flags_hex> + +The raw flags value (uint64, hexadecimal). +
+ + +
+attr:<device_file>:<disk_name>:<id>:<value_decimal>:<value_hex> +
+Logs the raw value of any assigned SMART attribute. +
+ + + + +
+<id> + +The SMART attribute ID (uint). +
+<value_decimal> + +The raw attribute value (uint64, decimal). +
+<value_hex> + +The raw attribute value (uint64, hexadecimal). +
+

+Summary +

+Tags logging the overall failure probabilities for the array. + + +
+summary:array_failure:<array_afr>:<array_prob> +
+Logs the total estimated failure rate for the entire array +(sum of individual disk AFRs) and the probability of at least +one disk failure in the next year. +
+ + + +
+<array_afr> + +The sum of AFRs of all disks in the array (double). +
+<array_prob> + +The probability of at least one disk failure in +
+

+
+the next year (double). +
+

15 +Command Probe Tags +

+This section describes the tags output with the `probe` command. +

+Note that a `<disk_name>` may be associated with more `<device_file>`, +in case the logical disk uses more physical disks. In such a case, +you'll see multiple tags for the same `<disk_name>` but with different +`<device_file>`. +

+Device Power State +

+Tags used to report the power state of each device. + + +
+probe:<device_file>:<disk_name>:<power_state> +
+Logs the detected power state of a device. +
+ + + + +
+<device_file> + +The file path of the device (e.g., /dev/sdb). +
+<disk_name> + +The configured name of the disk. +
+<power_state> + +The numerical power state: 0: Unknown, +1: StandBy, 2: Active. +
+

16 +Error Tags +

+These tags report specific errors that occur on data disks during the +commands that access files and parities. + + +
+error:<block>:<disk_name>:<file>:<msg> +
+Logs file access errors (open, read, file changed) during the +data disk read operation for parity calculation or verification. +
+ + + + + +
+<block> + +The zero-based index of the block where the error occurred (uint). +
+<disk_name> + +The name of the data disk. +
+<file> + +The path (relative to the disk mount point) of the +file containing the block (escaped). +
+<msg> + +A descriptive message indicating the nature of the +error (e.g., `Open/Read/Write EIO error`, `Open/Read/Write error`, +`Data error at position <pos>, diff bits <diff>/<bits>`). +
+ + +
+parity_error:<block>:<level>:<msg> +
+Logs errors during parity disk read or write operations. +
+ + + + +
+<block> + +The zero-based index of the block where the error occurred (uint). +
+<level> + +The configuration name of the parity level (e.g., +`parity`, `2-parity`). +
+<msg> + +A descriptive message indicating the nature of the +error (e.g., `Read/Write EIO error`, `Read/Write error`, +`Data error, diff bits <diff>/<bits>`). +
+ + +
+hardlink_error:<disk_name>:<link_path>:<target_path>:<msg> +
+Indicates an error when attempting to access a hard link. +
+ + + + + +
+<disk_name> + +The name of the disk. +
+<link_path> + +The hard link path relative to disk root (escaped). +
+<target_path> + +The target path of the hard link (escaped). +
+<msg> + +A descriptive message indicating the nature of the +error (e.g., `Hardlink stat error`, +`Hardlink error for not regular file`, `Hardlink to stat error`, +`Hardlink-to error for not regular file`, +`Hardlink mismatch for different inode`). +
+ + +
+symlink_error:<disk_name>:<link_path>:<msg> +
+Indicates an error when attempting to access a symbolic link. +
+ + + + +
+<disk_name> + +The name of the disk. +
+<link_path> + +The symlink path relative to disk root (escaped). +
+<msg> + +A descriptive message indicating the nature of the +error (e.g., `Symlink read error`, +`Symlink data error '<actual>' instead of '<expected>'`). +
+ + +
+dir_error:<disk_name>:<dir_path>:<msg> +
+Indicates an error when attempting to access a directory. +
+ + + + +
+<disk_name> + +The name of the disk. +
+<dir_path> + +The directory path relative to disk root (escaped). +
+<msg> + +A descriptive message indicating the nature of the +error (e.g., `Dir stat error`, `Dir error for not directory`). +
+ + +
+outofparity:<disk_name>:<file_path> +
+Logs that a file's blocks extend beyond the available parity +space, indicating that the parity files are too small to +protect all data. This occurs when data requires more parity +than is available on the parity disk(s) and is a critical +warning. +
+ + + +
+<disk_name> + +The name of the disk containing the file. +
+<file_path> + +The file path relative to the disk root (escaped). +
+ +