snapraid/doc/snapraid_log.d

Name{number}
	snapraid_log - SnapRAID Log Format

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`).
	=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` or `--gui-verbose` option
	is used. They provide extra verbose state and runtime progress only
	useful for a GUI interface.
	In GUI mode, the structured log is intended to be consumed by the GUI.
	Fatal errors are therefore not duplicated to standard error when they
	are successfully written to the log. If the log is unavailable or
	writing it fails, the fatal error is printed to standard error as a
	fallback.

	Integer values are marked as `uint` when they are unsigned and as `int`
	when they are signed. However, for practical purposes you can treat
	all of them as signed integers.
	All integer values should be assumed to be 64 bits wide, regardless
	of the signed/unsigned marker.
	Floating point values are marked as `float`.

Configuration Tags
	These tags report the memory usage and global configuration.

	=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>:<uuid>
		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.
		<uuid> - The UUID of the filesystem containing the dir.

	=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>:<uuid>
		The parity files as defined in the configuration file.

		<parity_level>[/<split_index>] - One of `parity`, `2-parity`,
			..., `6-parity`. This corresponds to the level of redundancy.
			In case of split parity, the parity name is followed
			by `/N` to indicate the split index, where N starts
			from 0. The `/0` is always omitted.
		<path> - The path (escaped).
		<uuid> - The UUID of the filesystem containing the path.

	=fsinfo_data:<disk_name>:<size>:<free>
		The filesystem information of the specified data disk.

		<size> - The size of the data disk (uint).
		<free_size> - The free size in the data disk (uint).

	=fsinfo_parity:<parity_level>:<size>:<free>
		The filesystem information of the specified parity disk.
		In case of multiple splits this is the sum of the sizes of all
		splits.

		<size> - The size of the parity disk (uint).
		<free_size> - The free size in the parity disk (uint).

	=fsinfo_data_split:<disk_name>:<size>:<free>:<type>:<label>
		The filesystem information of the specified data disk.

		<size> - The size of the data disk (uint).
		<free_size> - The free size in the data disk (uint).
		<type> - The filesystem type. A string like `ext4`, `ntfs`.
		<label> - The label associated to the filesystem.

	=fsinfo_parity_split:<parity_level>[/<split_index>]:<size>:<free>:<type>:<label>
		The filesystem information of the specified parity split.

		<size> - The size of the parity disk (uint).
		<free_size> - The free size in the parity disk (uint).
		<type> - The filesystem type. A string like `ext4`, `ntfs`.
		<label> - The label associated to the filesystem.

	=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
		(uint). 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 Tags
	These tags report the information stored in the content file.

	=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_write:<path>
		The absolute path to a content file being written (escaped).
		You will see multiple writes as the content file is saved in
		multiple copies.

	=content_data:<disk_name>:<size>:<free_size>
		The size of the data disk as stored in the content file.

		<disk_name> - Name of the data disk.
		<size> - The size of the data disk (uint).
		<free_size> - The free size in the data disk (uint).

	=content_parity:<parity_level>:<size>:<free_size>
		The size of the parity disk as stored in the content file.
		In case of multiple splits this is the sum of the sizes of all
		splits.

		<parity_level> - Name of the parity.
		<size> - The total size of the parity disk (uint).
		<free_size> - The free size in the parity disk (uint).

	=content_data_split:<disk_name>:<uuid>
		The data disk info as stored in the content file.

		<disk_name> - Name of the data disk.
		<uuid> - The UUID of the disk filesystem as stored in the
			content file.

	=content_parity_split:<parity_level>[/<split_index>]:<uuid>:<path>:<size>
		The parity split info as stored in the content file.

		<parity_level>[/<split_index>] - One of `parity`, `2-parity`,
			..., `6-parity`. This corresponds to the level of redundancy.
			In case of split parity, the parity name is followed
			by `/N` to indicate the split index, where N starts
			from 0. The `/0` is always omitted.
		<uuid> - The UUID of the disk containing the path.
		<path> - The path of the parity file (escaped).
		<size> - The size of the parity file (uint).

	=content_info:<kind>:<counter>
		The counters in the content file. The `kind` is
		one of the following:

		file - The count of files.
		hardlink - The counter of hardlinks.
		symlink - The counter of symlinks.
		dir_empty - The counter of empty directories.
		block_bad - The counter of bad blocks. Bad blocks indicate data
			or parity corruption.
		block_rehash - The counter of blocks needing a rehash, usually
			due to hash algorithm change.
		block_unscrubbed - The counter of blocks that are unscrubbed
			(just synced), meaning they have never been verified
			since their first sync.
		block_unsynced - The counter of blocks that are unsynced (need a sync),
			meaning their parity data is out of date.
		block - The total counter of blocks.

	=bucket_count:<uint>
		Total number of info records listed with `bucket`.

	=bucket_block_count:<uint>
		Total number of info blocks listed with `bucket`. This is the
		sum of all the counters listed.

	=bucket:<time>:<count_scrubbed>:<count_new>
		The info records.

		<time> - Unix timestamp of the scrub/sync.
		<count_scrubbed> - Number of blocks scrubbed at this timestamp.
		<count_new> - Number of blocks that were synced at this
			timestamp and haven't been scrubbed yet.

Diagnostics Tags
	=version:<version>
		The version of SnapRAID run.

	=unixtime:<time>
		The current time in the unix format (uint), 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 (uint).

	=memory:block:<bytes>
		Size of the internal `snapraid_block` structure in bytes (uint).

	=memory:extent:<bytes>
		Size of the internal `snapraid_extent` structure in bytes (uint).

	=memory:file:<bytes>
		Size of the internal `snapraid_file` structure in bytes (uint).

	=memory:link:<bytes>
		Size of the internal `snapraid_link` structure in bytes (uint).

	=memory:dir:<bytes>
		Size of the internal `snapraid_dir` structure in bytes (uint).

Scan Tags
	These tags report detected differences between the filesystem and the
	content file. They are output for every discovered change.

	=scan:equal:<disk_name>:<path>
		A file, link, or directory is equal (unchanged).
		No action is required for this item.
		Only produced when `--gui-verbose` option is used.

		<disk_name> - Name of the data disk.
		<path> -  Path to the file/link relative to the disk mount
			(escaped).

	=scan:add:<disk_name>:<path>
		A new file or link 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 or link has been removed from the filesystem
		since the last 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 to a different directory on the same disk.
		This is an efficient operation that only updates the path
		metadata without rehashing 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 on the same or
		any other disk.
		This is detected by matching the file name,
		size, and timestamp, and is an efficient operation that avoids
		rehashing all blocks.

		<source_disk> - The original file's disk.
		<source_path> - The original file's location (escaped).

	=scan:relocate:<disk_name>:<path>:<source_disk>:<source_path>
		Like `copy`, but the original file has disappeared.
		The difference between `move` and `relocate` on the same
		disk is that `move` is only used if the inode remains
		the same.

	=scan:restore:<disk_name>:<path>
		A file's inode has changed but not its directory, name,
		timestamp 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 files and links whose metadata and data match
		the current parity (uint).

	=summary:added:<count>
		Total number of brand new files and links not present in the
		last sync (uint).

	=summary:removed:<count>
		Total number of files and links that existed in the last sync
		but are now missing (uint).

	=summary:updated:<count>
		Total number of existing files where the timestamp or size has
		changed (uint).

	=summary:moved:<count>
		Total number of files relocated to a new path or renamed but
		retaining the same inode (uint).

	=summary:copied:<count>
		Total number of new files created by copying an existing
		protected file to a new path (uint).

	=summary:relocated:<count>
		Total number of new files created by relocating an existing
		protected file to a new path (uint).

	=summary:restored:<count>
		Total number of new files matching a parity entry by
		name/time/size but with a new inode (uint).

	=summary:exit:<status>
		Logs the overall exit status of the command. The `status` is
		one of the following:

		equal - Indicates that no differences were found.
			The array is already synchronized.
		diff - Indicates that differences were found.
			The array needs a `sync` operation.
		unsynced - The array has an interrupted sync.
			The array needs another `sync` operation.

General Progress and Execution Tags
	These tags are used to report the runtime processing of the commands
	`sync`, `scrub`, `check` and `fix`.
	Only produced when `--gui` option is used.

	=run:begin:<blockbegin>:<blockend>:<count>
		A tag indicating the start of the command execution.

		<blockbegin> - Starting block index (uint).
		<blockend> - Ending block index + 1 (uint).
		<count> - Number of blocks to process. It may be less
			than <blockend> - <blockbegin> + 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:<blockidx>:<blockdone>:<sizedone>:<perc>:<eta>:<speed_mbs>:<cpu>:<elapsed>:<temp>:<steady_temp>
		Detailed progress information during command execution.

		<blockidx> - Current block index position processed (uint).
		<blockdone> - Number of blocks processed (uint).
		<sizedone> - Current size processed (uint).
		<perc> - Completion percentage (uint).
		<eta> - Estimated time to completion in seconds. Empty if not
			available (uint).
		<speed_mbs> - Data processing speed in MB/s. Empty if not
			available (uint).
		<cpu> - CPU usage percentage. Empty if not available (uint).
		<elapsed> - Elapsed time in seconds (uint).
		<temp> - Current max temperature of the disks. Empty if not
			available (uint).
		<steady_temp> - Expected steady temperature of the disks.
			Empty if not available (uint).

	=sigint:<blockidx>:<msg>
		A user interruption (e.g., Ctrl+C) was signaled. The process
		is gracefully aborting.

		<blockidx> - 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`, `fatal_hardware`, `error`, `error_hardware`,
			`expected`, `status`, `progress` or `verbose`.
		fatal, fatal_hardware - A fatal error occurred. Program will
			abort after this message.
			The `hardware` one means that the problem was caused
			by a hardware failure, like an Input/Output error
			or a silent data error.
		error, error_hardware - A generic error condition that doesn't
			prevent the program to continue.
			The `hardware` one means that the problem was caused
			by a hardware failure, like an Input/Output error
			or a silent data error.
		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.

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>[/<split_index>]:<device>:<temp>
		Logs the most recent temperature reading for a specific disk
		device.

		<disk_name>[/<split_index>] - The configured name of the disk.
			In case of split parity, the parity name is followed
			by `/N` to indicate the split index, where N starts
			from 0. The `/0` is always omitted.
		<device> - The unique device ID (uint).
		<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>[/<split_index>]:<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.

		<device> - The unique device ID (uint).
		<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>[/<split_index>]:<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.

		<device> - The unique device ID (uint).
		<k_heat> - The heating rate constant, k (float).
		<t_ambient> - The ambient temperature, T_ambient (float).
		<t_steady> - The estimated steady-state temperature, T_steady (float),
			which is the maximum expected temperature of the disk.
		<rmse> - Root Mean Square Error of the fit (float).
		<r_squared> - Coefficient of determination (R^2) of the fit (float).
		<max_error> - Maximum absolute error of the fit (float).

	=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.

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:<uint>
		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:<uint>
		Total size of all files in bytes.
	=summary:parity_size:<uint>
		Total size of allocated parity blocks in bytes.
	=summary:parity_size_max:<uint>
		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:<uint>
		Total wasted space (space on data disks exceeding parity
		capacity) in bytes.
	=summary:total_used:<uint>
		Total used space by data files in bytes.
	=summary:total_free:<uint>
		Total free space (usable by data) in bytes, limited by parity
		capacity.
	=summary:total_use_percent:<uint>
		Overall array use percentage.
	=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.
	=summary:exit:<status>
		Logs the overall exit status of the command. The `status` is
		one of the following:

		ok - No issues. The array is fully synchronized and healthy.
		bad - The array has some blocks marked as bad.
			The array needs a `-e fix` and and a `-p bad scrub`
			operation.
		unsynced - The array has an interrupted sync.
			The array needs another `sync` operation.

    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>:<uint>
		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>:<int>
		Wasted space on the disk in bytes (positive if disk is larger
		than usable parity space).
	=summary:disk_used:<name>:<uint>
		Used space on the disk in bytes.
	=summary:disk_free:<name>:<uint>
		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.

    Scrub Graph Tags
	These tags provide a simple graph data of the past scrub and sync
	operations.

	=scrub_graph_range:<max_columns>:<max_height>
		Dimensions of the scrub history graph obtained from the
		`content_info:bucket` 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.
		<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.

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_soft:<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_soft:<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 issues. The array is fully synchronized and healthy.
		warning - Some files were skipped due to likely intentional
			modifications. No hardware risk.
		error - Critical failure. Indicates serious issues like I/O failures
			or silent data corruption. Requires immediate hardware
			or filesystem inspection.

Command Check/Fix Tags
	Tags specific for the `check` and `fix` commands. For `audit` mode,
	it's inteded `check` with the `--audit-only` option.
	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` (fix) or cannot be recovered (check).

		<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:recoverable:<disk_name>:<file_path>
		Logs that a file has errors but could be recovered with a
		`fix` (check).

		<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).

		<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_soft:<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:error_recovered:<recovered_count>
		Logs the total number of errors successfully recovered (fix).

		<recovered_count> - Number of recovered errors (uint).

	=summary:error_recoverable:<recoverable_count>
		Logs the total number of errors that can be recovered (check).

		<recoverable_count> - Number of recoverable errors (uint).

	=summary:error_unrecoverable:<unrecoverable_count>
		Logs the total number of unrecoverable errors (fix/check).

		<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 (audit).
		warning - Some files were different than expected, likely caused
			by intentional modification of the files.
			No hardware risk (audit).
		error - Critical failure. Indicates serious issues like I/O failures
			or silent data corruption. Requires immediate hardware
			or filesystem inspection (audit).
		recovered - Indicates that the operation completed with all
			errors successfully recovered (fix).
		recoverable - Indicates that errors were found but are all
			recoverable (check).
		unrecoverable - Indicates that unrecoverable errors were
			found (check/fix).

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 (uint).
		<mtime_sec> - The file's modification time in seconds since the
			Epoch (int).
		<mtime_nsec> - The file's modification time nanosecond component
			(uint).
		<inode> - The file's inode number (uint).

	=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 (uint, 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.

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 (uint). 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 (uint).

	=summary:exit:<status>
		Logs the overall exit status of the command. The `status` is one of
		the following:

		unique - Indicates that no duplicate files were found.
		dup - Indicates that at least one duplicate file was found.

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.

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:<status>
		Logs the overall exit status of the command. The `status` is one of
		the following:

		scheduled - Indicates that a rehash operation has
			been successfully scheduled. The rehash will be performed
			incrementally in future `sync` or `scrub` commands.
		already_in_progress - Indicates that that a rehash is already
			in progress and cannot be scheduled again. This causes the
			program to exit with a fatal error.
		not_required - Indicates 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.

Command Smart And Probe Tags
	This section describes the tags output by the `smart` and `probe`
	commands. The main difference between the two is that `probe` doesn't
	spin up the disk, so it won't be able to get all attributes if the
	disk is spun down. The `smart` command, instead, will always get all
	attributes, but with the risk of spinning up all disks.

	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 `<attr>` and `<smart>` tags for the same
	`<disk_name>` but with different `<device_file>`. The exception is the
	`stat` attrbute that is cumulative for all the devices part of the
	disk.

	In case of split parity, the parity name is followed by `/N` to indicate
	the split index, where N starts from 0. The `/0` is always omitted.

    Attributes
        Tags logging specific disk identification and attribute values.

	=smart:<device_file>:<disk_name>[/<split_index>]
		Logs the start of the SMART report for a device.

		<device_file> - The file path of the device (e.g., /dev/sdb).
		<disk_name>[/<split_index>] - The configured name of the disk.
			In case of split parity, the parity name is followed
			by `/N` to indicate the split index, where N starts
			from 0. The `/0` is always omitted.

	=attr:<device_file>:<disk_name>[/<split_index>]:serial:<serial_number>
		Logs the disk's serial number.

		<serial_number> - The disk's serial number (escaped).

	=attr:<device_file>:<disk_name>[/<split_index>]:family:<family>
		Logs the disk's model family string.

		<family> - The disk's model family identifier (escaped).

	=attr:<device_file>:<disk_name>[/<split_index>]:model:<model>
		Logs the disk's model string.

		<model> - The disk's model identifier (escaped).

	=attr:<device_file>:<disk_name>[/<split_index>]:interface:<interface>
		Logs the disk's interface. Something like `USB`, `SATA`, `NVMe`.

		<interface> - The disk's interface (escaped).

	=attr:<device_file>:<disk_name>[/<split_index>]:afr:<afr>:<prob>
		Logs the estimated Annual Failure Rate (AFR) and the
		probability of at least one failure in the next year based on
		SMART attributes. The AFR is calculated using the SMART
		attributes (5, 187, 188, 197, 198).

		<afr> - The computed Annual Failure Rate (the average number
			of failures you expect in a year) (float).
		<prob> - The probability of at least one failure in the
			next year (float).

	=attr:<device_file>:<disk_name>[/<split_index>]:size:<size_bytes>
		Logs the size of the disk.

		<size_bytes> - The disk size in bytes (uint).

	=attr:<device_file>:<disk_name>[/<split_index>]:error_protocol:<error_count>
		Counts command, transport, or controller-level errors reported
		by the device. These reflect failed I/O operations not directly
		caused by media defects (for example interface, firmware, or
		power-related errors).
		This counter is cumulative and never resets to zero, even if
		the underlying error condition is resolved.

		<error_count> - The total error count (uint).

	=attr:<device_file>:<disk_name>[/<split_index>]:error_medium:<error_count>
		Counts media-level errors where data could not be reliably
		read or written. These indicate actual storage surface or
		flash failures and may imply data loss.
		This counter is cumulative and never resets to zero, even if
		the underlying error condition is resolved.

		<error_count> - The total error count (uint).

	=attr:<device_file>:<disk_name>[/<split_index>]:wear_level:<percentage>
		The wear level of the SSD/NVME expressed as a percentage, where a
		value of 0 represents a brand new drive with zero wear and
		a value of 100 indicates the drive has reached or exceeded its
		manufacturer-rated design life. This metric is provided as a
		normalized unsigned integer, offering a consistent health
		indicator across various SSD/NVME vendors and interface types
		by mapping diverse hardware counters into a single
		standardized scale.

		<percentage> - Wear level percentage (uint).

	=attr:<device_file>:<disk_name>[/<split_index>]:rotationrate:<rate>
		Logs the disk's rotation rate.

		<rate> - The rotation rate. A value of 0 indicates a
			solid-state drive (SSD) or other non-rotating medium.
			A value of 1 indicates a rotational disk of unknown
			precise speed. Values greater than 1 indicate the
			rotational speed in RPM.

	=attr:<device_file>:<disk_name>[/<split_index>]:flags:<flags_decimal>:<flags_hex>
		Logs the SMART status flags from the `smartctl` utility.
		Per the smartctl manpage, these flags are bit-mapped
		to indicate specific issues like `Command line did not parse`,
		`Device could not be opened`, or `SMART status check returned 'DISK FAILING'`.

		<flags_decimal> - The raw flags value (uint, decimal).
		<flags_hex> - The raw flags value (uint, hexadecimal).

	=attr:<device_file>:<disk_name>[/<split_index>]:<id>:<raw_decimal>:<raw_hex>:<norm>:<worst>:<thresh>:<name>:<type>:<updated>:<when_failed>
		Logs the raw value of any assigned SMART attribute.

		<id> - The SMART attribute ID (uint).
		<raw_decimal> - The raw attribute value (uint, decimal).
		<raw_hex> - The raw attribute value (uint, hexadecimal).
		<norm> - The normalized value (uint).
		<worst> - The worst value (uint).
		<thresh> - The threshold value (uint).
		<name> - Name of the attribute.
		<type> - Type of the attribute: `prefail` or `oldage`.
		<updated> - Update method of the attribute: `always` or `offline`.
		<when_failed> - If and when the attribute failed: `never` or `past` or `now`.

	=attr:<device_file>:<disk_name>[/<split_index>]:power:active
		Logs that the device was confirmed to be in an active power
		state after a status probe.

	=attr:<device_file>:<disk_name>[/<split_index>]:power:standby
		Logs that the device was confirmed to be in a standby/spun-down
		state.

	=attr:<device_file>:<disk_name>[/<split_index>]:power:up
		Logs a successful spin-up operation via direct O_DIRECT
		read.

	=attr:<device_file>:<disk_name>[/<split_index>]:power:down
		Logs a successful spin-down operation initiated via the
		smartctl command.

	=stat:<disk_name>:<access_number>
		Logs the total number of read and write accesses done on the
		disk. This is a cumulative value that include all the devices
		and split of the disk.
		Comparing this number at different times, you can detect if the
		disk was used during that time.

		<access_number> - Total number of accesses (uint).

    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 failure in the next year.

		<array_afr> - The sum of AFRs of all disks in the array (the
			average number of failures you expect in a year) (float).
		<array_prob> - The probability of at least one failure in
			the next year (float).

Device Status Tags
	These tags log the lifecycle of hardware interactions and external
	command execution with the `smartctl` command.

	=device:<device_file>:<disk_name>[/<split_index>]:shell
		Logs a failure in the command shell execution environment.

		<device_file> - The system path to the device node.
		<disk_name>[/<split_index>] - The configured name of the disk.
			In case of split parity, the parity name is followed
			by `/N` to indicate the split index, where N starts
			from 0. The `/0` is always omitted.

	=device:<device_file>:<disk_name>[/<split_index>]:error:<errno>
		Logs a low-level system error during direct file operations.
		This is triggered when open(), read(), or close()
		calls fail during a spin-up attempt.

		<errno> - The standard integer error number provided by
			the OS.

	=device:<device_file>:<disk_name>[/<split_index>]:error:abort
		Logs that an external process (smartctl) failed to complete
		normally, such as being terminated by a signal rather than
		exiting.

	=device:<device_file>:<disk_name>[/<split_index>]:exit:<exit_code>
		Logs that the external command (smartctl) returned a non-zero
		exit code that was not explicitly recognized as a valid state.

		<exit_code> - The integer exit status returned by the
			process (int).

Error Tags
	These tags report specific errors that occur on data disks during the
	commands that access files and parities.

	=error[_io|_data]:<block>:<disk_name>:<file>:<msg>
		Logs errors affecting data files.

		With no suffix, `error` indicates a soft or logical error not
		classified as a hardware I/O or silent data error.

		_io - Indicates a physical Input/Output error, typically
			signaling a failing sector, device, or cable issue.
		_data - Indicates data that was read successfully but failed
			the checksum/hash verification, signaling `silent`
			corruption or an unsuccessful parity match.
		<block> - The zero-based SnapRAID parity position associated with
			the error (uint). It identifies the logical position affected
			by the failed operation, not necessarily the physical sector
			that caused the failure. Data file open/create errors occurring
			while processing a position report the current block. The field
			is empty when the error cannot be associated with a specific
			position, such as for close errors.
		<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 error`,
			`Data error at position <pos>, diff bits <diff>/<bits>`).

	=parity_error[_io|_data]:<block>:<level>:<msg>
		Logs errors affecting parity.

		With no suffix, `parity_error` indicates a soft or logical error
		not classified as a hardware I/O or silent data error.

		_io - Indicates a physical Input/Output error, typically
			signaling a failing sector, device, or cable issue.
		_data - Indicates data that was read successfully but failed
			the parity verification, signaling `silent` corruption.
		<block> - The zero-based SnapRAID parity position associated with
			the error (uint). Parity open/create errors report block 0 as
			a retry marker; this does not mean that parity block 0 is bad.
			Parity access is attempted again by subsequent commands. The
			field is empty when the error cannot be associated with a
			specific position, such as for close errors.
		<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., `Open/Read/Write error`,
			`Data error, diff bits <diff>/<bits>`).

	=hardlink_error[_io]:<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[_io]:<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[_io]:<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).